Appendix A. Object store implementations

A.1. The ObjectStore

In this appendix we shall examine the various TxCore object store implementations and give guidelines as to how other implementations may be created and plugged into an application.
This release of JBossTS contains several different implementations of a basic object store. Each serves a particular purpose and is generally optimised for that purpose. All of the implementations are derived from the ObjectStore interface. This defines the minimum operations which must be provided in order for an object store implementation to be used by JBossTS. The default object store implementation can be overridden at runtime by setting the com.arjuna.ats.arjuna.objectstore.objectStoreType property variable to one of the types described below.
	/*
	* This is the base class from which all object store types are derived.
	* Note that because object store instances are stateless, to improve
	* efficiency we try to only create one instance of each type per process.
	* Therefore, the create and destroy methods are used instead of new
	* and delete. If an object store is accessed via create it *must* be
	* deleted using destroy. Of course it is still possible to make use of
	* new and delete directly and to create instances on the stack.
	*/
	
	public class ObjectStore
	{
	public static final int OS_COMMITTED;
	public static final int OS_COMMITTED_HIDDEN;
	public static final int OS_HIDDEN;
	public static final int OS_INVISIBLE;
	public static final int OS_ORIGINAL;
	public static final int OS_SHADOW;
	public static final int OS_UNCOMMITTED;
	public static final int OS_UNCOMMITTED_HIDDEN;
	public static final int OS_UNKNOWN;
	public ObjectStore (ClassName type);
	public ObjectStore (ClassName type, String osRoot);
	public ObjectStore (String osRoot);
	public synchronized boolean allObjUids (String s, InputObjectState buff)
	throws ObjectStoreException;
	public synchronized boolean allObjUids (String s, InputObjectState buff,
	int m) throws ObjectStoreException;
	
	public synchronized boolean allTypes (InputObjectState buff)
	throws ObjectStoreException;
	public synchronized int currentState(Uid u, String tn)
	throws ObjectStoreException;
	public synchronized boolean commit_state (Uid u, String tn)
	throws ObjectStoreException;
	public synchronized boolean hide_state (Uid u, String tn)
	throws ObjectStoreException;
	public synchronized boolean reveal_state (Uid u, String tn)
	throws ObjectStoreException;
	public synchronized InputObjectState read_committed (Uid u, String tn)
	throws ObjectStoreException;
	public synchronized InputObjectState read_uncommitted (Uid u, String tn)
	throws ObjectStoreException;
	public synchronized boolean remove_committed (Uid u, String tn)
	throws ObjectStoreException;
	public synchronized boolean remove_uncommitted (Uid u, String tn)
	throws ObjectStoreException;
	public synchronized boolean write_committed (Uid u, String tn,
	OutputObjectState buff)
	throws ObjectStoreException;
	public synchronized boolean write_uncommitted (Uid u, String tn,
	OutputObjectState buff)
	throws ObjectStoreException;
	public static void printState (PrintStream strm, int res);
};
JBossTS programmers need not usually interact with any of the object store implementations directly other than possibly to create them in the first place (even this is not necessary if the default store type is used as JBossTS will create stores as necessary). All stores manipulate instances of the class ObjectState which are named using a type (via the object's type() operation) and a Uid. For atomic actions purposes object states in the store can be principally in two distinct states: OS_COMMITTED, and OS_UNCOMMITTED. An object state starts in the OS_COMMITTED state but when modified under the control of an atomic action a new second object state may be written that is in the OS_UNCOMMITTED state. If the action commits this second object state replaces the original and becomes OS_COMMITTED. If the action aborts, this second object state is simply discarded. All of the implementations provided with this release handle these state transitions by making use of shadow copies of object states, however, any other implementation that maintains this abstraction is permissible. Object states may become hidden (and thus inaccessible) under the control of the crash recovery system.
Browsing of the contents of a store is possible through the allTypes and allObjUids operations. allTypes returns an InputObjectState containing all of the type names of all objects in a store, terminated by a null name. allObjUids returns an InputObjectState that contains all of the Uids of all objects of a given type terminated by the special Uid.nullUid().