es.iac.ing.codeso.action.server
Interface iActionHandler

All Known Implementing Classes:

DefaultActionHandler

public interface iActionHandler

Describes the capabilities that must be offered by any class which wishes to handle the invocation of an action.

The following methods are defined:

1. validateArguments - performs additional validation of the action invocation arguments.
2. validateSystem - checks the underlying system being controlled is able to accept a new invocation request.
3. waitForSystemResources - waits for the underlying system to acquire the necessary resources in order to start active execution of the task.
4. execute - does whatever is required.

The CODESO framework will execute these methods in the sequence shown in the list above until either a) the sequence is complete or b) some exception is raised.

The DefaultActionHandler provides a default implementation for this interface and may be extended by the user to override only those methods which are required.

Nested Class Summary

static class	iActionHandler.ActionAbortException An exception which is raised if an attempt to abort an action is unsuccessful.
static class	iActionHandler.ActionExecutionException An exception which should be raised by the client action handler code if it wishes to prematurely abort the handling of an action due to some unexpected problem.
static class	iActionHandler.ActionValidationException An exception which is raised if an attempt to invoke an action is unsuccessful because either the parameters were specified incorrectly or the underlying system being controlled was in an invalid state.

Method Summary

void	abort(Action source) Causes the action handler to cancel execution of the current action in progress.
ActionResultList	execute(Action source, ActionArgumentList argumentList) Causes the action handler to execute the invocation request.
void	validateArguments(Action source, ActionArgumentList argumentList) Checks the action invocation arguments over and above the checks which are performed automatically by the CODESO framework.
void	validateSystem(Action source) Checks that the underlying system being controlled is able to perform the work, that's to say, that it isn't in an error state.
void	waitForSystemResources(Action source) This method should blocks until the action handler has acquired the necessary system resources to commence active execution of the invocation request.

Method Detail

validateArguments

void validateArguments(Action source,
                       ActionArgumentList argumentList)
                       throws iActionHandler.ActionValidationException

Checks the action invocation arguments over and above the checks which are performed automatically by the CODESO framework.

If the supplied arguments are acceptable then this method should return normally.

If the supplied arguments are not acceptable an ActionValidationException should be raised whose detail message describes the cause of the problem. This will cause the rejection of the incoming action request and the raising of the appropriate CODESO IDL-defined exception to the remote client.

This method should return quickly to ensure that remote clients receive a timely response to their asynchronous invocation requests.

The checks which the CODESO framework automatically performs (that's to say which don't need to be performed here) include:

• validation that all arguments in the list correspond to parameters which are present in the action descriptor.
• validation that arguments have been supplied for all mandatory parameters specified in the action descriptor.

Parameters:

source - reference to the Action object which has been invoked by the remote client.

argumentList - reference to the arguments which were provided by the remote client when the action was invoked.

Throws:

iActionHandler.ActionValidationException - if the parameters in the supplied argument list were not acceptable.

validateSystem

void validateSystem(Action source)
                    throws iActionHandler.ActionValidationException

Checks that the underlying system being controlled is able to perform the work, that's to say, that it isn't in an error state.

If the system is able to accept the new request then this method should return normally. Following this the action will make a transition to the PENDING state and call the waitForSystemResources method.

If the system state is not able to accept the new request an ActionValidationException should be raised whose detail message describes the cause of the problem. This will cause the rejection of the incoming action request and the raising of the appropriate CODESO IDL-defined exception to the remote client.

This method should return quickly to ensure that remote clients receive a timely response to their asynchronous invocation requests.

Parameters:

source - reference to the Action object which has been invoked by the remote client.

Throws:

iActionHandler.ActionValidationException - if the underlying system is not in a state where it can accept a new request.

waitForSystemResources

void waitForSystemResources(Action source)
                            throws java.lang.InterruptedException

This method should blocks until the action handler has acquired the necessary system resources to commence active execution of the invocation request. When this method returns the action will make a transition to the ACTIVE state and call the execute method.

Parameters:

source - reference to the Action object which has been invoked by the remote client.

Throws:

java.lang.InterruptedException - if the method was interrupted because it took too long (timed out).

execute

ActionResultList execute(Action source,
                         ActionArgumentList argumentList)
                         throws java.lang.InterruptedException,
                                iActionHandler.ActionExecutionException

Causes the action handler to execute the invocation request.

If the action completes normally the results should be returned in an ActionResultList. This will cause the associated action to make a transition to the IDLE end-state.

If for some reason the execution of the action failed then an ActionExecutionException exception should be raised. This will cause the associated action to make a transition to the ERROR end-state.

Parameters:

source - reference to the Action object which has been invoked by the remote client.

argumentList - reference to the arguments which were provided by the remote client when the action was invoked.

Returns:

reference to an object containing the results of the invocation.

Throws:

iActionHandler.ActionExecutionException - if the parameters in the argument list were not acceptable.

java.lang.InterruptedException - if the method was interrupted because it took too long (timed out).

abort

void abort(Action source)
           throws iActionHandler.ActionAbortException

Causes the action handler to cancel execution of the current action in progress.

Parameters:

source - reference to the Action object which has previously been invoked.

Throws:

iActionHandler.ActionAbortException - if the action invocation could not be cancelled.