net.sf.jguiraffe.gui.cmd
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 Summary

void	addQueueListener(CommandQueueListener l) Adds a new listener to this queue.
void	execute(Command cmd) Adds a new Command object to this queue.
GUISynchronizer	getGUISynchronizer() Returns the GUISynchronizer that is used by this command queue.
boolean	isPending() Checks if there are commands to be executed or in execution.
boolean	isShutdown() Returns a flag if shutdown() was called.
void	removeQueueListener(CommandQueueListener l) Removes the specified event listener from this command queue.
void	setGUISynchronizer(GUISynchronizer sync) Sets the GUISynchronizer to be used by this command queue.
void	shutdown(boolean immediate) Initiates the shutdown sequence.

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:

java.lang.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:

java.lang.IllegalArgumentException - if the command is null

java.lang.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