org.cristalise.kernel.persistency

Class ClusterStorage

java.lang.Object

org.cristalise.kernel.persistency.ClusterStorage

Direct Known Subclasses:

MemoryOnlyClusterStorage, ProxyLoader, TransactionalClusterStorage, XMLClusterStorage

public abstract class ClusterStorage
extends Object

Interface for persistency managers of entities. It allows different kernel objects to be stored in different backend. For instance, Properties may be stored in LDAP, while Events, Outcomes and Viewpoints could be stored in a relational database. The kernel does and needs no analytical querying of the ClusterStorages, only simple gets and puts. This may be implemented on top of the storage implementation separately.

Each item is indexed by its ItemPath, which is may be constructed from its UUID, equivalent SystemKey object, or

Each first-level path under the Item is defined as a Cluster. Different Clusters may be stored in different places. Each ClusterStorage must support get(ItemPath, String) and getClusterContents(ItemPath, String) for clusters they return READ and READWRITE from queryClusterSupport and put(ItemPath, C2KLocalObject) and delete(ItemPath, String) for clusters they return WRITE and READWRITE from getClusterContents(ItemPath, String). Operations that have not been declared as not supported should throw a PersistencyException. If a cluster does not exist, get should return null, and delete should return with no action.

Field Summary

Fields

Modifier and Type	Field and Description
static String[]	allClusterTypes An array of all currently supported cluster types, for iterative purposes.
static String	COLLECTION The root of the Collection object cluster.
static String	HISTORY This is the cluster that contains all event for this Item.
static String	JOB Agents store their persistent jobs in this cluster that have been pushed to them by activities configured to do so.
static String	LIFECYCLE The cluster which holds the Item workflow.
static short	NONE Constant to return from queryClusterSupport(String) for Cluster types this storage does not support.
static String	OUTCOME This cluster holds all outcomes of this Item.
static String	PROPERTY The root of the Property object cluster.
static short	READ Constant to return from queryClusterSupport(String) for Cluster types this storage can read from a database but not write.
static short	READWRITE Constant to return from queryClusterSupport(String) for data stores that CRISTAL may use for both reading and writing for the given Cluster type.
static String	ROOT The defined path of the root of the CRISTAL Kernel object cluster tree.
static String	VIEWPOINT This cluster contains all viewpoints.
static short	WRITE Constant to return from queryClusterSupport(String) for Cluster types this storage can write to a database but not read.

Constructor Summary

Constructors

Constructor and Description
ClusterStorage()

Method Summary

Methods

Modifier and Type	Method and Description
abstract void	close() Shuts down the storage.
abstract void	delete(ItemPath itemPath, String path) Remove a CRISTAL local object from storage.
abstract C2KLocalObject	get(ItemPath itemPath, String path) Fetches a CRISTAL local object from storage
abstract String[]	getClusterContents(ItemPath itemPath, String path) Queries the local path below the given root and returns the possible next elements.
protected static String	getClusterType(String path) Utility method to find the cluster for a particular Local Object (the first part of its path)
abstract String	getId()
abstract String	getName()
static String	getPath(C2KLocalObject obj) Gives the path for a local object.
abstract void	open(Authenticator auth) Connects to the storage.
abstract void	put(ItemPath itemPath, C2KLocalObject obj) Stores a CRISTAL local object.
abstract short	queryClusterSupport(String clusterType) Declares whether or not this ClusterStorage can read or write a particular CRISTAL local object type.

Methods inherited from class java.lang.Object

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

Field Detail

NONE

public static final short NONE

Constant to return from queryClusterSupport(String) for Cluster types this storage does not support.

See Also:

Constant Field Values

READ

public static final short READ

Constant to return from queryClusterSupport(String) for Cluster types this storage can read from a database but not write. An example would be pre-existing data in a database that is mapped to Items in some way.

See Also:

Constant Field Values

WRITE

public static final short WRITE

Constant to return from queryClusterSupport(String) for Cluster types this storage can write to a database but not read. An example would be a realtime database export of data, which is transformed in an unrecoverable way for use in other systems.

See Also:

Constant Field Values

READWRITE

public static final short READWRITE

Constant to return from queryClusterSupport(String) for data stores that CRISTAL may use for both reading and writing for the given Cluster type.

See Also:

Constant Field Values

ROOT

public static final String ROOT

The defined path of the root of the CRISTAL Kernel object cluster tree. A zero-length string.

See Also:

Constant Field Values

PROPERTY

public static final String PROPERTY

The root of the Property object cluster. All Property paths start with this. Defined as "Property". Properties are stored underneath according to their name e.g. "Property/Name"

See Also:

Constant Field Values

COLLECTION

public static final String COLLECTION

The root of the Collection object cluster. All Collection paths start with this. Defined as "Collection". Collections are stored underneath by name e.g. "Collection/Composition"

See Also:

Constant Field Values

LIFECYCLE

public static final String LIFECYCLE

The cluster which holds the Item workflow. Defined as "LifeCycle". Holds the workflow inside, which is named "workflow", hence "LifeCycle/workflow".

See Also:

Workflow, Constant Field Values

OUTCOME

public static final String OUTCOME

This cluster holds all outcomes of this Item. The path to each outcome is "Outcome/Schema Name/Schema Version/Event ID"

See Also:

Constant Field Values

HISTORY

public static final String HISTORY

This is the cluster that contains all event for this Item. This cluster may be instantiated in a client as a History, which is a RemoteMap. Events are stored with their ID: "/AuditTrail/Event ID"

See Also:

Constant Field Values

VIEWPOINT

public static final String VIEWPOINT

This cluster contains all viewpoints. Its name is defined as "ViewPoint". The paths of viewpoint objects stored here follow this pattern: "ViewPoint/Schema Name/Viewpoint Name"

See Also:

Constant Field Values

JOB

public static final String JOB

Agents store their persistent jobs in this cluster that have been pushed to them by activities configured to do so. The name is defined as "Job" and each new job received is assigned an integer ID one more than the highest already present.

See Also:

Constant Field Values

allClusterTypes

public static final String[] allClusterTypes

An array of all currently supported cluster types, for iterative purposes.

Constructor Detail

ClusterStorage

public ClusterStorage()

Method Detail

open

public abstract void open(Authenticator auth)
                   throws PersistencyException

Connects to the storage. It must be possible to retrieve CRISTAL local objects after this method returns.

Parameters:

auth - The Authenticator instance that the user or server logged in with.

Throws:

PersistencyException - If storage initialization failed

close

public abstract void close()
                    throws PersistencyException

Shuts down the storage. Data must be completely written to disk before this method returns, so the process can exit. No further gets or puts should follow.

Throws:

PersistencyException - If closing failed

queryClusterSupport

public abstract short queryClusterSupport(String clusterType)

Declares whether or not this ClusterStorage can read or write a particular CRISTAL local object type.

Parameters:

clusterType - The Cluster type requested. Must be one of the Cluster type constants from this class.

Returns:

A ClusterStorage constant: NONE, READ, WRITE, or READWRITE

getName

public abstract String getName()

Returns:

A full name of this storage for logging

getId

public abstract String getId()

Returns:

A short code for this storage for reference

getClusterType

protected static String getClusterType(String path)

Utility method to find the cluster for a particular Local Object (the first part of its path)

Parameters:

Local - object path

Returns:

The cluster to which it belongs

getPath

public static String getPath(C2KLocalObject obj)

Gives the path for a local object. Varies by Cluster.

Parameters:

C2KLocalObject -

Returns:

Its path

get

public abstract C2KLocalObject get(ItemPath itemPath,
                 String path)
                            throws PersistencyException

Fetches a CRISTAL local object from storage

Parameters:

itemPath - The ItemPath of the containing Item

path - The path of the local object

Returns:

The C2KLocalObject, or null if the object was not found

Throws:

PersistencyException - when retrieval failed

put

public abstract void put(ItemPath itemPath,
       C2KLocalObject obj)
                  throws PersistencyException

Stores a CRISTAL local object. The path is automatically generated.

Parameters:

itemPath - The Item that the object will be stored under

obj - The C2KLocalObject to store

Throws:

PersistencyException - When storage fails

delete

public abstract void delete(ItemPath itemPath,
          String path)
                     throws PersistencyException

Remove a CRISTAL local object from storage. This should be used sparingly and responsibly, as it violated traceability. Objects removed in this way are not expected to be recoverable.

Parameters:

itemPath - The containing Item

path - The path of the object to be removed

Throws:

PersistencyException - When deletion fails or is not allowed

getClusterContents

public abstract String[] getClusterContents(ItemPath itemPath,
                          String path)
                                     throws PersistencyException

Queries the local path below the given root and returns the possible next elements.

Parameters:

itemPath - The Item to query

path - The path within that Item to query. May be ClusterStorage.ROOT (empty String)

Returns:

A String array of the possible next path elements

Throws:

PersistencyException - When an error occurred during the query