org.inria.ns.reflex.processor
Class DataSet

java.lang.Object
  org.inria.ns.reflex.processor.DataSet

All Implemented Interfaces:

XOperable

public class DataSet
extends Object
implements XOperable

A DataSet is used to store properties used by the RefleX processor at runtime.

A property is named by a QName (qualified name), and its value may be any object or the null value.

Unqualified property names are considered as unqualified attributes in XML, that is to say that such property names are not bound to a namespace URI ; if a property name have to be bound to a namespace URI, it must be prefixed.

Addressing properties

Properties from the data set can be used as XPath variables references , like $myProperty.

Properties that are XML objects or cross-operable objects may be traversed by XPath expressions, like $myProperty/foo/@bar.

Property scope

A property may be local,global, or shared:

• Local properties are usable only in the scope of the logical procedure that defines them.
• Global properties are reachable from any logic procedure.
• Shared properties are like global properties accessible by all data set that are running the same processor instance.

When a property is expected, it is searched first within the local properties, then within the global properties, and last within the shared properties.

According to its scope, a property may be shadowed by another property with the same name and a higher accessed priority.

Life cycle

***

Once created, the data set must be adopted by the processor instance that will execute it. When the data set is no longer in use, it is discarded automatically. To do so, ensure that there is no strong reference.

***

To prevent problems (the program won't terminate) :

• it is highly recommended to remove it manually by using removeWeakDataSet().

or :

• if a strong reference on a data set have to be used anyway, store an Embed data set instead (getEmbeddedDataSet()), which is disconnected from its host processor instance.

or :

• store the data set within a soft reference.

Implementation details

Normal usage is to invoke the DataSet with its getPropertyValue(QName) methods to retrieve values. PropertyResolvers plugged in front of the DataSet would handle resolution for their keys.

It is also possible to access to the local, global, or shared properties directly.

Author:

Philippe Poulard

See Also:

QName

Nested Class Summary

class	DataSet.DataSetContext A view of this data set as a variable context.
static class	DataSet.Embedded An Embedded data set that can be stored safely (it can be reached with a permanent strong reference).

Field Summary

boolean	isLogging true if the data set is used to log all actions processed with, false otherwise.
Level	logLevel The level for logging.
QName	name The name of this data set.

Constructor Summary

DataSet()
Create a default DataSet, which contains no properties.

DataSet(DataSet dataSet)
Create a new instance of DataSet, which contains no local properties.

DataSet(DataSet dataSet, boolean copyLocalProperties)
Create a new instance of DataSet, which contains a copy of the local properties of the given data set.

DataSet(ProcessorInstance processorInstance)
Create a new instance of DataSet, which contains no local neither global properties.

Method Summary

void	addGlobalProperty(QName propertyName, Object value) Add a new global property in the data set, or replace those that have the same key.
void	addLocalProperty(QName propertyName, Object value) Add directly a new local property in the data set, or replace those that have the same key.
void	addProperty(QName propertyName, Object propertyValue, int scope) Add the property to the data set, with the appropriate scope.
void	addSharedProperty(QName propertyName, Object value) Add a new shared property in the data set, or replace those that have the same key.
XPathContext	createContext(NamespaceContextFactory namespaceContextFactory) Create a context based : on the given factory for mapping namespace URIs, on this data set for resolving variables, on its processor instance's module bindings for resolving XPath functions.
void	feedContext(Object data) Store a data inside the current context.
void	feedContextWithBubbleMessages(List list) Feed the current context with all bubble messages in the list.
Object	getCurrentObject() Get the current object for this data set.
static DataSet	getDataSet(PatternContext context) Extract a data set from an XPath context.
DataSet.Embedded	getEmbeddedDataSet() Embeds this data set inside a storable object.
Object	getGlobalPropertyValue(QName propertyName) Return the value of a global property in the data set.
Object	getLocalPropertyValue(QName propertyName) Return directly the value of a local property in the data set.
MainAction	getMainAction() Return the root action that uses this data set.
ProcessorInstance	getProcessorInstance() Return the processor instance.
Object	getPropertyValue(QName propertyName) Return the value of a property based on its QName.
Object	getPropertyValue(QName propertyName, int scope) Return the value of a property based on its QName.
Map	getSharedProperties() Return the set of shared properties used by this data set.
Object	getSharedPropertyValue(QName propertyName) Return the value of a shared property in the data set.
Object	getThreadLocalProperty(QName key) Get a property in the map of thread-local properties used by this data set.
XOperator	getXOperator() Return the X-operator of this object.
XPathVariableResolver	getXPathVariableResolver() Return the XPathVariableResolver used to resolve variable bindings within an XPath expression.
List	peekContext() Read the context on the top of the context stack.
List	popContext() Pop the context on the top of the context stack.
List	pushContext() Push a new context on the context stack.
List	pushContext(List context) Push a context on the context stack.
void	putThreadLocalProperty(QName key, Object value) Put a property in the map of thread-local properties used by this data set.
Object	removeGlobalProperty(QName propertyName) Remove the global property which QName is the same as those passed in parameter.
Object	removeLocalProperty(QName propertyName) Remove the local property which QName is the same as those passed in parameter.
Object	removeProperty(QName propertyName) Remove the property which QName is the same as those passed in parameter.
Object	removeProperty(QName propertyName, int scope) Remove the property which QName is the same as those passed in parameter.
Object	removeSharedProperty(QName propertyName) Remove the shared property which QName is the same as those passed in parameter.
void	removeThreadLocalProperty(QName key) Remove a property in the map of thread-local properties used by this data set.
void	removeWeakDataSet() Removes this data set from its host processor instance, if any.
void	setCurrentObject(Object currentObject) Set the current object for this data set.
void	setMainAction(MainAction mainAction) Set the root action used by this data set.

Methods inherited from class java.lang.Object

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

Field Detail

name

public QName name

The name of this data set.

isLogging

public boolean isLogging

true if the data set is used to log all actions processed with, false otherwise.

logLevel

public Level logLevel

The level for logging.

Constructor Detail

DataSet

public DataSet()

Create a default DataSet, which contains no properties. This data set endorsed a default processor instance.

DataSet

public DataSet(ProcessorInstance processorInstance)

Create a new instance of DataSet, which contains no local neither global properties.

Parameters:

xclController - The controller whose engine class binder is in charge of property resolutions, and whose attributes are used as the shared property set.

DataSet

public DataSet(DataSet dataSet)

Create a new instance of DataSet, which contains no local properties.
The data set is built with the same global properties than the data set passed in parameter.
The data set doesn't keep the context of these that is built from.
Its trace indicator is also the same.

Parameters:

dataSet - The data set to build from.

DataSet

public DataSet(DataSet dataSet,
               boolean copyLocalProperties)

Create a new instance of DataSet, which contains a copy of the local properties of the given data set.
The data set is built with the same global properties than the data set passed in parameter.
The data set doesn't keep the context of these that is built from.
Its trace indicator is also the same.

Parameters:

dataSet - The data set to build from.

copyLocalProperties - true if the local properties have to be duplicated, false if the local propertise have to be left empty.

Method Detail

getProcessorInstance

public ProcessorInstance getProcessorInstance()

Return the processor instance.

Returns:

The processor instance.

getMainAction

public MainAction getMainAction()

Return the root action that uses this data set.

Returns:

The root action that uses this data set.

setMainAction

public void setMainAction(MainAction mainAction)

Set the root action used by this data set.

Parameters:

mainAction - The root action to use by this data set.

See Also:

ProcessorInstance.acquire(DataSet)

getSharedProperties

public Map getSharedProperties()

Return the set of shared properties used by this data set.

Returns:

The set of shared properties used by this data set.

putThreadLocalProperty

public void putThreadLocalProperty(QName key,
                                   Object value)

Put a property in the map of thread-local properties used by this data set. The thread-local properties are not accessible with XPath variable references. Properties must be get and set directly with the relevant methods.

Parameters:

key - The key of the object to store.

value - The object to store.

See Also:

removeThreadLocalProperty(QName), getThreadLocalProperty(QName)

removeThreadLocalProperty

public void removeThreadLocalProperty(QName key)

Remove a property in the map of thread-local properties used by this data set. The thread-local properties are not accessible with XPath variable references. Properties must be get and set directly with the relevant methods.

Parameters:

key - The key of the object to remove.

See Also:

putThreadLocalProperty(QName, Object), getThreadLocalProperty(QName)

getThreadLocalProperty

public Object getThreadLocalProperty(QName key)

Get a property in the map of thread-local properties used by this data set. The thread-local properties are not accessible with XPath variable references. Properties must be get and set directly with the relevant methods.

Parameters:

key - The key of the object to get.

See Also:

putThreadLocalProperty(QName, Object), removeThreadLocalProperty(QName)

getXPathVariableResolver

public XPathVariableResolver getXPathVariableResolver()

Return the XPathVariableResolver used to resolve variable bindings within an XPath expression. The variables of the XPathVariableResolver are taken from the properties of the DataSet.XPathVariableResolver is a data structure used by the Jaxen XPath processor to fix variables. See http://jaxen.sourceforge.net XPathVariableResolver is simply a view of the data set for the Jaxen XPath processor.

addLocalProperty

public void addLocalProperty(QName propertyName,
                             Object value)

Add directly a new local property in the data set, or replace those that have the same key. The key of the property is a QName. Property resolvers are not used.

Parameters:

namespaceURI - The namespace URI.

propertyName - The QName.

value - The value of the property (which can be null).

getLocalPropertyValue

public Object getLocalPropertyValue(QName propertyName)

Return directly the value of a local property in the data set. The key of the property is a QName. Property resolvers are not used.

Parameters:

propertyName - The QName.

Returns:

The value of the property (which can be null).

addGlobalProperty

public void addGlobalProperty(QName propertyName,
                              Object value)

Add a new global property in the data set, or replace those that have the same key. The key of the property is a QName. Property resolvers are not used.

Parameters:

namespaceURI - The namespace URI.

propertyName - The QName.

value - The value of the property (which can be null).

getGlobalPropertyValue

public Object getGlobalPropertyValue(QName propertyName)

Return the value of a global property in the data set. The key of the property is a QName. Property resolvers are not used.

Parameters:

propertyName - The QName.

Returns:

The value of the property (which can be null).

addSharedProperty

public void addSharedProperty(QName propertyName,
                              Object value)

Add a new shared property in the data set, or replace those that have the same key. The key of the property is a QName. Property resolvers are not used.

Parameters:

namespaceURI - The namespace URI.

propertyName - The QName.

value - The value of the property (which can be null).

getSharedPropertyValue

public Object getSharedPropertyValue(QName propertyName)

Return the value of a shared property in the data set. The key of the property is a QName. Property resolvers are not used.

Parameters:

propertyName - The QName.

Returns:

The value of the property (which can be null).

addProperty

public void addProperty(QName propertyName,
                        Object propertyValue,
                        int scope)
                 throws ExecutionException

Add the property to the data set, with the appropriate scope. If a property resolver is bound to the QName of the property, it is used to perform the action.

Parameters:

propertyName - The QName of the property.

propertyValue - The value of the property.

scope - The scope of the property.

Throws:

ExecutionException

getPropertyValue

public Object getPropertyValue(QName propertyName)
                        throws ExecutionException

Return the value of a property based on its QName. If a property resolver is bound to the QName of the property, it is used to perform the action. To retrieve the property, the looking up is done on the local data set first, then on the global data set, last on the shared data set.

Parameters:

propertyName - The QName of the property.

Returns:

The property's value (which can be null)

Throws:

ExecutionException

getPropertyValue

public Object getPropertyValue(QName propertyName,
                               int scope)
                        throws ExecutionException

Return the value of a property based on its QName. If a property resolver is bound to the QName of the property, it is used to perform the action. If the QName of the property denotes a path to an item of a collection, the looking up is started with the scope given, and goes on with the other shadowed scopes if not found.

Parameters:

propertyName - The QName of the property.

scope - The scope level to start the research of the property.

Returns:

The property's value (which can be null)

Throws:

ExecutionException

removeProperty

public Object removeProperty(QName propertyName)
                      throws ExecutionException

Remove the property which QName is the same as those passed in parameter. If a property resolver is bound to the QName of the property, it is used to perform the action. To retrieve the property, the looking up is done on the local data set first, then on the global data set, last on the shared data set.

Parameters:

propertyName - The QName of the property.

Returns:

The previous value of the property, or null if the property was not found.

Throws:

ExecutionException

removeLocalProperty

public Object removeLocalProperty(QName propertyName)
                           throws RecoverableException

Remove the local property which QName is the same as those passed in parameter. This method bypass the eventual property resolver; Use one of the removeProperty() methods instead.

Parameters:

propertyName - The QName of the property.

Returns:

The previous value of the property, or null if the property was not found.

Throws:

RecoverableException

See Also:

removeProperty(QName), removeProperty(QName, int), PropertyResolver

removeGlobalProperty

public Object removeGlobalProperty(QName propertyName)
                            throws RecoverableException

Remove the global property which QName is the same as those passed in parameter. This method bypass the eventual property resolver; Use one of the removeProperty() methods instead.

Parameters:

propertyName - The QName of the property.

Returns:

The previous value of the property, or null if the property was not found.

Throws:

RecoverableException

See Also:

removeProperty(QName), removeProperty(QName, int), PropertyResolver

removeSharedProperty

public Object removeSharedProperty(QName propertyName)
                            throws RecoverableException

Remove the shared property which QName is the same as those passed in parameter. This method bypass the eventual property resolver; Use one of the removeProperty() methods instead.

Parameters:

propertyName - The QName of the property.

Returns:

The previous value of the property, or null if the property was not found.

Throws:

RecoverableException

See Also:

removeProperty(QName), removeProperty(QName, int), PropertyResolver

removeProperty

public Object removeProperty(QName propertyName,
                             int scope)
                      throws ExecutionException

Remove the property which QName is the same as those passed in parameter. If a property resolver is bound to the QName of the property, it is used to perform the action. If the QName of the property denotes a path to an item of a collection, the looking up is started with the scope given, and goes on with the other shadowed scopes if not found.

Parameters:

propertyName - The QName of the property.

scope - The scope level to start the research of the property.

Returns:

The previous value of the property, or null if the property was not found.

Throws:

ExecutionException

setCurrentObject

public void setCurrentObject(Object currentObject)

Set the current object for this data set.

Parameters:

currentObject - The current object to set.

getCurrentObject

public Object getCurrentObject()

Get the current object for this data set.

Returns:

The current object.

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.

pushContext

public List pushContext()

Push a new context on the context stack. The creator of the new context must pop it after usage.

Returns:

The context created inside which objects can be stored.

pushContext

public List pushContext(List context)

Push a context on the context stack. The creator of the new context must pop it after usage.

Parameters:

context - A user-defined context. If the context is a simple list, use pushContext() instead.

Returns:

The context created inside which objects can be stored.

peekContext

public List peekContext()

Read the context on the top of the context stack.

Returns:

The context inside which objects can be stored.

popContext

public List popContext()

Pop the context on the top of the context stack. The context must be popped by the creator of the popped context.

Returns:

The context inside which objects have been stored.

feedContext

public void feedContext(Object data)

Store a data inside the current context.

null datas are ignored.

Parameters:

data - The data to store.

feedContextWithBubbleMessages

public void feedContextWithBubbleMessages(List list)

Feed the current context with all bubble messages in the list. Bubble messages are removed from the list.

Parameters:

list - The list that may contain bubble messages.

getDataSet

public static DataSet getDataSet(PatternContext context)

Extract a data set from an XPath context.

Parameters:

context - An XPath context.

Returns:

The $exp:dataset property.

createContext

public XPathContext createContext(NamespaceContextFactory namespaceContextFactory)

Create a context based :

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

Parameters:

namespaceContextFactory - The component that can create a namespace context. Usually, an action.

Returns:

An XPath context.

removeWeakDataSet

public void removeWeakDataSet()

Removes this data set from its host processor instance, if any.

See Also:

ProcessorInstance.removeWeakDataSet(DataSet)

getEmbeddedDataSet

public DataSet.Embedded getEmbeddedDataSet()

Embeds this data set inside a storable object.

The storable data set doesn't belong to the processor instance of the original data set. When a data set must be unwrapped, a copy that do belong to the original processor instance is provided.

Returns:

An embedded data set.