com.jbbres.lib.actions.tools.elements
Class SimpleAction<I,O>

java.lang.Object
  com.jbbres.lib.actions.tools.elements.SimpleElement
      com.jbbres.lib.actions.tools.elements.SimpleAction<I,O>

All Implemented Interfaces:

Action, ActionService, Element, ElementService

public abstract class SimpleAction<I,O>
extends SimpleElement
implements Action, ActionService

This abstract class provides default implementations for most of the methods in the Action interface.

Contrary to AbstractAction, SimpleAction does not requires to be associated to a separate ActionService object, as this implementation of Action also implements ActionService.

SimpleAction is a parameterized abstract class with two type variables, which means that all implementation of this class requires two type arguments:

1. The first argument (I) represents the type of object that the action accepts as an input.
2. The second argument is the type of object that the action generates as a result.

If an action does not have to deal with the input data handed it – for example, its role is to select some items in the file system – the first parameterized argument should be java.lang.Void. On the opposite, if the action is able to handle any type of input data, the first parameterized argument will be java.lang.Object.java.lang.Void means that the action is not expected returning a result. java.lang.Object informs that the result of the action can be any type of object.

A particular case in action is a service not receiving input nor generating result. Following the convention, such a service should extend SimpleAction<java.lang.Void, java.lang.Void>. Action(s) will recognize this specific case and will route the flow of data around the action.

For more information on how to create your own actions, consult the Action(s) Developer Guide or visit http://app.jbbres.com/actions/developers/.

Since:

1.0.0

Version:

1.0.0

Author:

Jean-Baptiste Bres

Constructor Summary

SimpleAction(Workflow workflow)
Instantiates a new simple action.

Method Summary

void	addExecutionListener(ActionExecutionListener l) Adds a listener to the execution.
abstract O	execute(I input) Executes the action.
java.lang.Object	execute(java.lang.Object input, Parameters parameters) Executes the action.
void	fireActionExecutionEnd(int status, java.lang.Object input, Parameters parameters, java.lang.Object result) Calls the actionExecutionEnds() method of all the action listeners.
void	fireActionExecutionEnd(int status, java.lang.Object input, Parameters parameters, java.lang.Object result, java.lang.Throwable exception) Calls the actionExecutionEnds() method of all the action listeners.
void	fireActionExecutionStart(java.lang.Object input, Parameters parameters) Calls the actionExecutionStarts() method of all the action listeners.
ActionExecutionListener[]	getActionListeners() Returns the action listeners.
ActionDescription	getDescription() Returns the description of the element.
ActionService	getService() Returns the service associated to the element.
java.lang.Class<? extends java.lang.Object>	inputClass() Returns the input class.
boolean	isValidInputClass(java.lang.Class<? extends java.lang.Object> clazz) Returns true if an instance of the given class is an acceptable input.
java.lang.Class<? extends java.lang.Object>	outputClass() Returns the output class.
java.lang.Class<? extends java.lang.Object>	outputClass(java.lang.Class<? extends java.lang.Object> inputClazz) Returns the class of the object returned by the execute method, depending on the class of the object received as an input.
void	removeExecutionListener(ActionExecutionListener l) Removes a listener to the execution.

Methods inherited from class com.jbbres.lib.actions.tools.elements.SimpleElement

getWorkflow

Methods inherited from class java.lang.Object

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

Methods inherited from interface com.jbbres.lib.actions.elements.Action

getUI

Methods inherited from interface com.jbbres.lib.actions.elements.Element

getParameters, setParameters

Constructor Detail

SimpleAction

public SimpleAction(Workflow workflow)

Instantiates a new simple action.

Parameters:

workflow - the workflow

Method Detail

getService

public ActionService getService()

Description copied from interface: Element

Returns the service associated to the element. The service describes how the element performs within the workflow. For example, if the element is an action, the service will contain the executable methods that the action is designed to perform. If the element is a variable, the service will contain methods related to data access.

Specified by:

getService in interface Action

Specified by:

getService in interface Element

Overrides:

getService in class SimpleElement

Returns:

the service associated to the element.

See Also:

ElementService

execute

public abstract O execute(I input)
                   throws ActionExecutionException

Executes the action. This method is called during the workflow execution.

The executeAction method has one parameter input: it contains (in most instances) the output of the previous action in the workflow; it is almost always in the form of a list. The type of input is the first parameterized argument of the service class. Remember that if the previous action result is not compatible, or if this action is the first one in the workflow, the input parameter will be null. Make sure that you handle this case properly to avoid a NullPointerException.

The method returns an output, which should be an object compatible second parameterized argument of the class. The method should always return an output, even if it is null or the input object.

Most action services operate on the input data given them from the previous action. Action(s) includes an internal technology called Smart-Casting that converts, when possible, the output of an action into an acceptable input type for the next action. For example, if an action returning an Image is followed by an action that requires a File, Action(s) will create a temporary file containing the image result of the first action and pass it as the input of the second action. Smart-Casting can also convert a single object into an array to ensure action’s compatibility. This means that, as a developer, you do not have to worry too much about the type of object you receive as an input or generate as an output.

The input object and the output object for an action are almost always array objects. This is why many action services implement executeAction using the following general approach:

1. Prepare an output array for later use.
2. Iterate through the elements of the input array and for each perform whatever operation is required and write the resulting data item to the output array.
3. Return the output array.

 public String[] executeAction(final File[] input)
                throws ActionExecutionException {
        if (input == null)
                return null;
 
        final String[] result = new String[input.length];
 
        for (int i = 0; i < input.length; i++) {
                try {
                        final FileInputStream fis = new FileInputStream(f);
                        final FileChannel fc = fis.getChannel();
                        final long sz = fc.size();
                        final MappedByteBuffer bb = fc.map(FileChannel.MapMode.READ_ONLY,
                                        0, sz);
 
                        final Charset charset = Charset.forName("ISO-8859-1");
                        final CharsetDecoder decoder = charset.newDecoder();
                        final CharBuffer cb = decoder.decode(bb);
 
                        result[i] = cb.toString();
                        fc.close();
                        fis.close();
                } catch (final IOException e) {
                        throw new ActionExecutionException(e);
                }
        }
        return result;
 }
 

If your action service encounters an error that prevents it from proceeding, it should give information describing the error to Action(s), which then stops executing the workflow and displays an error message.
To report errors, you must throw an ActionExecutionException exception. In the example above, you can see how the code stops and informs Action(s) if an I/O exception occurs when trying to read the file.

An action service has only two restrictions related to its implementation of executeAction:

1. It cannot return until it has completely finished whatever processing it has initiated. For instance, if an action instructs a camera to take a picture (an asynchronous process) it cannot return from executeAction method until the picture is taken. So the action has to implement whatever blocking algorithm, timeout logic, or threading strategy is necessary until the picture is taken.
2. The second restriction has to do with Action(s)’s threading architecture. Because executeAction is run on a secondary thread, if they want to display a dialog window it must be done on the main thread. Especially, javax.swing.JDialog and javax.swing.JOptionPane objects require a dialog owner to display correctly. The getWorkflow().dialogOwner() method is adequate for this purpose; for example:
   JOptionPane.showInputDialog (getWorkflow().dialogOwner(), “Input a text�?, “default text�?);

Parameters:

input - - in most instances, the output of the previous action in the workflow; it is almost always in the form of a list. In some cases, if the previous action result is not compatible or if this action is the first one in the workflow, the input parameter will be null. Make sure that you handle this case properly to avoid a NullPointerException.

Returns:

the output.

Throws:

ActionExecutionException - if the execution failed

execute

public final java.lang.Object execute(java.lang.Object input,
                                      Parameters parameters)
                               throws ActionExecutionException

Description copied from interface: ActionService

Executes the action. This method is called during the workflow execution.

The method receives as an input the result of the previous action in the workflow, casted in the input type of the action. As it might appends that the action is the first one of the workflow, or that the previous one did not generate an output compatible with the expected input of this one, the value received as a parameter might be null. The method should handle this case in order to avoid workflow execution errors.

This method returns the result of the execution, which will be used as input of the next action. Action(s) considers that the execution of the action is successful if no exception is raised during its execution. If the result of this function is null, it will be considered as successful and the workflow will continue its execution.

An ActionExecutionException means that the action failed during its execution. Such an exception (and any other exception) will result in ending the workflow execution.

If the action is not supposed to return any output (result of the ActionService.outputClass(Class) method is Void), it returns a null object.

Specified by:

execute in interface ActionService

Parameters:

input - - the result of the previous action

parameters - - the settings related to this action, to apply for this execution.

Returns:

the output to be used as input of the next action

Throws:

ActionExecutionException - - if the execution failed

inputClass

public java.lang.Class<? extends java.lang.Object> inputClass()

Returns the input class.

Returns:

the input class.

outputClass

public java.lang.Class<? extends java.lang.Object> outputClass()

Returns the output class.

Returns:

the output class.

outputClass

public java.lang.Class<? extends java.lang.Object> outputClass(java.lang.Class<? extends java.lang.Object> inputClazz)

Description copied from interface: ActionService

Returns the class of the object returned by the execute method, depending on the class of the object received as an input.

Specified by:

outputClass in interface ActionService

Parameters:

inputClazz - - the class of the object that will be received as an input

Returns:

the class of the object returned by the execute method

See Also:

ActionService.isValidInputClass(Class)

isValidInputClass

public boolean isValidInputClass(java.lang.Class<? extends java.lang.Object> clazz)

Description copied from interface: ActionService

Returns true if an instance of the given class is an acceptable input.

Specified by:

isValidInputClass in interface ActionService

Parameters:

clazz - - the tentative class

Returns:

true if an instance of the given class is an acceptable input. false otherwise.

See Also:

ActionService.outputClass(Class)

getDescription

public ActionDescription getDescription()

Description copied from interface: Element

Returns the description of the element. The description is a dictionary derived from the element description, usually the information specified in the element information property list.

Specified by:

getDescription in interface Action

Specified by:

getDescription in interface Element

Overrides:

getDescription in class SimpleElement

Returns:

the description of the element.

See Also:

ElementDescription

addExecutionListener

public void addExecutionListener(ActionExecutionListener l)

Description copied from interface: ActionService

Adds a listener to the execution.

Specified by:

addExecutionListener in interface ActionService

Parameters:

l - - new listener.

See Also:

ActionService.removeExecutionListener(ActionExecutionListener)

removeExecutionListener

public void removeExecutionListener(ActionExecutionListener l)

Description copied from interface: ActionService

Removes a listener to the execution.

Specified by:

removeExecutionListener in interface ActionService

Parameters:

l - - listener to remove

See Also:

ActionService.addExecutionListener(ActionExecutionListener)

getActionListeners

public ActionExecutionListener[] getActionListeners()

Returns the action listeners.

Returns:

the action listeners

fireActionExecutionStart

public void fireActionExecutionStart(java.lang.Object input,
                                     Parameters parameters)
                              throws ActionExecutionException

Calls the actionExecutionStarts() method of all the action listeners.

Parameters:

input - the input

parameters - the parameters

Throws:

ActionExecutionException - the action exception

fireActionExecutionEnd

public void fireActionExecutionEnd(int status,
                                   java.lang.Object input,
                                   Parameters parameters,
                                   java.lang.Object result)
                            throws ActionExecutionException

Calls the actionExecutionEnds() method of all the action listeners.

Parameters:

status - - the status of the action (SUCCEED or FAILED)

input - - the input object

parameters - - the parameters

result - - the result object

Throws:

ActionExecutionException - the action exception

fireActionExecutionEnd

public void fireActionExecutionEnd(int status,
                                   java.lang.Object input,
                                   Parameters parameters,
                                   java.lang.Object result,
                                   java.lang.Throwable exception)
                            throws ActionExecutionException

Calls the actionExecutionEnds() method of all the action listeners.

Parameters:

status - - the status of the action (SUCCEED or FAILED)

input - - the input object

parameters - - the parameters

result - - the result object

exception - - the exception that occurs during the execution

Throws:

ActionExecutionException - the action exception