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

java.lang.Object
  extended by 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 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 :

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 :

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()