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 db 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 Deprecated.
static String	COLLECTION Deprecated.
static String	HISTORY Deprecated.
static String	JOB Deprecated.
static String	LIFECYCLE Deprecated.
static short	NONE Constant to return from queryClusterSupport(String) for Cluster types this storage does not support.
static String	OUTCOME Deprecated.
static String	PATH Deprecated.
static String	PROPERTY Deprecated.
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 Deprecated.
static String	VIEWPOINT Deprecated.
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

Modifier and Type	Method and Description
abstract boolean	checkQuerySupport(String language) Checks whether the storage support the given type of query or not
abstract void	close() Shuts down the storage.
abstract void	delete(ItemPath itemPath, String path) Remove a CRISTAL local object from storage.
abstract String	executeQuery(Query query) Executes an SQL/OQL/XQuery/XPath/etc query in the target database.
abstract C2KLocalObject	get(ItemPath itemPath, String path) Fetches a CRISTAL local object from storage by path
String[]	getClusterContents(ItemPath itemPath, ClusterType type) Queries the local path below the given type and returns the possible next elements.
abstract String[]	getClusterContents(ItemPath itemPath, String path) Queries the local path below of the item and returns the possible next elements.
ClusterType[]	getClusters(ItemPath itemPath) Queries the Item for the Clusters (root path elements) that are available.
protected static ClusterType	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.
short	queryClusterSupport(ClusterType clusterType) Declares whether or not this ClusterStorage can read or write a particular CRISTAL local object type.
abstract short	queryClusterSupport(String clusterType) Deprecated.

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

@Deprecated
public static final String ROOT

Deprecated.

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

PATH

@Deprecated
public static final String PATH

Deprecated.

PROPERTY

@Deprecated
public static final String PROPERTY

Deprecated.

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"

COLLECTION

@Deprecated
public static final String COLLECTION

Deprecated.

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"

LIFECYCLE

@Deprecated
public static final String LIFECYCLE

Deprecated.

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

See Also:

Workflow

OUTCOME

@Deprecated
public static final String OUTCOME

Deprecated.

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

HISTORY

@Deprecated
public static final String HISTORY

Deprecated.

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"

VIEWPOINT

@Deprecated
public static final String VIEWPOINT

Deprecated.

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"

JOB

@Deprecated
public static final String JOB

Deprecated.

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.

allClusterTypes

@Deprecated
public static final String[] allClusterTypes

Deprecated.

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 short queryClusterSupport(ClusterType clusterType)

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

Parameters:

clusterType - The Cluster type requested

Returns:

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

queryClusterSupport

@Deprecated
public abstract short queryClusterSupport(String clusterType)

Deprecated.

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

checkQuerySupport

public abstract boolean checkQuerySupport(String language)

Checks whether the storage support the given type of query or not

Parameters:

language - type of the query (e.g. SQL/XQuery/XPath/....)

Returns:

whether the Storage supports the type of the query or not

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 ClusterType getClusterType(String path)

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

Parameters:

path - 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:

obj - C2KLocalObject

Returns:

Its path

executeQuery

public abstract String executeQuery(Query query)
                             throws PersistencyException

Executes an SQL/OQL/XQuery/XPath/etc query in the target database.

Parameters:

query - the query to be executed

Returns:

the xml result of the query

Throws:

PersistencyException

get

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

Fetches a CRISTAL local object from storage by path

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 of the item 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

getClusterContents

public String[] getClusterContents(ItemPath itemPath,
                                   ClusterType type)
                            throws PersistencyException

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

Parameters:

itemPath -

type -

Returns:

Throws:

PersistencyException

getClusters

public ClusterType[] getClusters(ItemPath itemPath)
                          throws PersistencyException

Queries the Item for the Clusters (root path elements) that are available.

Parameters:

itemPath - the Item to query

Returns:

A ClusterType array of the possible next path elements

Throws:

PersistencyException - When an error occurred during the query