net.sf.jguiraffe.gui.cmd

Class CommandQueueImpl

java.lang.Object

net.sf.jguiraffe.gui.cmd.CommandQueueImpl

All Implemented Interfaces:

CommandQueue

public class CommandQueueImpl
extends Object
implements CommandQueue

A command queue implementation for GUI applications.

This class maintains a queue, in which Command objects can be inserted by an application. At least one worker thread monitors the queue and executes the commands.

In an application usually the execute() method is of most importance. Here new Command objects are passed. Then the application need not bother about execution of these commands in a background thread. The other methods will be used by worker threads to obtain commands and send notifications about executed commands.

Version:

$Id: CommandQueueImpl.java 205 2012-01-29 18:29:57Z oheger $

Author:

Oliver Heger

Constructor Summary

Constructors

Constructor and Description
CommandQueueImpl(GUISynchronizer sync) Creates a new instance of CommandQueue and initializes it with the GUISynchronizer.
CommandQueueImpl(GUISynchronizer sync, ExecutorService execSrvc) Creates a new instance of CommandQueueImpl and initializes it with the GUISynchronizer and the ExecutorService to be used.

Method Summary

Modifier and Type	Method and Description
void	addQueueListener(CommandQueueListener l) Adds an event listener to this queue.
protected Runnable	createTask(Command cmd) Creates a task object for executing the passed in command.
void	execute(Command cmd) Executes the specified command object.
protected void	fireQueueEvent(Command cmd, CommandQueueEvent.Type eventType) Notifies all registered listeners about a change in the state of this queue.
ExecutorService	getExecutorService() Returns the ExecutorService used by this command queue.
GUISynchronizer	getGUISynchronizer() Returns the GUISynchronizer.
boolean	isPending() Tests whether there are commands that have not been executed.
boolean	isShutdown() Tests whether this command queue was shutdown.
void	processingFinished(Command cmd) This method is called by a worker thread if a command has been executed.
void	removeQueueListener(CommandQueueListener l) Removes the specified event listener from this queue.
void	setGUISynchronizer(GUISynchronizer sync) Sets the GUISynchronizer.
void	shutdown(boolean immediate) Shuts down this command queue.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

CommandQueueImpl

public CommandQueueImpl(GUISynchronizer sync)

Creates a new instance of CommandQueue and initializes it with the GUISynchronizer. A default ExecutorService will be created.

Parameters:

sync - the GUI synchronizer object (must not be null)

Throws:

IllegalArgumentException - if a required parameter is missing

CommandQueueImpl

public CommandQueueImpl(GUISynchronizer sync,
                        ExecutorService execSrvc)

Creates a new instance of CommandQueueImpl and initializes it with the GUISynchronizer and the ExecutorService to be used.

Parameters:

sync - the GUISynchronizer (must not be null)

execSrvc - the ExecutorService (must not be null)

Throws:

IllegalArgumentException - if a required parameter is missing

Method Detail

getGUISynchronizer

public GUISynchronizer getGUISynchronizer()

Returns the GUISynchronizer.

Specified by:

getGUISynchronizer in interface CommandQueue

Returns:

the GUI synchronizer

setGUISynchronizer

public void setGUISynchronizer(GUISynchronizer sync)

Sets the GUISynchronizer.

Specified by:

setGUISynchronizer in interface CommandQueue

Parameters:

sync - the GUI synchronizer (must not be null)

Throws:

IllegalArgumentException - if the synchronizer is null

getExecutorService

public ExecutorService getExecutorService()

Returns the ExecutorService used by this command queue.

Returns:

the executor service

addQueueListener

public void addQueueListener(CommandQueueListener l)

Adds an event listener to this queue.

Specified by:

addQueueListener in interface CommandQueue

Parameters:

l - the listener to add (must not be null)

Throws:

IllegalArgumentException - if the listener is undefined

removeQueueListener

public void removeQueueListener(CommandQueueListener l)

Removes the specified event listener from this queue.

Specified by:

removeQueueListener in interface CommandQueue

Parameters:

l - the listener to remove

execute

public void execute(Command cmd)

Executes the specified command object. This implementation calls createTask() to create a task object for actually executing the command. This task is then passed to the ExecutorService, so it will be processed by a background thread.

Specified by:

execute in interface CommandQueue

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

processingFinished

public void processingFinished(Command cmd)

This method is called by a worker thread if a command has been executed.

Parameters:

cmd - the command that has been processed

isPending

public boolean isPending()

Tests whether there are commands that have not been executed. This implementation uses a counter that keeps track of the scheduled commands (i.e. the number of commands passed to the execute() method) that have not yet been completed.

Specified by:

isPending in interface CommandQueue

Returns:

a flag whether there are pending commands

isShutdown

public boolean isShutdown()

Tests whether this command queue was shutdown. This information can be obtained from the underlying executor service.

Specified by:

isShutdown in interface CommandQueue

Returns:

a flag whether shutdown() was called

shutdown

public void shutdown(boolean immediate)

Shuts down this command queue. For this implementation, a shutdown means that the underlying executor has to be shut down. Depending on the boolean parameter this method will block until the executor service's shutdown is complete.

Specified by:

shutdown in interface CommandQueue

Parameters:

immediate - a flag whether an immediate shutdown should be performed

fireQueueEvent

protected void fireQueueEvent(Command cmd,
                              CommandQueueEvent.Type eventType)

Notifies all registered listeners about a change in the state of this queue.

Parameters:

cmd - the affected command

eventType - the type of the event to fire

createTask

protected Runnable createTask(Command cmd)

Creates a task object for executing the passed in command. This task will then be passed to the ExecutorService.

Parameters:

cmd - the command to be executed

Returns:

the task for executing this command