Package net.sf.jguiraffe.gui.app

Class CommandActionTask

  • All Implemented Interfaces:
    Runnable, BeanContextClient
    public class CommandActionTask
extends Object
implements 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.

    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.) Note: When executing a builder script default converters are in place. There is also a default converter which can deal with ElementEnabler objects, so you can use an abbreviated form in most cases.

    Version:
    $Id: CommandActionTask.java 205 2012-01-29 18:29:57Z oheger $
    Author:
    Oliver Heger

    • 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 String getCommandBeanName()
        Returns the name of the command bean.
        Returns:
        the name of the command bean

      • setCommandBeanName

        public void setCommandBeanName​(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:
        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

      • 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

      • 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:
        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