net.sf.jguiraffe.gui.app
Class CommandActionTask

java.lang.Object
  net.sf.jguiraffe.gui.app.CommandActionTask

All Implemented Interfaces:

java.lang.Runnable, BeanContextClient

public class CommandActionTask
extends java.lang.Object
implements java.lang.Runnable, BeanContextClient

A specialized action task that executes a Command object.

This class can be used as a task for FormAction objects. When invoked by the associated action it will put a command object in the application's command queue. This is especially useful for longer running actions that should not block the application's event dispatch thread.

Instances can be initialized with either a concrete Command object or with the name of a command bean. In the former case the Command object will be reused each time the action is triggered. In the latter case for each invocation a bean with the specified name is queried from the current BeanContext. (This bean must implement the Command interface.)

This class implements some support for disabling and enabling UI elements during the execution of the associated command. For instance, it may make sense to disable certain actions (e.g. menu items and/or tool bar buttons) while the command is running in background. After completion of the background task these actions can be enabled again. For this purpose two ElementEnabler objects can be set: one is invoked when the associated Command is passed to the command queue for execution. The other one is triggered at the end of the Command's execution (in the event dispatch thread). The second ElementEnabler can be omitted if it is the exact counterpart of the first one.

In addition to the specification of ElementEnabler objects this class also supports a short form for defining such enablers: The setEnablerSpecification() method allows passing in a string that can be interpreted by an EnablerBuilder object. This is especially convenient if the task is declared in a builder script because the longer XML declarations for the enabler beans can be omitted. setEnablerSpecification() parses the passed in string, creates a corresponding ElementEnabler, and passes it to the setBeforeEnabler(ElementEnabler) method. So this is equivalent to setting the enabler directly.

A CommandActionTask object can be fully declared in a builder script using the capabilities of the dependency injection framework and the ActionTaskTag. Because this class implements the BeanContextClient interface the reference to the current BeanContext (which is required for accessing the central Application and also the command beans) will then be automatically set. If the object is created by hand, it lies in the responsibility of the developer to ensure that the reference to the BeanContext is correctly initialized. An example for an action declaration in a builder script making use of this class could look as follows:

 <!-- Definition of the command bean -->
 <di:bean name="commandBean" singleton="false"
   beanClass="com.acme.CommandBeanImpl"/>
 <!-- The command task used by the action -->
 <di:bean name="commandTask"
   beanClass="net.sf.jguiraffe.gui.app.CommandActionTask">
   <di:setProperty property="commandBeanName" value="commandBean"/>
   <di:setProperty property="beforeEnabler">
     <di:bean beanClass="net.sf.jguiraffe.gui.builder.enablers.ActionEnabler">
       <di:constructor>
         <di:param value="testAction"/>
       </di:constructor>
     </di:bean>
   </di:setProperty>
 </di:bean>
 <!-- The action itself -->
 <a:action name="testAction" text="Test action" taskBean="commandTask"/>
 

This script creates an action named testAction that is associated with a CommandActionTask object as its task. The task uses a Command object that is also defined as a bean. (Note that the command bean has the singleton attribute set to false, so each time the action task is executed a new instance of the command class will be created.) In this example also an ElementEnabler is defined. The way this enabler is defined, it disables the action when the task is executed and enables it again after the task's execution. (Thus the user cannot activate the action again as long as it is running.)

Version:

$Id: CommandActionTask.java 171 2009-11-21 20:30:28Z oheger $

Author:

Oliver Heger

Constructor Summary

CommandActionTask()

Method Summary

protected Command	createCommandWrapper(Command actualCommand) Creates the Command object wrapper that is passed to the Application.execute(Command) method.
protected BeanContext	fetchBeanContext() Returns the BeanContext to use and checks whether it is defined.
protected Command	fetchCommand() Obtains the command object to be executed.
ElementEnabler	getAfterEnabler() Returns the ElementEnabler that is invoked after the execution of this task.
protected Application	getApplication() Returns a reference to the global application object.
BeanContext	getBeanContext() Returns the current BeanContext.
ElementEnabler	getBeforeEnabler() Returns the ElementEnabler that is invoked before the execution of this task.
Command	getCommand() Returns the command object.
java.lang.String	getCommandBeanName() Returns the name of the command bean.
java.lang.String	getEnablerSpecification() Returns the specification of the ElementEnabler used by this task.
void	run() Executes this task.
void	setAfterEnabler(ElementEnabler afterEnabler) Sets the ElementEnabler that is invoked after the execution of this task.
void	setBeanContext(BeanContext context) Sets the current BeanContext.
void	setBeforeEnabler(ElementEnabler beforeEnabler) Sets the ElementEnabler that is invoked before the execution of this task.
void	setCommand(Command command) Sets the command object.
void	setCommandBeanName(java.lang.String commandBeanName) Sets the name of the command bean.
void	setEnablerSpecification(java.lang.String enablerSpecification) Sets the specification of the ElementEnabler to be used by this task.

Methods inherited from class java.lang.Object

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

Constructor Detail

CommandActionTask

public CommandActionTask()

Method Detail

getCommand

public Command getCommand()

Returns the command object.

Returns:

the command object

setCommand

public void setCommand(Command command)

Sets the command object. Here an object can be passed that will be reused for each invocation.

Parameters:

command - the command object to be used

getCommandBeanName

public java.lang.String getCommandBeanName()

Returns the name of the command bean.

Returns:

the name of the command bean

setCommandBeanName

public void setCommandBeanName(java.lang.String commandBeanName)

Sets the name of the command bean. If this property is set, the Command object to be executed by this task is obtained from the current BeanContext using this property as bean name. However, this property is only evaluated if no Command object was set using the setCommand(Command) method.

Parameters:

commandBeanName - the name of the command bean

getBeforeEnabler

public ElementEnabler getBeforeEnabler()

Returns the ElementEnabler that is invoked before the execution of this task. This method never returns null; if no enabler has been set explicitly, a default dummy enabler is returned.

Returns:

the ElementEnabler before the execution

setBeforeEnabler

public void setBeforeEnabler(ElementEnabler beforeEnabler)

Sets the ElementEnabler that is invoked before the execution of this task. As soon as this task is triggered, this ElementEnabler is invoked with a value of false for the enabled state argument. If no after enabler was set, it is also called after the execution of the Command - this time with a value of true for the enabled state argument.

Parameters:

beforeEnabler - the ElementEnabler before the execution

See Also:

ElementEnabler.setEnabledState(net.sf.jguiraffe.gui.builder.components.ComponentBuilderData, boolean), setAfterEnabler(ElementEnabler)

getAfterEnabler

public ElementEnabler getAfterEnabler()

Returns the ElementEnabler that is invoked after the execution of this task. This method never returns null; if no enabler has been set explicitly, a default dummy enabler is returned.

Returns:

the ElementEnabler after the execution

setAfterEnabler

public void setAfterEnabler(ElementEnabler afterEnabler)

Sets the ElementEnabler that is invoked after the execution of this task. After the command has been executed this ElementEnabler is invoked (in the event dispatch thread) with a value of true for the enabled state argument. An after enabler is only necessary if the enabling/disabling is asymmetric, i.e. before the execution different elements are enabled/disabled than after the execution. If no after enabler is set, the before enabler is invoked both before and after execution. Also note that the after enabler is always called with the value true for the enabled state argument; if a different flag value is required, an InverseEnabler can be used to switch the behavior.

Parameters:

afterEnabler - the ElementEnabler after the execution

getEnablerSpecification

public java.lang.String getEnablerSpecification()

Returns the specification of the ElementEnabler used by this task. This method just returns the string that was set using setEnablerSpecification(String). It is not in sync with an enabler set by setBeforeEnabler(ElementEnabler). This is due to the fact that it is not supported to transform an arbitrary ElementEnabler into a string specification. Therefore a call to setBeforeEnabler() causes the enablerSpecification property to be reset.

Returns:

the specification of the ElementEnabler

setEnablerSpecification

public void setEnablerSpecification(java.lang.String enablerSpecification)

Sets the specification of the ElementEnabler to be used by this task. This method provides a convenient way of defining an ElementEnabler for this task in a compact form. This is especially useful if the task is defined in a Jelly builder script. This method basically interprets the enabler specification (internally an EnablerBuilder is used for this purpose) and calls setBeforeEnabler(ElementEnabler) with the resulting object. It is possible to pass a null string; in this case the beforeEnabler is reset.

Parameters:

enablerSpecification - the specification of the ElementEnabler

getBeanContext

public BeanContext getBeanContext()

Returns the current BeanContext.

Returns:

the current BeanContext

setBeanContext

public void setBeanContext(BeanContext context)

Sets the current BeanContext. This method is usually automatically called by the dependency injection framework.

Specified by:

setBeanContext in interface BeanContextClient

Parameters:

context - the current BeanContext

run

public void run()

Executes this task. Obtains the Command object by invoking fetchCommand() and createCommandWrapper(Command) and passes it to the application.

Specified by:

run in interface java.lang.Runnable

fetchBeanContext

protected BeanContext fetchBeanContext()

Returns the BeanContext to use and checks whether it is defined. This method delegates to getBeanContext() and throws an exception if no context was set.

Returns:

the current BeanContext

Throws:

java.lang.IllegalStateException - if no BeanContext was set

getApplication

protected Application getApplication()

Returns a reference to the global application object. It is obtained through the current BeanContext.

Returns:

the application object

fetchCommand

protected Command fetchCommand()
                        throws ApplicationRuntimeException

Obtains the command object to be executed. This implementation will use the command object if one was set. Otherwise it requests the command object from the current BeanContext using the bean name specified by the commandBeanName property. If neither a Command object nor the name of a Command bean was set, an ApplicationRuntimeException exception is thrown.

Returns:

the command object to use

Throws:

ApplicationRuntimeException - if the command is not specified

InjectionException - if the command bean cannot be obtained

createCommandWrapper

protected Command createCommandWrapper(Command actualCommand)

Creates the Command object wrapper that is passed to the Application.execute(Command) method. This method is called by run() with the Command object returned by fetchCommand() as argument. Because some additional tasks have to be performed (e.g. invoking the ElementEnabler) the Command managed by this task is not directly executed. Instead, a wrapper is created around this Command, which takes care about these tasks. This method creates this wrapper.

Parameters:

actualCommand - the Command object implementing the actual logic to be executed

Returns:

a Command wrapping the actual command and performing additional housekeeping tasks