com.sdm.quasar.client.core.data
Interface DataManager

All Known Implementing Classes:

DefaultDataManager

public interface DataManager

Represents the basic interface of a datastore.

A DataManager stores hierarchically organized values and allows access to them. The hierarchy usually reflects the object structure of the stored objects including their attributes.

There are many extensions to this interface that provide additional functionality.

The DataManager interface is one of three facets of the DataManagerComponent. The following basic concepts are used by the DataManagerComponent.

1. Data (interface DataManager)
   The data manager stores key value pairs. The key is a String. Values may be any java object, e.g. a Integer or a complex data structure starting with an object that references other data objects.
   The values can be read and written using the methods in this interface (DataManager).
2. Data Structure (interfaces DataConfiguration and DataStructureConfiguration)
   The data manager defines a structure in the data. Each key value pair corresponds to a Node that defines the structural aspects of the data that can be stored under that key.
   The following types of structure are supported:
   • Base nodes (BaseNode)
     Base nodes are the "roots" of the data structure: they don't depend on any other nodes.
     Base nodes are created using DataStructureConfiguration.addBaseNode(String, Class).
   • Aspect nodes (AspectNode)
     Aspect nodes represent a value that depends on the value of another node in a "is a structural part of" relation. Attributes of an object are the typical example for these nodes.
     An aspect node depends on exactly one other node. The value of that other node is a java object of a specific type that has the attribute which the aspect node takes and supplies as its own value.
     Example: You have a class "Person" that has an attribute "name". You can define a base node with the key "person" storing an instance of class "Person". Then you can define an aspect node with the key "person.name" which is based on the value of the node "person" and returns the aspect "name" of the object that is stored in the node "person". Thus getValue(String) with the key "person.name" will return the value of the attribute "name" of the "Person" object stored in the node "person". And setValue(String, Object) with the key "person.name" will set the value in the stored object.
     Aspect nodes are created using DataStructureConfiguration.addAspectNode(String, String, Class, String, Class).
   • Indexed nodes (IndexedNode)
     An indexed nodes represents a value that is chosen by an index object among a collection of other similar values. The typical example is a list where you can access an element by using an Integer index.
     An indexed node depends on exactly one other node. The value of that other node must be a collection that supports an indexed access, e.g. a List, an array, or a Map. Please note that the capabilities of the indexed node depend on the corresponding plugin, thus restricting the possible types an indexed node can be based on.
     The value of an indexed node is not defined when using an access method without index. You must use a method like getValue(String, Context) to access an indexed value. The Context parameter has the information which index should be used in form of key value pairs where the key is the key of the indexed node and the value is the index to be used.
     Example: You have a class "Company" that has an attribute "employees" which is a List of class "Employee". You can have the instanceof of "Company" in a base node "company" and an aspect node "company.employees" which is connected to the "employees" attribute. Then you can define an indexed node "company.employees.indexed" which depends on the node "company.employees". To access the 5th employee instance in the list you need to create a context with the key "company.employees.indexed" and the value (Integer)4. Using this context a call to getValue(String, Context) with a key of "company.employees.indexed" will return the 5th employee.
     Normally you don't need to bother with this complicated access since it is included in your data binding when displaying a list in a table. And when you want to display a selected entries values you can keep track with a selection index in a separate node and use a computed node (see below) with a ContextNodeComputation to do that for you. The index mechanism with a context is incredibly powerful since it allows you to reference a value even when it is stored in a list of a list of objects.
     Indexed nodes are created using DataStructureConfiguration.addIndexedNode(String, String, Class, Class, Class).
   • Computed nodes (ComputedNode)
     A computed node represents a value that is the result of some computation involving the values of one or more other nodes. The typical example is a type conversion, e.g. of a Date into a String, but you can define other computations, e.g. the concatenation of several string values that are stored in other nodes. This is also a way to define 'virtual' attributes or values in the DataManager.
     A computed node depends on one or more other nodes. Its value depends on the Computation it is configured with. The Computation contains the code to convert the source values into the node's own value (and vice versa if desired).
     Computed nodes are created using DataStructureConfiguration.addComputedNode(String, String[], Computation). In most cases it will be sufficient to create a subclass of AbstractSimpleComputation and supply it as the Computation parameter.
3. Pluggable Functionality (interface DataManagerSetup)
   The implementation of the DataManagerComponent supplies only the basic infrastructure for organizing data and change notifications. You have to set up your data manager by registering the plugins that you want to use.
   Plug ins are defined by an interface derived from DataManagerPlugIn and its corresponding implementation. The implementation is accessable by the user of the DataManager by calling getPlugIn(Class) with the interface class as a parameter.
   The interface of a plug in may provide various methods to the user of the DataManager which offer additional functionality, e.g. an observer mechanism, metadata or transaction support.
   Other plug ins don't offer additional methods to the user but the supply basic functions of the DataManager, e.g. for actually storing values or accessing indexed values. These plug ins are absolutely necessary to create a data manager but are pluggable to allow for easy extensions, e.g. when handling collections you can add support for other types by supplying a corresponding plug in that handles the indexed nodes of those types.
   The plug ins essentially satisfy all calls to the DataManager interface by adding a ValueHandler to the nodes they feel responsible for. The value handlers of different plug ins are stacked in each node, thus the order in which plug ins are registered is vital.

To use the DataManager, you must first register the DataManagerPlugIns using DataManagerSetup, then configure the data structure using DataConfiguration or the more convenient interface DataStructureConfiguration. Then you can add, read, and modify the data.

Note: Depending on the system or dialog environment, implementations of this interface may have to be threadsafe.

Version:

1.0

Author:

Martin Haft, sd&m AG, Thomas Wolf, sd&m AG, Jürgen Zeller, sd&m AG, Carsten Lucke, sd&m AG, Bernd Olleck, sd&m AG

Method Summary

boolean	canModifyValue(java.lang.String key) Tests whether the value with the given name can be modified.
java.util.Set	getIndexSet(java.lang.String key) Returns a Set of the index values for the given key.
java.util.Set	getIndexSet(java.lang.String key, Context context) Returns a Set of the index values for the given key.
DataManagerPlugIn	getPlugIn(java.lang.Class dataManagerPlugInClass) Returns the requested plugin implementation
java.lang.Object	getValue(java.lang.String key) Returns the value corresponding to the given name.
java.lang.Object	getValue(java.lang.String key, Context context) Returns a value that needs indices to be accessed.
java.lang.Class	getValueType(java.lang.String key) Returnes the Class of the value that may be stored at or recieved by the data node.
boolean	hasKey(java.lang.String key) Tests whether the DataManager has a node defined for the given key.
boolean	hasPlugIn(java.lang.Class dataManagerPlugInClass) Tests whether the DataManager does have a specific plug in installed.
boolean	hasValue(java.lang.String key) Tests whether the node defined by the given key does have a value.
void	setValue(java.lang.String key, Context context, java.lang.Object value) Modifies a value that needs indices to be accessed.
void	setValue(java.lang.String key, java.lang.Object value) Sets the value corresponding to the given name.

Method Detail

getValue

public java.lang.Object getValue(java.lang.String key)

Returns the value corresponding to the given name.

Parameters:

key - the key of the data node

Returns:

the value, may be null iff the stored value is null or there is no stored value

getValueType

public java.lang.Class getValueType(java.lang.String key)

Returnes the Class of the value that may be stored at or recieved by the data node.

Parameters:

key - the key of the data node

Returns:

class of the stored value

setValue

public void setValue(java.lang.String key,
                     java.lang.Object value)

Sets the value corresponding to the given name.

Parameters:

key - the of the data node

value - the new value, may be null if null is a valid value for the corresponding node

Throws:

java.lang.IllegalArgumentException - if the value cannot be set.

hasKey

public boolean hasKey(java.lang.String key)

Tests whether the DataManager has a node defined for the given key.

This does not test whether the value is null or not, it tests solely if the DataManager is configured in a way that allows such a value to exist.

If hasKey(String) returns false, getValue(String) will return null. If hasKey(String) returns true, getValue(String) depends on the value of this node and the nodes it depends on.

Parameters:

key - the key of the node

Returns:

true iff the DataManager does have a node defined for the given key

hasValue

public boolean hasValue(java.lang.String key)

Tests whether the node defined by the given key does have a value. This method will return false if some prerequisite is not fulfilled. Such a prerequisite might be that a node that this node depends on does return a value that is not null.

This does not test whether the value is null or not, it tests solely if the node could have a value other than null.

If hasValue(String) returns false, getValue(String) will return null. If hasValue(String) returns true, getValue(String) depends on the actually stored value but may return null.

Parameters:

key - the key of the node

Returns:

true iff the node does have a value

Throws:

java.lang.IllegalArgumentException - iff the DataManager does not have a node with the given key.

hasPlugIn

public boolean hasPlugIn(java.lang.Class dataManagerPlugInClass)

Tests whether the DataManager does have a specific plug in installed.

Parameters:

dataManagerPlugInClass - the interface class (extending DataManagerPlugIn) that defines the plugin

Returns:

true iff the DataManager does have the feature installed

getPlugIn

public DataManagerPlugIn getPlugIn(java.lang.Class dataManagerPlugInClass)

Returns the requested plugin implementation

Parameters:

dataManagerPlugInClass - the interface class (extending DataManagerPlugIn) that defines the plugin

Returns:

the implementation of the requested plugin

Throws:

java.lang.IllegalArgumentException - if the DataManager does not have the given plugin installed

canModifyValue

public boolean canModifyValue(java.lang.String key)

Tests whether the value with the given name can be modified.

If canModifyValue(String) returns false, then setValue(String, Object) will throw an exception. Otherwise the call to setValue(String, Object) should succeed, although it may fail for unexpected reasons.

Parameters:

key - the key of the node to be modified

Returns:

true iff the DataManager can modify the value for the given name

getValue

public java.lang.Object getValue(java.lang.String key,
                                 Context context)

Returns a value that needs indices to be accessed. The values for these indices are supplied as context.

Parameters:

key - the key of the data node

context - the context containing the indices needed to access the value

Returns:

the value, may be null iff the stored value is null or there is no stored value

setValue

public void setValue(java.lang.String key,
                     Context context,
                     java.lang.Object value)

Modifies a value that needs indices to be accessed. The values for these indices are supplied as context.

Parameters:

key - the key of the data node

context - the context containing the indices needed to access the value

value - the new value, may be null if null is a valid value for the corresponding node

Throws:

java.lang.IllegalArgumentException - if the value cannot be set.

getIndexSet

public java.util.Set getIndexSet(java.lang.String key)

Returns a Set of the index values for the given key. The objects of the set may be used as index values within a Context together with the given key. The method returns null for not indexed nodes.

Parameters:

key - the key of the data node

Returns:

a Set of the index values for the given key or null.

getIndexSet

public java.util.Set getIndexSet(java.lang.String key,
                                 Context context)

Returns a Set of the index values for the given key. The objects of the set may be used as additional index values within the given Context for access with the given key. The method returns null for not indexed nodes.

Parameters:

key - the key of the data node

context - the context containing the indices needed to access the value

Returns:

a Set of the index values for the given key and context or null.