10.2.3. StateManager
The JBoss Transaction Service class
StateManager manages the state of an object and provides all of the basic state-management support mechanisms. StateManager creates and registers appropriate resources for persistence and recovery of the transactional object. If a transaction is nested, then StateManager propagates these resources between child transactions and their parents during the commit phase.
Objects in JBoss Transaction Service might be recoverable, persistent, both, or neither. If recoverable,
StateManager tries to generate and maintain appropriate recovery information for the object, storing the information in instances of the Input/OutputObjectState class. The lifetimes of these objects are assumed to be shorter than the application which created them. Recoverable and persistent objects are assumed to live longer than the applications that created them, so StateManager loads or unloads persistent states for the object by calling the activate or deactivate method. Objects which are neither recoverable nor persistent do not have any state data stored.
public class ObjectStatus
{
public static final int PASSIVE;
public static final int PASSIVE_NEW;
public static final int ACTIVE;
public static final int ACTIVE_NEW;
public static final int UNKNOWN_STATUS;
};
public class ObjectType
{
public static final int RECOVERABLE;
public static final int ANDPERSISTENT;
public static final int NEITHER;
};
public abstract class StateManager
{
public synchronized boolean activate ();
public synchronized boolean activate (String storeRoot);
public synchronized boolean deactivate ();
public synchronized boolean deactivate (String storeRoot, boolean commit);
public synchronized void destroy ();
public final Uid get_uid ();
public boolean restore_state (InputObjectState, int ObjectType);
public boolean save_state (OutputObjectState, int ObjectType);
public String type ();
. . .
protected StateManager ();
protected StateManager (int ObjectType, ObjectName attr);
protected StateManager (Uid uid);
protected StateManager (Uid uid, ObjectName attr);
. . .
protected final void modified ();
. . .
};
public class ObjectModel
{
public static final int SINGLE;
public static final int MULTIPLE;
};
If an object is recoverable or persistent,
StateManager invokes the save_state method during the deactivation method. The restore_state is called during the activate. The type is called at various points during the execution of the application. The programmer must implement these methods, since StateManager does not have access to a runtime description of the layout of an arbitrary Java object in memory. However, the capabilities provided by InputObjectState and OutputObjectState classes simplify the writing of these routines. For example, the save_state implementation for a class Example that had member variables called A, B and C might adhere to Example 10.5, “save_state Example”
Example 10.5. save_state Example
public boolean save_state ( OutputObjectState os, int ObjectType )
{
if (!super.save_state(os, ObjectType))
return false;
try
{
os.packInt(A);
os.packString(B);
os.packFloat(C);
return true;
}
catch (IOException e)
{
return false;
}
}
To support crash recovery for persistent objects, all
save_state and restore_state methods of user objects must call super.save_state and super.restore_state.
Note
The
type method determines the location in the object store where the state of instances of that class will be saved and ultimately restored. This can be any valid string. However, avoid using the hash character #, which is reserved for special directories required by JBoss Transaction Service.
The
get_uid method of StateManager provides read-only access to an object’s internal system name. The value of the internal system name can only be set when an object is created,by providing it as an explicit parameter or by generating a new identifier when the object is created.
The
destroy method removes the object’s state from the object store. This is an atomic operation, which only removes the state if its invoking transaction commits. The programmer must guarante eexclusive access to the object before invoking this operation.
Since object recovery and persistence have complimentary requirements, the
StateManager class combines the management of both into a single mechanism. That is, it uses instances of the class Input/OutputObjectState both for recovery and persistence purposes. An additional argument passed to the save_state and restore_state operations allows the programmer to determine the purpose for which any given invocation is being made thus allowing different information to be saved for recovery and persistence purposes.
