com.arjuna.ats.arjuna
Class StateManager

java.lang.Object
  com.arjuna.ats.arjuna.StateManager

Direct Known Subclasses:

AbstractRecord, BasicAction, Lock, LockManager

public class StateManager

extends java.lang.Object

The root of the Arjuna class hierarchy. This class provides state management facilities than can be automatically used by other classes by inheritance.

Since:

JTS 1.0.

Version:

$Id: StateManager.java 2342 2006-03-30 13:06:17Z $

Author:

Mark Little (mark@arjuna.com)

Field Summary

protected java.util.Hashtable	modifyingActions
protected ObjectName	objectName
protected Uid	objectUid
protected StateManagerAttribute	smAttributes
protected java.util.Hashtable	usingActions

Constructor Summary

protected	StateManager()
protected	StateManager(int ot)
protected	StateManager(int ot, ObjectName objName)
protected	StateManager(ObjectName objName)
protected	StateManager(Uid objUid) Create object with specific uid.
protected	StateManager(Uid objUid, int ot)
protected	StateManager(Uid objUid, int ot, ObjectName objName)
protected	StateManager(Uid objUid, ObjectName attr)

Method Summary

boolean	activate() This operation activates an object.
boolean	activate(java.lang.String rootName) This operation activates an object.
java.lang.Object	attributes()
protected void	cleanup(boolean fromTerminate) Object cleanup.
boolean	deactivate() This operation deactivates a persistent object.
boolean	deactivate(java.lang.String rootName) This operation deactivates a persistent object.
boolean	deactivate(java.lang.String rootName, boolean commit) This operation deactivates a persistent object.
boolean	destroy() Destroy the object (e.g., remove its state from the persistent store.) Calls to destroy for volatile objects (ones not maintained within the volatile object store) are ignored, and FALSE is returned.
void	disable() The following function disables recovery for an object by setting the ObjectType to NEITHER (RECOVERABLE or ANDPERSISTENT).
void	finalize() Destructor.
protected boolean	forgetAction(BasicAction action, boolean committed, int recordType) Remove action from list of using actions.
Uid	get_uid()
protected Mutex	getMutex()
ObjectStore	getStore()
java.lang.String	getStoreRoot()
protected boolean	loadObjectState() Do we need to load the object's state?
protected boolean	lockMutex()
protected boolean	modified() The object's state is about to be modified, and StateManager should take a snapshot of the state if the object is being used within a transaction.
int	ObjectType()
protected void	packHeader(OutputObjectState os, Uid txId, Uid processUid) Pack the necessary information for crash recovery.
protected void	persist() The persist function changes the type of the object from RECOVERABLE to ANDPERSISTENT.
void	print(java.io.PrintWriter strm) Print out information about the object.
protected boolean	rememberAction(BasicAction action, int recordType) Remember that the specified transaction is using the object.
boolean	restore_state(InputObjectState os, int ot) These methods must be provided by a derived class.
boolean	save_state(OutputObjectState os, int ot) These methods must be used by a derived class.
protected void	setStatus(int s)
protected void	setupStore() Make sure the object store is set up, if required.
protected void	setupStore(java.lang.String rootName) Make sure the object store is set up, if required.
int	status()
protected void	terminate() The following function checks to see if the object is going out of scope while an action is still running.
protected boolean	tryLockMutex()
java.lang.String	type() The object's type.
protected boolean	unlockMutex()
protected void	unpackHeader(InputObjectState os, Uid txId, Uid processUid) Unpack the crash recovery state header information and return it.

Methods inherited from class java.lang.Object

clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

smAttributes

protected StateManagerAttribute smAttributes

objectName

protected ObjectName objectName

modifyingActions

protected java.util.Hashtable modifyingActions

usingActions

protected java.util.Hashtable usingActions

objectUid

protected Uid objectUid

Constructor Detail

StateManager

protected StateManager(Uid objUid)

Create object with specific uid. This constructor is primarily used when recreating an existing object. The object type is set to 'ANDPERSISTENT' this is equivalent to invoking persist in the object constructor.

StateManager

protected StateManager(Uid objUid,
                       ObjectName attr)

StateManager

protected StateManager(Uid objUid,
                       int ot)

StateManager

protected StateManager(Uid objUid,
                       int ot,
                       ObjectName objName)

StateManager

protected StateManager()

StateManager

protected StateManager(int ot)

StateManager

protected StateManager(int ot,
                       ObjectName objName)

StateManager

protected StateManager(ObjectName objName)

Method Detail

save_state

public boolean save_state(OutputObjectState os,
                          int ot)

These methods must be used by a derived class. They are responsible for packing and unpacking an object's state to/from a state buffer. StateManager calls them at appropriate times during the lifetime of the object, and may then pass the buffer to a persistent object store for saving.

Returns:

true on success, false otherwise.

restore_state

public boolean restore_state(InputObjectState os,
                             int ot)

These methods must be provided by a derived class. They are responsible for packing and unpacking an object's state to/from a state buffer. StateManager calls them at appropriate times during the lifetime of the object, and may then pass the buffer to a persistent object store for saving.

Returns:

true on success, false otherwise.

finalize

public void finalize()
              throws java.lang.Throwable

Destructor.

Throws:

java.lang.Throwable

activate

public boolean activate()

This operation activates an object. Activation of an object may entail loading its passive state from the object store and unpacking it into the memory resident form, or it may simply be a no-op. Full activation is only necessary if the object is currently marked as being PASSIVE (that is, the object was constructed as being of type ANDPERSISTENT with an existing uid and has not already been activated). Objects that are not of type ANDPERSISTENT or are persistent but have not yet been saved in an object store (so-called new persistent objects) are unaffected by this function. Returns false if PASSIVE object cannot be loaded from object store, true otherwise. The root of the object store is taken as null.

Returns:

true on success, false otherwise.

See Also:

ObjectStore

activate

public boolean activate(java.lang.String rootName)

This operation activates an object. Activation of an object may entail loading its passive state from the object store and unpacking it into the memory resident form, or it may simply be a no-op. Full activation is only necessary if the object is currently marked as being PASSIVE (that is, the object was constructed as being of type ANDPERSISTENT with an existing uid and has not already been activated). Objects that are not of type ANDPERSISTENT or are persistent but have not yet been saved in an object store (so-called new persistent objects) are unaffected by this function. Returns false if PASSIVE object cannot be loaded from object store, true otherwise.

Returns:

true on success, false otherwise.

See Also:

ObjectStore

deactivate

public boolean deactivate()

This operation deactivates a persistent object. It behaves in a similar manner to the activate operation, but has an extra argument which defines whether the object's state should be committed or written as a shadow. The root of the object store is null. It is assumed that this is being called during a transaction commit.

Returns:

true on success, false otherwise.

deactivate

public boolean deactivate(java.lang.String rootName)

This operation deactivates a persistent object. It behaves in a similar manner to the activate operation, but has an extra argument which defines whether the object's state should be commited now or not. It is assumed that this is being called during a transaction commit.

Returns:

true on success, false otherwise.

deactivate

public boolean deactivate(java.lang.String rootName,
                          boolean commit)

This operation deactivates a persistent object. It behaves in a similar manner to the activate operation, but has an extra argument which defines whether the object's state should be commited now or not.

Returns:

true on success, false otherwise.

status

public int status()

Returns:

the object's current status (active, passive, ...)

ObjectType

public int ObjectType()

Returns:

the type of the object (persistent, recoverable, ...)

get_uid

public final Uid get_uid()

Returns:

the object's unique identifier.

destroy

public boolean destroy()

Destroy the object (e.g., remove its state from the persistent store.) Calls to destroy for volatile objects (ones not maintained within the volatile object store) are ignored, and FALSE is returned.

Returns:

true on success, false otherwise.

disable

public void disable()

The following function disables recovery for an object by setting the ObjectType to NEITHER (RECOVERABLE or ANDPERSISTENT). The value of this variable is checked in the modified operation so that no recovery information is created if myType is set to NEITHER.

print

public void print(java.io.PrintWriter strm)

Print out information about the object.

type

public java.lang.String type()

The object's type. Derived classes should override this to reflect their type structure. Typically this string is used for locating the object state in an object store, and reflects the hierarchy structure of the object.

getStoreRoot

public final java.lang.String getStoreRoot()

Returns:

the root of the object store this instance will use if it has to save the state of the object to storage.

getStore

public ObjectStore getStore()

Returns:

the object store this instance will used if it has to save the state of the object to storage.

attributes

public java.lang.Object attributes()

Returns:

object specific attributes (e.g., object store type).

packHeader

protected void packHeader(OutputObjectState os,
                          Uid txId,
                          Uid processUid)
                   throws java.io.IOException

Pack the necessary information for crash recovery.

Throws:

java.io.IOException

Since:

JTS 2.1.

unpackHeader

protected void unpackHeader(InputObjectState os,
                            Uid txId,
                            Uid processUid)
                     throws java.io.IOException

Unpack the crash recovery state header information and return it.

Parameters:

txId - the identity of the transaction that last caused the state to be written to the object store.

Returns:

the Uid of the process that last managed this state.

Throws:

java.io.IOException

Since:

JTS 2.1.

terminate

protected void terminate()

The following function checks to see if the object is going out of scope while an action is still running.

setStatus

protected final void setStatus(int s)

modified

protected boolean modified()

The object's state is about to be modified, and StateManager should take a snapshot of the state if the object is being used within a transaction.

Returns:

true on success, false otherwise.

persist

protected final void persist()

The persist function changes the type of the object from RECOVERABLE to ANDPERSISTENT. No changes are made unless the status of the object is ACTIVE, so it is not possible to change the type of the object if it has been modified.

cleanup

protected final void cleanup(boolean fromTerminate)

Object cleanup. Attempt sane cleanup when object is deleted. Handle perverse cases where multiple actions are still active as object dies.

Parameters:

fromTerminate - indicates whether this method is being called from the terminate method, or from elsewhere.

See Also:

terminate()

setupStore

protected final void setupStore()

Make sure the object store is set up, if required. The root of the object store is assumed to be null.

setupStore

protected void setupStore(java.lang.String rootName)

Make sure the object store is set up, if required.

Parameters:

rootName - indicates the root of the object store.

loadObjectState

protected final boolean loadObjectState()

Do we need to load the object's state?

Returns:

true if the object state should be loaded, false otherwise.

forgetAction

protected final boolean forgetAction(BasicAction action,
                                     boolean committed,
                                     int recordType)

Remove action from list of using actions. If the action list empties reset state to PASSIVE. The second param tells why the action should be forgotten. This aids in resetting the state correctly.

rememberAction

protected final boolean rememberAction(BasicAction action,
                                       int recordType)

Remember that the specified transaction is using the object.

getMutex

protected final Mutex getMutex()

Returns:

the mutex object used to lock this object.

Since:

JTS 2.1.

lockMutex

protected final boolean lockMutex()

Returns:

the result of the attempt to lock this object.

Since:

JTS 2.1.

unlockMutex

protected final boolean unlockMutex()

Returns:

the result of the attempt to unlock this object.

Since:

JTS 2.1.

tryLockMutex

protected final boolean tryLockMutex()

Returns:

true if the object was locked, false if the attempt would cause the thread to block.

Since:

JTS 2.1.