org.inria.ns.reflex.processor
Class ProcessorInstance

java.lang.Object
  extended by org.inria.ns.reflex.processor.catalog.LocalCatalog
      extended by org.inria.ns.reflex.processor.ProcessorInstance
All Implemented Interfaces:
GlobalCatalog, Configurable, Initializable, Localizable, Loggable, XOperable
Direct Known Subclasses:
ReflexCLI

public class ProcessorInstance
extends LocalCatalog
implements Initializable, Configurable, Loggable, Localizable, XOperable, GlobalCatalog

The processor instance is the active form of an Active Sheet.

Prefixes disabling/enabling

When unmarshalling, prefixes may be explicitely enabled or disabled (only one of this feature is available ; see enablesPrefix(String) and disablesPrefix(String)). An element that uses a disabled prefix causes the invokation of the fallback module when unmarshalling ; that is to say that an unknown element is a litteral element, not a real action.

Attributes

The processor's own attributes are shared with all data sets. When a property is shared (scope="shared"), it is stored within the processor's attributes.

Catalogs and registries

Each processor holds its own catalog and a registry ; a catalog translates addresses while a registry stores resources .

A processor instance may be built from a parent processor instance ; in this case, it inherit its catalog and registry (in fact, it will use them according to the lookup strategy of the object to retrieve). A global catalog and registry are shared by all processor instances. They contain all the modules needed for the engine to work, the core modules, and also optional modules that RefleX implements.

When a resource is expected, it is looked up in the registry ; then the processor's catalog is involved ; finally, the resolved address is used again in the registry ; usually, the registry stores builders, so that resources are built only when expected. Once a builder is created, it is put in the registry bound to the catalog that resolves the resource.

Using a processor instance

Running a processor instance

Minimal usage :

  InputStream activeSheet = ... // an XML document
  ProcessorInstance pi = new ProcessorInstance();
  pi.unmarshal( activeSheet );
  DataSet dataSet = new DataSet( pi );
  pi.call( dataSet );
  // retrieve datas that have been stored in the data set
 

It is also possible to call a given logic procedure :

Author:
Philippe Poulard
See Also:
DataSet, Catalog, Module

Nested Class Summary
 
Nested classes/interfaces inherited from interface org.inria.ns.reflex.structures.Configurable
Configurable.Impl
 
Field Summary
static long t
           
 
Constructor Summary
ProcessorInstance()
          Create a new processor instance.
ProcessorInstance(ProcessorInstance creator)
          Create a new processor instance.
 
Method Summary
 void acquire(DataSet dataSet)
          Acquire a data set : if the data set is not belonging to this processor instance, it is removed from its list and added to this one.
 void addCatalogReference(String catalogRef)
          Adds a catalog reference to this processor instance.
 void addCatalogReference(XFile catalogRef)
          Adds a catalog reference to this processor instance.
 void addNamedLogicProcedure(AbstractAction logicProcedure, Element element, AbstractAction parent)
          Adds a logic procedure to the processor.
 void addWeakDataSet(DataSet dataSet)
          Adds a data set to the current list of data set used by this instance.
 void call(DataSet dataSet, QName logic)
          Perform the action by executing the procedure that has the name given.
 void callDefault(DataSet dataSet)
          Perform the action by executing the default procedure, that correspond to the unnamed logic procedure if any.
 void callMain(DataSet dataSet)
          Perform the action by executing the main procedure, that correspond to the root.
 boolean containsAttribute(Object key)
          Returns true if the processor's attribute set contains a mapping for the specified key.
 boolean containsProcedure(QName name)
          Returns true if the procedure exists, false otherwise.
 int countDataSets()
          Return the number of data sets known by this processor instance.
 void disablesPrefix(String prefix)
          Disables the prefix given.
 void enablesPrefix(String prefix)
          Enables the prefix given.
 Object getAttribute(Object key)
          Return an attribute that has been defined for the processor.
 Map getAttributes()
          Return the set of attributes defined for the processor.
 XFile getBaseLocation()
          Return the directory where is located this processor instance.
 Iterator getCatalogReferences()
          Get the catalog references.
 List getDataSets()
          Return the list of the data sets known by this processor instance.
 AbstractAction getDefaultAction()
          Return the default action.
 Document getDocument()
          Return the XML active sheet used for unmarshalling this processor instance.
 LocalCatalog getLocalCatalogEntry()
          Return the local catalog entry.
 XFile getLocation()
          Return the URI where is located this processor instance.
 Logger getLogger()
          Return the logger used by the processor.
 MainAction getMainAction()
          Return the main action.
 Module getModule(QName name)
          Return the module bound to the same namespace URI of the given qualified name.
 Module getModule(String nsURI)
          Return the module bound to the same namespace URI of the given qualified name.
 LocalCatalog getParent()
          Return the parent local catalog.
 AbstractAction getProcedure(QName name)
          Returns the named procedure.
 Map getProcedures()
          Returns the procedures.
 String getVersion(String moduleNsURI)
          Get the version of the module to use.
 XOperator getXOperator()
          Return the X-operator of this object.
 XPathFunctionResolver getXPathFunctionResolver()
          Return the function context used by this registry.
 boolean hasDefault()
          Indicates whether the active sheet of this processor instance has a default procedure (#default) or not.
 boolean hasParent()
          Indicates if this local catalog has a parent.
 void init()
          Display an initialization message to the log stream.
 boolean isDisabled(String prefix)
          Return true if the prefix has been disabled, false otherwise.
 boolean isEnabled(String prefix)
          Return true if the prefix has been enabled and is not disabled, false otherwise.
 boolean isExplicitelyEnabled(String prefix)
          Return true if the prefix has been explicitely enabled, false otherwise.
 boolean isLocalizable()
          Indicates whether this instance is localizable or not.
 boolean isModuleRegistered(String nsURI)
          Indicates if a namespace URI corresponds to a registered module or not.
 boolean isValidating()
          Indicates whether or not the Active Sheet will be validated.
 void mergeAttributes(Map attributes)
          Merge 2 collections of attributes.
 void removeWeakDataSet(DataSet dataSet)
          Remove a data set from the current list of data set used by this instance.
 void setAttribute(Object key, Object data)
          Define an attribute for the processor.
 void setAttributes(Map attributes)
          Set the properties shared by all data set used by this processor.
 void setCorrupted(String cause, Throwable exception, boolean logEvent)
          Indicates that this engine is corrupted.
 void setLocation(XFile location)
          Set an URI that localize this processor instance.
 void setLogger(Logger logger)
          Set the logger that the processor will use.
 void setLogger(String logFileName)
          Set the logger that the processor will use.
 void setLogLevel(Level level)
          Set the level of the current logger.
 void setLogLevel(String logLevel)
          Set the level of the current logger.
 void setMainAction(MainAction mainAction)
          Set a ready-to-use main action.
 void setValidating(boolean validating)
          Specifies that the Active Sheet will be validated.
 void setVersion(String moduleNsURI, String version)
          Set the version of the module to use.
 void unmarshal(Document activeSheet)
          Unmarshal an Active Sheet.
 void unmarshal(InputSource activeSheet)
          Unmarshal the processor from an XML file.
 void unmarshal(InputStream activeSheet)
          Unmarshal the processor from an XML stream.
 void unmarshal(Reader activeSheet)
          Unmarshal the processor from an XML character stream.
 void unmarshal(String activeSheet)
          Unmarshal the processor from an XML file.
 void unmarshal(XFile activeSheet)
          Unmarshal the processor from an XML file.
 
Methods inherited from class org.inria.ns.reflex.processor.catalog.LocalCatalog
append
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

t

public static long t
Constructor Detail

ProcessorInstance

public ProcessorInstance()
Create a new processor instance.


ProcessorInstance

public ProcessorInstance(ProcessorInstance creator)
Create a new processor instance. Its own registry is backed by those from its creator processor instance.

Parameters:
creator - The processor instance used to create this one.
Method Detail

getXPathFunctionResolver

public XPathFunctionResolver getXPathFunctionResolver()
Return the function context used by this registry.

Returns:
The function context used by this registry.

getDocument

public Document getDocument()
Return the XML active sheet used for unmarshalling this processor instance.

Returns:
The XML active sheet used for unmarshalling this processor instance.

setValidating

public void setValidating(boolean validating)
Specifies that the Active Sheet will be validated. By default the value of this is set to true.

Parameters:
validating - true if the Active Sheet will be validated ; false otherwise.

isValidating

public boolean isValidating()
Indicates whether or not the Active Sheet will be validated.

Returns:
true if the Active Sheet will be validated ; false otherwise..

setLogger

public void setLogger(Logger logger)
Set the logger that the processor will use.

Specified by:
setLogger in interface Loggable
Parameters:
logger - The logger.

setLogger

public void setLogger(String logFileName)
               throws InitializationException
Set the logger that the processor will use.

Parameters:
logFileName - The name of the file to log activities.
Throws:
InitializationException

getLogger

public Logger getLogger()
Return the logger used by the processor. If the processor doesn't use any, a default one is created which return logged information to System.err.

Specified by:
getLogger in interface Loggable
Returns:
The logger used by the processor.

setAttribute

public void setAttribute(Object key,
                         Object data)
Define an attribute for the processor. An action may access to externals objects/ressources by using such attributes. Attributes should not change after process initialization. Attributes are common to all actions. If an object is transaction specific, it should be added to the set of datas used at runtime.

Specified by:
setAttribute in interface Configurable
Parameters:
key - The key associated to the object.
data - The object to define as an attribute.

setAttributes

public void setAttributes(Map attributes)
Set the properties shared by all data set used by this processor.

Specified by:
setAttributes in interface Configurable
Parameters:
attributes - The attribute set to define.

getAttribute

public Object getAttribute(Object key)
Return an attribute that has been defined for the processor. If none correspond to the key, null is returned.

Specified by:
getAttribute in interface Configurable
Parameters:
key - The key associated to the object.
Returns:
The object defined as an attribute.

getAttributes

public Map getAttributes()
Return the set of attributes defined for the processor.

Specified by:
getAttributes in interface Configurable
Returns:
The set of attributes defined for the processor.

containsAttribute

public boolean containsAttribute(Object key)
Returns true if the processor's attribute set contains a mapping for the specified key.

Specified by:
containsAttribute in interface Configurable
Parameters:
key - The key associated to the object.
Returns:
true if the processor's attribute set contains a mapping for the specified key.

mergeAttributes

public void mergeAttributes(Map attributes)
Merge 2 collections of attributes.

Specified by:
mergeAttributes in interface Configurable
Parameters:
attributes - The attributes set to merge with.

init

public void init()
          throws InitializationException
Display an initialization message to the log stream.

Specified by:
init in interface Initializable
Throws:
InitializationException - If the welcome message can't be read.

getMainAction

public MainAction getMainAction()
Return the main action.

Returns:
The main action.

getDefaultAction

public AbstractAction getDefaultAction()
Return the default action.

Returns:
The default action.

setMainAction

public void setMainAction(MainAction mainAction)
Set a ready-to-use main action.

Parameters:
mainAction - The main action.

unmarshal

public void unmarshal(Document activeSheet)
               throws InitializationException
Unmarshal an Active Sheet.

Parameters:
activeSheet - The Active Sheet to unmarshall.
Throws:
InitializationException

unmarshal

public void unmarshal(InputSource activeSheet)
               throws InitializationException
Unmarshal the processor from an XML file.

Parameters:
activeSheet - The name of the XML file.
Throws:
InitializationException

unmarshal

public void unmarshal(String activeSheet)
               throws InitializationException
Unmarshal the processor from an XML file.

Parameters:
activeSheet - The path to the XML file.
Throws:
InitializationException

unmarshal

public void unmarshal(XFile activeSheet)
               throws InitializationException
Unmarshal the processor from an XML file.

Parameters:
activeSheet - The XML file to unmarshal.
Throws:
InitializationException

unmarshal

public void unmarshal(InputStream activeSheet)
               throws InitializationException
Unmarshal the processor from an XML stream.

Parameters:
activeSheet - The XML input stream.
Throws:
InitializationException

unmarshal

public void unmarshal(Reader activeSheet)
               throws InitializationException
Unmarshal the processor from an XML character stream.

Parameters:
activeSheet - The XML character stream.
Throws:
InitializationException

setLogLevel

public void setLogLevel(Level level)
Set the level of the current logger.

Parameters:
level - The level to set.

setLogLevel

public void setLogLevel(String logLevel)
Set the level of the current logger.

Parameters:
logLevel - The label of the level to set.

isDisabled

public boolean isDisabled(String prefix)
Return true if the prefix has been disabled, false otherwise.

Parameters:
prefix - The prefix to check.
Returns:
true if the prefix has been disabled, false otherwise.

isEnabled

public boolean isEnabled(String prefix)
Return true if the prefix has been enabled and is not disabled, false otherwise.

Parameters:
prefix - The prefix to check.
Returns:
true if the prefix has been enabled and is not disabled, false otherwise.

isExplicitelyEnabled

public boolean isExplicitelyEnabled(String prefix)
Return true if the prefix has been explicitely enabled, false otherwise.

Parameters:
prefix - The prefix to check.
Returns:
true if the prefix has been explicitely enabled, false otherwise.

disablesPrefix

public void disablesPrefix(String prefix)
Disables the prefix given. This can be done only if none has been already enabled.

Parameters:
prefix - The prefix to disable.

enablesPrefix

public void enablesPrefix(String prefix)
Enables the prefix given. This can be done only if none has been already disabled.

Parameters:
prefix - The prefix to enable.

addWeakDataSet

public void addWeakDataSet(DataSet dataSet)
Adds a data set to the current list of data set used by this instance. Once a data set became unused, it is automatically removed from this list.

Parameters:
dataSet - The data set to add to the list maintained by this instance.

removeWeakDataSet

public void removeWeakDataSet(DataSet dataSet)
Remove a data set from the current list of data set used by this instance.

Parameters:
dataSet - The data set to remove.

countDataSets

public int countDataSets()
Return the number of data sets known by this processor instance. Notice that this number is reactualized as a data set is no longer in use.

Returns:
The number of data sets known by this processor instance.

getDataSets

public List getDataSets()
Return the list of the data sets known by this processor instance. All the data sets are kept as long as the list is in use. If this processor uses another data set after the creation of the list, it won't be inserted in the items of the list; another list must be created.

Returns:
A list of the data sets known by this processor instance.

acquire

public void acquire(DataSet dataSet)
Acquire a data set : if the data set is not belonging to this processor instance, it is removed from its list and added to this one. A data set must be acquired by a processor before running it.

Parameters:
dataSet - The set of datas used when the action is running.
See Also:
DataSet.setMainAction(MainAction)

call

public void call(DataSet dataSet,
                 QName logic)
          throws ExecutionException
Perform the action by executing the procedure that has the name given. Running a processor should always be done with one of the call methods. Direct action call may be done carefully : always use the acquire method before.

Parameters:
dataSet - The set of datas used when the action is running. If the data set is not belonging to this processor instance, it is removed from its list and added to this one (acquired).
logic - The name of the logic function to call, as a qualified name. A QName build with "#default" or "#main" may be provided. If the procedure is not found, the call ends immediately.
Throws:
ExecutionException - If the action can't be performed.
See Also:
acquire(DataSet), callMain(DataSet), callDefault(DataSet)

callMain

public void callMain(DataSet dataSet)
              throws ExecutionException
Perform the action by executing the main procedure, that correspond to the root. Running a processor should always be done with one of the call methods. Direct action call may be done carefully : always use the acquire method before.

Parameters:
dataSet - The set of datas used when the action is running. If the data set is not belonging to this processor instance, it is removed from its list and added to this one (acquired).
Throws:
ExecutionException - If the action can't be performed.
See Also:
acquire(DataSet), call(DataSet, QName), callDefault(DataSet)

callDefault

public void callDefault(DataSet dataSet)
                 throws ExecutionException
Perform the action by executing the default procedure, that correspond to the unnamed logic procedure if any. Running a processor should always be done with one of the call methods. Direct action call may be done carefully : always use the acquire method before.

Parameters:
dataSet - The set of datas used when the action is running. If the data set is not belonging to this processor instance, it is removed from its list and added to this one (acquired).
Throws:
ExecutionException - If the action can't be performed.
See Also:
acquire(DataSet), call(DataSet, QName), callMain(DataSet)

getProcedure

public AbstractAction getProcedure(QName name)
Returns the named procedure. Null if it doesn't exist.

Parameters:
name - The name of the procedure, as a qualified name.
Returns:
The named procedure. Null if it doesn't exist.

getProcedures

public Map getProcedures()
Returns the procedures.

Returns:
The procedures.

containsProcedure

public boolean containsProcedure(QName name)
Returns true if the procedure exists, false otherwise.

Parameters:
name - The name of the procedure, as a qualified name.
Returns:
true if the procedure exists, false otherwise.

addNamedLogicProcedure

public void addNamedLogicProcedure(AbstractAction logicProcedure,
                                   Element element,
                                   AbstractAction parent)
Adds a logic procedure to the processor. If the element has no name attribute, it stands for the processor's main logic procedure.

Parameters:
logicProcedure - The logic procedure.
element - The XML element that stands for the procedure, to unmarshall.
parent - The action depending from.

hasDefault

public boolean hasDefault()
Indicates whether the active sheet of this processor instance has a default procedure (#default) or not.

Returns:
true if the active sheet defines a default procedure, false otherwise.

getXOperator

public XOperator getXOperator()
Return the X-operator of this object.

Specified by:
getXOperator in interface XOperable
Returns:
The non null X-operator of this object.

setCorrupted

public void setCorrupted(String cause,
                         Throwable exception,
                         boolean logEvent)
Indicates that this engine is corrupted. A severe message is logged.

Parameters:
cause - The message that indicates the cause.
exception - The exception that cause the error.
logEvent - true if this event must be logged, false otherwise.

getLocation

public XFile getLocation()
                  throws UnlocalizableException
Return the URI where is located this processor instance.

Specified by:
getLocation in interface Localizable
Returns:
An URI, as an XFile.
Throws:
UnlocalizableException - If this processor instance is not localizable. It may occur :
  • if setLocation(XFile) was invoked with a null argument,
  • if this processor instance didn't already unmarshall an Active Sheet,
  • if the Active Sheet of this processor instance was a stream,
  • or if this processor instance is a pre-compiled object that works without an Active Sheet.
See Also:
Localizable.getLocation()

getBaseLocation

public XFile getBaseLocation()
Return the directory where is located this processor instance.

Returns:
An URI, as an XFile, or null if it is not localizable.

setLocation

public void setLocation(XFile location)
                 throws UnlocalizableException
Set an URI that localize this processor instance.

Specified by:
setLocation in interface Localizable
Parameters:
baseURI - The URI, as an XFile. Should not be null, otherwise it will delocalize this processor instance.
Throws:
UnlocalizableException - For compatibility.
See Also:
Localizable.setLocation(org.inria.ns.reflex.modules.io.XFile)

isLocalizable

public boolean isLocalizable()
Indicates whether this instance is localizable or not.

Specified by:
isLocalizable in interface Localizable
Returns:
true if this instance is localizable, false otherwise.
See Also:
Localizable.isLocalizable()

getCatalogReferences

public Iterator getCatalogReferences()
Get the catalog references.

Returns:
An iterator on String or XFiles.

getParent

public LocalCatalog getParent()
Return the parent local catalog.

Returns:
A non-null local catalog.

hasParent

public boolean hasParent()
Indicates if this local catalog has a parent.

Returns:
true : a processor instance has always a parent local catalog.

getLocalCatalogEntry

public LocalCatalog getLocalCatalogEntry()
Return the local catalog entry.

Specified by:
getLocalCatalogEntry in interface GlobalCatalog
Returns:
This local catalog.

addCatalogReference

public void addCatalogReference(String catalogRef)
                         throws FileSystemException
Adds a catalog reference to this processor instance. When the catalog will be requested, it will be created and stored in the registry.

Parameters:
catalogRef - The reference to the catalog : A file path, or a class name preceded with "res:" (that must be a Catalog).
Throws:
FileSystemException

addCatalogReference

public void addCatalogReference(XFile catalogRef)
                         throws FileSystemException
Adds a catalog reference to this processor instance. When the catalog will be requested, it will be created and stored in the registry.

Parameters:
catalogRef - The reference to the catalog : A file path, or a class name preceded with "res:" (that must be a Catalog).
Throws:
FileSystemException

isModuleRegistered

public boolean isModuleRegistered(String nsURI)
Indicates if a namespace URI corresponds to a registered module or not. The module is not loaded.

Parameters:
nsURI - The namespace URI of the module to retrieve.
Returns:
true if a module is bound to the given namespace URI, false otherwise.

getModule

public Module getModule(QName name)
Return the module bound to the same namespace URI of the given qualified name.

The first time a module is expected, the version is those explicitely specified if any, or the last version known at this level. The version is kept so that next module requests will supply the same version.

Parameters:
name - The qualified name which namespace URI will be used to retrieve the module.
Returns:
The module bound to the namespace URI of the given qualified name.
See Also:
getModule(String)

getModule

public Module getModule(String nsURI)
Return the module bound to the same namespace URI of the given qualified name.

The first time a module is expected, the version is those explicitely specified if any, or the last version known at this level. The version is kept so that next module request will supply the same version.

Parameters:
nsURI - The namespace URI of the module to retrieve.
Returns:
The module bound to the namespace URI of the given qualified name.
See Also:
getModule(String)

setVersion

public void setVersion(String moduleNsURI,
                       String version)
Set the version of the module to use.

Parameters:
moduleNsURI - The namespace URI of the module.
version - The version of the module to use.

getVersion

public String getVersion(String moduleNsURI)
Get the version of the module to use.

Parameters:
moduleNsURI - The namespace URI of the module.
Returns:
The version of the module to use, null if none specified.