org.inria.ns.reflex.processor.core
Class AbstractAction

java.lang.Object
  org.inria.ns.reflex.processor.core.AbstractAction

All Implemented Interfaces:

Executable, Presentable, NamespaceContextFactory

Direct Known Subclasses:

AbstractAction.UselessAction, AbstractFeedAction, AbstractSetAction, AbstractStepAction, ActiveSchemaAction, ActiveSheetAction, AlternativeAction, ApplyRulesAction, BlockAction, BreakAction, CallAction, ChooseAction, ClearAction, CloseAction, CommitAction, ComplexOperationAction, ContinueAction, ConversationAction, CookieAction, CopyAction, DeleteAction, DisconnectAction, EchoAction, ExitAction, ExportsAction, FallbackAction, FlushAction, ForwardAction, GroupAction, IfAction, InactiveTagsAction, InitAction, InvokeAction, KeepAction, LiteralTextAction, LoopAction, MacroAction, MacroInvokerAction, MainAction, MappingAction, ModuleAction, NoAction, NopAction, OperationsAction, RenameAction, RollbackAction, RuleAction, SaveAction, ServiceAction, SetItemAction, SetParameterAction, SetXMLAttribute, SimpleOperationAction, SleepAction, SubmitAction, UseAction, ValidateAction, WriteAction

public class AbstractAction
extends Object
implements Executable, NamespaceContextFactory, Presentable

Base support for all active tags.

All actions are derived from this class.
This class is also the entry point for unmarshalling. Each specific action should be built by unmarshalling an XML document.
An action is processed by using its run(DataSet) method.

Custom actions classes

Notice that each class that extends AbstractAction must define a constructor that calls AbstractAction's constructor.

 /**
  * Create a new instance of FooAction.
  * @param node The node from which the action has been unmarshalled.
  * Used for namespace prefix resolution when performing XPath expressions.
  * @param parent The action depending from.
  * /
 public class FooAction extends AbstractAction {
     public FooAction(Node node, AbstractAction parent) {
         super(node, parent);
     }
 }
 

Implementation details : subactions stability

Usually, an action contains a set of subactions to run. Sometimes, several of these subactions have to be removed, because they can't be applied to the runtime context. This is done in two step :

• the action to removed is replaced by a UselessAction.
• when a UselessAction is invoked, it tries to invoke the inner class AbstracAction.Organizer to clean all UselessActions from the set of actions, by copying all the actions except those to remove (thus, removing an action became thread safe).

The AbstracAction.Organizer is a singleton that works as a background task.
All action set will gain stability and efficiency after a few invokations.

Author:

Philippe Poulard

See Also:

org.inria.ns.reflex.processor

Nested Class Summary

class	AbstractAction.ParameterAdapter A class used to find the parameters set when performing subactions, and use them on behalf of any component.
static class	AbstractAction.UselessAction An action that does nothing except trying to reorganize the set of actions that is depending from.

Field Summary

Vector	actions The dependent subactions.
AbstractAction	parent The action that is depending from.
ProcessorInstance	processorInstance The processor instance that own this action.

Constructor Summary

AbstractAction(Node node, AbstractAction parent)
Create a new instance of AbstractAction.

Method Summary

void	addAction(AbstractAction action) Adds the AbstractAction to the child list of the current action.
void	addFallbackAction(Fallback fallback) Add a fallback action.
XPathContext	createContext(DataSet dataSet) Create a context based : on this action for mapping namespace URIs, on the given data set for resolving variables, on its processor instance's module bindings for resolving XPath functions.
CanonicalPath	getCanonicalPath() Return the canonical path that lead to this action.
Fallback	getFallbackAction(QName id) Return a fallback action.
Fallback	getLocalFallbackAction(QName id) Return the fallback action defined locally by this action.
Logger	getLogger() Returns the logger used by the processor.
NamespaceContext	getNamespaceContext() Get the namespace context used by this action.
Node	getNode() Returns the node from which the action has been unmarshalled.
AbstractAction	getParent() Returns the action from which the current one depends.
boolean	recover(DataSet dataSet, Exception e) Try to recover an error with a fallback action.
boolean	recover(DataSet dataSet, RecoverableException re) Try to recover an error with a fallback action.
void	removeFallbackAction(QName fallbackId) Remove a fallback action.
void	reorganize(boolean reorganization) Set the reorganization indicator.
void	run(DataSet dataSet) A wrapper that executes the action safely ; this method simply calls runAction(DataSet).
void	runAction(DataSet dataSet) Execute the action by doing what the action was intending for.
void	runActions(DataSet dataSet) Execute the action by processing all dependant actions sequentially.
StringBuffer	toPrettyString() Return the pretty print representation of this action.
StringBuffer	toPrettyString(StringBuffer buf) Return the pretty print representation of this action.
String	toString() Return this action as a string.
static AbstractAction	unmarshal(AbstractAction parent, Element element) XML unmarshaller for AbstractAction.

Methods inherited from class java.lang.Object

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

Field Detail

actions

public Vector actions

The dependent subactions.

parent

public AbstractAction parent

The action that is depending from.

processorInstance

public ProcessorInstance processorInstance

The processor instance that own this action.

Constructor Detail

AbstractAction

public AbstractAction(Node node,
                      AbstractAction parent)

Create a new instance of AbstractAction.

Parameters:

node - The node from which the action has been unmarshalled. Used for namespace prefix resolution when performing XPath expressions.

parent - The action depending from.

Method Detail

unmarshal

public static AbstractAction unmarshal(AbstractAction parent,
                                       Element element)
                                throws XMLException

XML unmarshaller for AbstractAction. Are unmarshalled the child nodes of the element given.

*** Each active tag to unmarshal must return a non-null instance of its class ; if necessary, use NoAction instead of null that would cause an exception because at this stage, the underlying active tag must exist. ***

Parameters:

parent - The non-null action depending from.

element - The XML element to unmarshall.

Returns:

The parent action (the same as the argument given, but that may contain active tags)

Throws:

XMLException - When the element and its content is not those expected.

See Also:

NoAction

reorganize

public void reorganize(boolean reorganization)

Set the reorganization indicator.

Parameters:

reorganization - true if the actions are currently reorganized, false otherwise.

getLogger

public Logger getLogger()

Returns the logger used by the processor.

Returns:

The logger used by the processor.

getNode

public Node getNode()

Returns the node from which the action has been unmarshalled.

Returns:

The node from which the action has been unmarshalled.

getParent

public AbstractAction getParent()

Returns the action from which the current one depends.

Returns:

The action from which the current one depends.

addAction

public void addAction(AbstractAction action)

Adds the AbstractAction to the child list of the current action. The child may retrieved its parent with the parent property. Special registration for Fallback action, which is not added to the subactions list.

*** If overriden, the subactions won't be added and the fallback actions won't be processed. Usually, a custom implementation of this method requires a call to super.addAction(). ***

Parameters:

action - The child action to add, or to register as a fallback action.

addFallbackAction

public void addFallbackAction(Fallback fallback)

Add a fallback action.

Parameters:

fallback - The action to add.

See Also:

getFallbackAction(QName)

removeFallbackAction

public void removeFallbackAction(QName fallbackId)

Remove a fallback action.

Parameters:

fallbackId - The ID of the action to remove.

See Also:

addFallbackAction(Fallback)

getFallbackAction

public Fallback getFallbackAction(QName id)

Return a fallback action.

If this action defines a fallback action with the ID given, it will be returned ; otherwise, if its parent defines a fallback action with the ID given, it will be returned ; otherwise, it will use the default fallback action if it defines one, or the default fallback action of its parent.

Any action may define a default fallback action ; the fallback action of an action that has no ID is the default fallback action.

See <xcl:fallback>.

Parameters:

id - The ID of the fallback action to retrieve, or null.

Returns:

The fallback action that has the ID expected if any, or null.

See Also:

addFallbackAction(Fallback), #getFallbackAction(), LogicAction

getLocalFallbackAction

public Fallback getLocalFallbackAction(QName id)

Return the fallback action defined locally by this action. No lookup is performed on the parent.

Parameters:

id - The ID of the fallback action to get, maybe null.

Returns:

The fallback action that has the ID given.

See Also:

getFallbackAction(QName)

recover

public boolean recover(DataSet dataSet,
                       Exception e)
                throws ExecutionException

Try to recover an error with a fallback action.

Parameters:

dataSet - The data set in use.

e - The exception to recover, which is assimilable to a recoverable exception which ID is the class name of the exception given.

Returns:

true if a fallback action was used to recover the error, false otherwise.

Throws:

ExecutionException - If an exception occurs while running the fallback action.

See Also:

recover(DataSet, RecoverableException)

recover

public boolean recover(DataSet dataSet,
                       RecoverableException re)
                throws ExecutionException

Try to recover an error with a fallback action.

Parameters:

dataSet - The data set in use.

re - The exception to recover.

Returns:

true if a fallback action was used to recover the error, false otherwise.

Throws:

ExecutionException - If an exception occurs while running the fallback action.

run

public final void run(DataSet dataSet)
               throws ExecutionException

A wrapper that executes the action safely ; this method simply calls runAction(DataSet).

runAction(DataSet) is invoked with safe exception processing, that is to say that :

• recoverable exceptions are recovered with a fallback action if this action or its ancestor defines one.
• unrecoverable exceptions are transmitted.

User defined processes should be defined in the runAction(DataSet) method.

Specified by:

run in interface Executable

Parameters:

dataSet - The set of datas used when the action is running.

Throws:

ExecutionException - If the action can't be performed.

See Also:

RecoverableException, UnrecoverableException, Fallback

runAction

public void runAction(DataSet dataSet)
               throws ExecutionException,
                      XPathException

Execute the action by doing what the action was intending for.

A specific subclasse may override this method to perform specific processing. The default behaviour is to call runActions(DataSet). If this behaviour doesn't suit an action, this method must be overriden. Particularly, although this behaviour suits procedural-oriented actions, it may not suit for declarative-oriented actions.

If this method is overriden, the implementation must process abnormal exceptions. Other exceptions (ExecutionExceptions) are processed by the run(DataSet) method.

This method should not be called directly : users should call the run(DataSet) method that wraps this method for exception processing and recovering.

Parameters:

dataSet - The set of datas used when the action is running.

Throws:

ExecutionException - If the action can't be performed.

XPathException

runActions

public final void runActions(DataSet dataSet)
                      throws ExecutionException,
                             XPathException

Execute the action by processing all dependant actions sequentially. If runAction(DataSet) is not overriden by an implementation of this class, it will call this method.

Parameters:

dataSet - The set of datas used when the action is running.

Throws:

ExecutionException - If the action can't be performed.

XPathException

createContext

public XPathContext createContext(DataSet dataSet)

Create a context based :

• on this action for mapping namespace URIs,
• on the given data set for resolving variables,
• on its processor instance's module bindings for resolving XPath functions.

Parameters:

dataSet - The data set to use by the context.

Returns:

An XPath context.

See Also:

DataSet.createContext(NamespaceContextFactory)

getNamespaceContext

public NamespaceContext getNamespaceContext()

Get the namespace context used by this action.

Specified by:

getNamespaceContext in interface NamespaceContextFactory

Returns:

The namespace context used by this action.

getCanonicalPath

public CanonicalPath getCanonicalPath()

Return the canonical path that lead to this action.

Returns:

The canonical path of the underlying node.

toPrettyString

public StringBuffer toPrettyString()

Return the pretty print representation of this action.

Specified by:

toPrettyString in interface Presentable

Returns:

The location of this action and its canonical path.

See Also:

toPrettyString(StringBuffer), Presentable.toPrettyString()

toPrettyString

public StringBuffer toPrettyString(StringBuffer buf)

Return the pretty print representation of this action.

Specified by:

toPrettyString in interface Presentable

Parameters:

buf - The buffer to append to.

Returns:

The location of this action and its canonical path.

See Also:

Presentable.toPrettyString(java.lang.StringBuffer)

toString

public String toString()

Return this action as a string.

Overrides:

toString in class Object

Returns:

The string representation of this action.

See Also:

toPrettyString()