Appendix A. Object Store Implementations

A.1. The ObjectStore

This chapter covers the various JBoss Transaction Service object store implementations and provides guidelines for creating new implementations and using them in an application.
JBoss Transaction Service includes several different implementations of a basic object store. Each implementation is optimized for a particular purpose. All of the implementations are derived from the ObjectStore interface, which defines the minimum operations which is needed for an object store implementation to be used by JBoss Transaction Service. You can override the default object store implementation at runtime by setting the com.arjuna.ats.arjuna.objectstore.objectStoreType property to one of the types described below in Example A.1, “Object Store Type”.

Example A.1. Object Store Type

	/*
	* 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);
	};
You do not usually need to interact with any of the object store implementations directly, except for creating them if you are not using the default store type. All stores manipulate instances of the class ObjectState, which are named using a type derived via the object's type() operation, and a Uid. Object states in the store are usually in one of two distinct states OS_COMMITTED or 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 discarded. All of the implementations provided with this release use shadow copies to handle these state transitions. However, you are allowed to implement them in a different way. Object states may become hidden and inaccessible under the control of the crash recovery system.
The allTypes and allObjUids methods provide the ability to browse the contents of a store. The allTypes method returns an InputObjectState containing all of the type names of all objects in a store, terminated by a null name. The allObjUids method returns an InputObjectState that contains all of the Uids of all objects of a given type terminated by the special Uid.nullUid() type.