org.cristalise.kernel.persistency

Class ClusterStorage

java.lang.Object

org.cristalise.kernel.persistency.ClusterStorage

Direct Known Subclasses:

MemoryOnlyClusterStorage, ProxyLoader, TransactionalClusterStorageBase, 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 short	NONE Constant to return from #queryClusterSupport(String) for Cluster types this storage does not support.
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 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 void	abort(TransactionKey transactionKey)
abstract void	begin(TransactionKey transactionKey)
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	commit(TransactionKey transactionKey)
abstract void	delete(ItemPath itemPath, String path, TransactionKey transactionKey) Remove a CRISTAL local object from storage.
abstract String	executeQuery(Query query, TransactionKey transactionKey) Executes an SQL/OQL/XQuery/XPath/etc query in the target database.
abstract C2KLocalObject	get(ItemPath itemPath, String path, TransactionKey transactionKey) Fetches a CRISTAL local object from storage by path
String[]	getClusterContents(ItemPath itemPath, ClusterType type, TransactionKey transactionKey) Queries the local path below the given type and returns the possible next elements.
abstract String[]	getClusterContents(ItemPath itemPath, String path, TransactionKey transactionKey) Queries the local path below of the item and returns the possible next elements.
ClusterType[]	getClusters(ItemPath itemPath, TransactionKey transactionKey) 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 int	getLastIntegerId(ItemPath itemPath, String path, TransactionKey transactionKey) History and JobList based on a integer id that is incremented each tome a new Event or Job is stored
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	postBoostrap() Informs the ClusterSorage that the Boostrap process has finished.
abstract void	postConnect() Informs the ClusterSorage that connect was done.
abstract void	postStartServer() Informs the ClusterSorage that the start server process has finished.
abstract void	put(ItemPath itemPath, C2KLocalObject obj, TransactionKey transactionKey) Stores a CRISTAL local object.
abstract short	queryClusterSupport(ClusterType 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

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

postBoostrap

public abstract void postBoostrap()
                           throws PersistencyException

Informs the ClusterSorage that the Boostrap process has finished. It enables the implementation to perform domain specific tasks

Throws:

PersistencyException - Database error

postStartServer

public abstract void postStartServer()
                              throws PersistencyException

Informs the ClusterSorage that the start server process has finished. It enables the implementation to perform domain specific tasks

Throws:

PersistencyException - Database error

postConnect

public abstract void postConnect()
                          throws PersistencyException

Informs the ClusterSorage that connect was done. It enables the implementation to perform domain specific tasks

Throws:

PersistencyException - Database error

queryClusterSupport

public abstract 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

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,
                                    TransactionKey transactionKey)
                             throws PersistencyException

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

Parameters:

query - the query to be executed

transactionKey - the key of the transaction, can be null

Returns:

the xml result of the query

Throws:

PersistencyException

getLastIntegerId

public abstract int getLastIntegerId(ItemPath itemPath,
                                     String path,
                                     TransactionKey transactionKey)
                              throws PersistencyException

History and JobList based on a integer id that is incremented each tome a new Event or Job is stored

Parameters:

itemPath - The ItemPath (UUID) of the containing Item

path - the cluster patch, either equals to 'AuditTrail' or 'Job'

transactionKey - the key of the transaction, can be null

Returns:

returns the last found integer id (zero based), or -1 if not found

Throws:

PersistencyException - When storage fails

get

public abstract C2KLocalObject get(ItemPath itemPath,
                                   String path,
                                   TransactionKey transactionKey)
                            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

transactionKey - the key of the transaction, can be null

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,
                         TransactionKey transactionKey)
                  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

transactionKey - the key of the transaction, cannot be null

Throws:

PersistencyException - When storage fails

delete

public abstract void delete(ItemPath itemPath,
                            String path,
                            TransactionKey transactionKey)
                     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

transactionKey - the key of the transaction, cannot be null

Throws:

PersistencyException - When deletion fails or is not allowed

getClusterContents

public abstract String[] getClusterContents(ItemPath itemPath,
                                            String path,
                                            TransactionKey transactionKey)
                                     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)

transactionKey - the key of the transaction, can be null

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,
                                   TransactionKey transactionKey)
                            throws PersistencyException

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

Parameters:

itemPath -

type -

transactionKey - the key of the transaction, can be null

Returns:

Throws:

PersistencyException

getClusters

public ClusterType[] getClusters(ItemPath itemPath,
                                 TransactionKey transactionKey)
                          throws PersistencyException

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

Parameters:

itemPath - the Item to query

transactionKey - the key of the transaction, can be null

Returns:

A ClusterType array of the possible next path elements

Throws:

PersistencyException - When an error occurred during the query

begin

public abstract void begin(TransactionKey transactionKey)
                    throws PersistencyException

Throws:

PersistencyException

commit

public abstract void commit(TransactionKey transactionKey)
                     throws PersistencyException

Throws:

PersistencyException

abort

public abstract void abort(TransactionKey transactionKey)
                    throws PersistencyException

Throws:

PersistencyException