Package org.cristalise.kernel.persistency

Class ClusterStorage

java.lang.Object
org.cristalise.kernel.persistency.ClusterStorage
Direct Known Subclasses:
MemoryOnlyClusterStorage, 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

invalid reference 
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

invalid reference 
#get(ItemPath, String)
and
invalid reference 
#getClusterContents(ItemPath, String)
for clusters they return READ and READWRITE from queryClusterSupport and
invalid reference 
#put(ItemPath, C2KLocalObject)
and
invalid reference 
#delete(ItemPath, String)
for clusters they return WRITE and READWRITE from
invalid reference 
#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 Details

    • NONE

      public static final short NONE
      Constant to return from
      invalid reference 
      #queryClusterSupport(String)
      for Cluster types this storage does not support.
      See Also:

    • READ

      public static final short READ
      Constant to return from
      invalid reference 
      #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:

    • WRITE

      public static final short WRITE
      Constant to return from
      invalid reference 
      #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:

    • READWRITE

      public static final short READWRITE
      Constant to return from
      invalid reference 
      #queryClusterSupport(String)
      for data stores that CRISTAL may use for both reading and writing for the given Cluster type.
      See Also:

  • Constructor Details

    • ClusterStorage

      public ClusterStorage()

  • Method Details

    • open

      public abstract void open() 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, ClusterType cluster, TransactionKey transactionKey) throws PersistencyException
      Remove all CRISTAL local object of the given ClusterType from storage. This should be used sparingly and responsibly, as it violated traceability. Objects removed in this way cannot be recovered.
      Parameters:
      itemPath - The containing Item
      cluster - The type of the object to be removed
      transactionKey - the key of the transaction, cannot be null
      Throws:
      PersistencyException - When deletion fails or is not allowed

    • 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 cannot be recovered.
      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

    • delete

      public abstract void delete(ItemPath itemPath, TransactionKey transactionKey) throws PersistencyException
      Removes all data of an Item. 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
      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

    • toString

      public String toString()
      Overrides:
      toString in class Object