com.glaivestone.javax.execution
Class AbstractEvaluableAction

java.lang.Object
  |
  +--com.glaivestone.javax.execution.AbstractEvaluableAction

All Implemented Interfaces:

EvaluableAction

Direct Known Subclasses:

BlockContext, ConstructorAction, MessageAction

public abstract class AbstractEvaluableAction

extends java.lang.Object

implements EvaluableAction

Abstract superclass for evaluable action implementations.

An action is configured with a receiver (the instance or class which supports the code to be executed) and a code element which defines the behavior of the action.

Argument values for evaluating an action can be provided at construction time or at evaluation time. Default message arguments can be configured for the action if the desired values are known at construction time. Actual argument values can be provided dynamically at evaluation time; arguments supplied at invocation time override any default values. In keeping with strict type checking, actions require the correct number and type of arguments to be supplied.

An action is also configured with an ExceptionHandler which is invoked if an exception occurs when the action is evaluated. The default exception handling behavior is to propagate the exception into the client context using an unchecked PropagatedException. Use of an unchecked exception is necessary so that evaluable actions can be used to configure dynamic behavior in contexts which do not necessarily have suitable declarations for checked exceptions that may occur.

Clients must consider the exception architecture of their application and define suitable handlers when using evaluable actions. The exception handler for a specific action can be configured using the setExceptionHandler message to install an alternate handler. The standard exception handler behavior for the application session can be configured by installing an alternate handler as AbstractEvaluableAction.DEFAULT_HANDLER. The latter mechanism should be used with care, however, since it is a global setting which controls the default handler configued for all actions created in the session.

Subclass Responsibilities

Subclass implementations provide for various flavors of code that is executed when the action is evaluated.

Implementation Notes

Not clear how useful the exception handler mechanism is w.r.t. allowing clients to configure arbitrary handlers. In practice, we seem to mainly just use the standard propagated exception and be done with it.

We retain the exception handler mechanism, though, despite it being a violation of overgeneralizing the design (YAGNI - You Aren't Going to Need It). It does provide a hook so that an application session could be configured with an standard exception handler which, say, reported evaluation failures to a session logging mechanism for the session.

Author:

Deb Lewis

Field Summary

static ExceptionHandler	CONTINUABLE_HANDLER An exception handler which blithely ignores problems and continues execution regardless.
static ExceptionHandler	DEFAULT_HANDLER The default exception handler for evaluable actions propagates the underlying cause of an evaluation failure as an unchecked PropagatedException which wraps the original exception.
static java.lang.Object[]	EMPTY_ARGS Arguments array for a no-arg action.
static java.lang.Class[]	EMPTY_PARM_TYPES Parameter types for a no-arg action.
static ExceptionHandler	PROPAGATING_HANDLER An exception handler which propagates the original exception by wrapping it in an unchecked PropagatedException.
static ExceptionHandler	TERMINATING_HANDLER An exception handler which abruptly terminates the session.

Method Summary

java.lang.Object	evaluate() Answer the result of evaluating the action
java.lang.Object	evaluate(java.lang.Object anArg) Answer the result of evaluating the receiver with the given argument value.
abstract java.lang.Object	evaluate(java.lang.Object[] args) Answer the result of evaluating the action with the given argument values.
java.lang.Object	evaluate(java.lang.Object arg1, java.lang.Object arg2) Answer the result of evaluating the action with the given argument values.
java.lang.Object[]	getArguments() Answer the default arguments used for evaluating the action.
int	getNumberOfArguments() Answer the number of arguments required to evaluate the action.
static java.lang.Throwable	getOriginalException(java.lang.Throwable anException) Answer the original cause of an exception.
java.lang.Object	getReceiver() Answer the object which performs the evaluation.
abstract java.lang.String	getSelector() Answer the name of the action.
void	setArguments(java.lang.Object[] arguments) Specify the default arguments used for evaluating the action.
void	setExceptionHandler(ExceptionHandler aHandler) Set the evaluation exception handler for this action.

Methods inherited from class java.lang.Object

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

Field Detail

PROPAGATING_HANDLER

public static final ExceptionHandler PROPAGATING_HANDLER

An exception handler which propagates the original exception by wrapping it in an unchecked PropagatedException.

TERMINATING_HANDLER

public static final ExceptionHandler TERMINATING_HANDLER

An exception handler which abruptly terminates the session. This is an aggressive failure handling policy which should not be used lightly.

CONTINUABLE_HANDLER

public static final ExceptionHandler CONTINUABLE_HANDLER

An exception handler which blithely ignores problems and continues execution regardless. This is a sloppy failure handling policy which should not be used lightly.

EMPTY_PARM_TYPES

public static final java.lang.Class[] EMPTY_PARM_TYPES

Parameter types for a no-arg action.

EMPTY_ARGS

public static final java.lang.Object[] EMPTY_ARGS

Arguments array for a no-arg action.

DEFAULT_HANDLER

public static ExceptionHandler DEFAULT_HANDLER

The default exception handler for evaluable actions propagates the underlying cause of an evaluation failure as an unchecked PropagatedException which wraps the original exception.

Method Detail

getOriginalException

public static java.lang.Throwable getOriginalException(java.lang.Throwable anException)

Answer the original cause of an exception. Dereferences propagated exceptions to return the underlying cause.

evaluate

public java.lang.Object evaluate()

Answer the result of evaluating the action

Specified by:

evaluate in interface EvaluableAction

See Also:

EvaluableAction.evaluate()

evaluate

public java.lang.Object evaluate(java.lang.Object anArg)

Answer the result of evaluating the receiver with the given argument value.

Specified by:

evaluate in interface EvaluableAction

See Also:

EvaluableAction.evaluate(Object)

evaluate

public java.lang.Object evaluate(java.lang.Object arg1,
                                 java.lang.Object arg2)

Answer the result of evaluating the action with the given argument values.

Specified by:

evaluate in interface EvaluableAction

See Also:

EvaluableAction.evaluate(Object, Object)

evaluate

public abstract java.lang.Object evaluate(java.lang.Object[] args)

Answer the result of evaluating the action with the given argument values.

Specified by:

evaluate in interface EvaluableAction

See Also:

EvaluableAction.evaluate(Object[])

getArguments

public java.lang.Object[] getArguments()

Answer the default arguments used for evaluating the action.

Specified by:

getArguments in interface EvaluableAction

See Also:

EvaluableAction.getArguments()

getNumberOfArguments

public int getNumberOfArguments()

Answer the number of arguments required to evaluate the action.

getReceiver

public java.lang.Object getReceiver()

Answer the object which performs the evaluation.

Specified by:

getReceiver in interface EvaluableAction

See Also:

EvaluableAction.getReceiver()

getSelector

public abstract java.lang.String getSelector()

Answer the name of the action.

Specified by:

getSelector in interface EvaluableAction

See Also:

EvaluableAction.getSelector()

setArguments

public void setArguments(java.lang.Object[] arguments)

Specify the default arguments used for evaluating the action.

Specified by:

setArguments in interface EvaluableAction

See Also:

EvaluableAction.setArguments(java.lang.Object[])

setExceptionHandler

public void setExceptionHandler(ExceptionHandler aHandler)

Set the evaluation exception handler for this action.

Specified by:

setExceptionHandler in interface EvaluableAction

See Also:

EvaluableAction.setExceptionHandler(com.glaivestone.javax.execution.ExceptionHandler)