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

java.lang.Object
  com.jbbres.lib.actions.tools.elements.AbstractElementService
      com.jbbres.lib.actions.tools.elements.AbstractActionService<I,O>

Type Parameters:

I - - represents the type of object that the action accepts as an input.

O - - represents the type of object that the action generates as a result.

All Implemented Interfaces:

ActionService, ElementService

public abstract class AbstractActionService<I,O>
extends AbstractElementService
implements ActionService

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

AbstractActionService 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.

For example, if your action is supposed to receive an array of file objects ( File[]) and return a text (String), the content of your service class file will look like the following example:

 package packageName;
 
 import java.io.File;
 import com.jbbres.lib.actions.elements.*;
 import com.jbbres.lib.actions.tools.elements.*;
 
 public class ActionNameService extends AbstractActionService<File[], String> {
        public ActionNameService(AbstractAction parent) {
                super(parent);
        }
 
        public String executeAction(File[] input, Parameters parameters)
                        throws ActionExecutionException {
                // The logic for the action goes here
                return "Result of the action";
        }
 }
 
 

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 AbstractActionService<java.lang.Void, java.lang.Void>. Action(s) will recognise this specific case and will route the flow of data around the action.

Release Notes:

v1.1.0:

Improved outputClass() and outputClass(Class) methods

Since:

1.0.0

Version:

1.1.0

Author:

Jean-Baptiste Bres

Constructor Summary

AbstractActionService(AbstractAction parent)
Instantiates a new action service.

Method Summary

void	addExecutionListener(ActionExecutionListener l) Adds a listener to the execution.
java.lang.Object	execute(java.lang.Object input, Parameters parameters) Executes the action.
abstract O	executeAction(I input, Parameters parameters) Executes the action.
void	fireActionExecutionEnd(int status, java.lang.Object input, Parameters parameters, java.lang.Object result) Calls the actionExecutionEnded(ActionExecutionEvent) method of all the listeners.
void	fireActionExecutionEnd(int status, java.lang.Object input, Parameters parameters, java.lang.Object result, java.lang.Throwable exception) Calls the actionExecutionEnded(ActionExecutionEvent) method of all the listeners.
void	fireActionExecutionStart(java.lang.Object input, Parameters parameters) Calls the actionExecutionStarted(ActionExecutionEvent) method of all the listeners.
ActionExecutionListener[]	getActionExecutionListeners() Returns the listeners.
java.lang.Class<? extends java.lang.Object>	inputClass() Returns the class of accepted input objects.
boolean	isValidInputClass(java.lang.Class<? extends java.lang.Object> clazz) Returns true if an instance of the given class is an valid input.
java.lang.Class<? extends java.lang.Object>	outputClass() Returns the class of generated output objects.
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.AbstractElementService

getDescription, getParent, getWorkflow

Methods inherited from class java.lang.Object

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

Constructor Detail

AbstractActionService

public AbstractActionService(AbstractAction parent)

Instantiates a new action service.

Parameters:

parent - - the parent action

Method Detail

executeAction

public abstract O executeAction(I input,
                                Parameters parameters)
                         throws ActionExecutionException

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

The executeAction method has two parameters, input, and parameters.

• The input parameter 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 parameters parameter contains the settings made in the action’s user interface.

The method finally 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, final Parameters parameters)
                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.

parameters - - the settings made in the action’s user interface.

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 class of accepted input objects.

Returns:

the class of accepted input objects.

outputClass

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

Returns the class of generated output objects.

Returns:

the class of generated output objects.

outputClass

public 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.

Specified by:

outputClass in interface ActionService

Parameters:

inputClazz - - the input class

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)

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

Specified by:

isValidInputClass in interface ActionService

Parameters:

clazz - - the class to test

Returns:

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

See Also:

ActionService.outputClass(Class)

fireActionExecutionStart

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

Calls the actionExecutionStarted(ActionExecutionEvent) method of all the listeners.

Parameters:

input - - the input

parameters - - the parameters

Throws:

ActionExecutionException - if an exception occurs

fireActionExecutionEnd

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

Calls the actionExecutionEnded(ActionExecutionEvent) method of all the 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 actionExecutionEnded(ActionExecutionEvent) method of all the 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

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)

getActionExecutionListeners

public ActionExecutionListener[] getActionExecutionListeners()

Returns the listeners.

Returns:

the listeners