Interface CommandQueue

  • All Known Implementing Classes:
    CommandQueueImpl

    public interface CommandQueue

    Definition of an interface that describes a command queue.

    A command queue can be used by an application to execute longer-running tasks in the background without blocking the main event dispatching thread. This way the application will stay responsive. The command pattern also provides a suitable way of structuring the logic implemented in an application.

    The most important method in this interface is of course the execute() method, which allows scheduling new commands to be executed. With shutdown() the queue can be gracefully closed (commands that are contained in the queue or are currently executed will be finished before the queue actually shuts down). Further methods are available for checking the current status of the queue.

    Version:
    $Id: CommandQueue.java 127 2008-05-24 15:59:16Z oheger $
    Author:
    Oliver Heger
    • Method Detail

      • addQueueListener

        void addQueueListener​(CommandQueueListener l)
        Adds a new listener to this queue.
        Parameters:
        l - the event listener to add (must not be null)
        Throws:
        IllegalArgumentException - if the listener is undefined
      • removeQueueListener

        void removeQueueListener​(CommandQueueListener l)
        Removes the specified event listener from this command queue.
        Parameters:
        l - the listener to remove
      • getGUISynchronizer

        GUISynchronizer getGUISynchronizer()
        Returns the GUISynchronizer that is used by this command queue.
        Returns:
        the GUI synchronizer
      • setGUISynchronizer

        void setGUISynchronizer​(GUISynchronizer sync)
        Sets the GUISynchronizer to be used by this command queue. This object will be used to ensure that GUI updates performed by commands are done on the event dispatch thread.
        Parameters:
        sync - the GUI synchronizer
      • execute

        void execute​(Command cmd)
        Adds a new Command object to this queue. It will be executed as soon as the next worker thread is available.
        Parameters:
        cmd - the command to be executed (must not be null)
        Throws:
        IllegalArgumentException - if the command is null
        IllegalStateException - if shutdown() has already been called
      • isPending

        boolean isPending()
        Checks if there are commands to be executed or in execution. This method can be called for instance if the user wants to exit the application to check if there are still running command threads.
        Returns:
        a flag if there are pending commands
      • isShutdown

        boolean isShutdown()
        Returns a flag if shutdown() was called. After that no commands can be executed any more.
        Returns:
        a flag if the queue is shut down
      • shutdown

        void shutdown​(boolean immediate)
        Initiates the shutdown sequence. New commands won't be accepted any more. The boolean parameter determines the kind of shutdown: If set to false, the commands contained in the queue will still be executed, and the method blocks until everything is complete. A value of true forces an immediate shutdown (as far as this is possible for a concrete implementation).
        Parameters:
        immediate - a flag how the shutdown should be performed