com.arjuna.ats.arjuna
Class PersistenceRecord

java.lang.Object
  com.arjuna.ats.arjuna.StateManager
      com.arjuna.ats.arjuna.coordinator.AbstractRecord
          com.arjuna.ats.arjuna.RecoveryRecord
              com.arjuna.ats.arjuna.PersistenceRecord

Direct Known Subclasses:

CadaverRecord

public class PersistenceRecord

extends com.arjuna.ats.arjuna.RecoveryRecord

A PersistenceRecord is created whenever a persistent object is created/read/modified within the scope of a transaction. It is responsible for ensuring that state changes are committed or rolled back on behalf of the object depending upon the outcome of the transaction.

Since:

JTS 1.0.

Version:

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

Author:

Mark Little (mark@arjuna.com)

Field Summary

protected static boolean	classicPrepare
static int	MAX_OBJECT_SIZE
protected StateManager	objectAddr
protected boolean	shadowMade
protected OutputObjectState	state
protected ObjectStore	store
protected OutputObjectState	topLevelState

Fields inherited from class com.arjuna.ats.arjuna.StateManager

modifyingActions, objectName, objectUid, smAttributes, usingActions

Constructor Summary

protected	PersistenceRecord() Creates a 'blank' persistence record.
	PersistenceRecord(OutputObjectState os, ObjectStore objStore, StateManager sm) This constructor is used to create a new instance of PersistenceRecord.

Method Summary

void	alter(AbstractRecord a) Alter the current record with the one presented.
ClassName	className() Only used for crash recovery, so most records don't need it.
static AbstractRecord	create()
boolean	doSave() Should this record be saved in the intentions list? If the record is saved, then it may be recovered later in the event of a failure.
void	finalize() Destructor.
protected void	forgetAction(boolean commit)
void	merge(AbstractRecord a) Merge the current record with the one presented.
int	nestedAbort() nestedAbort causes the restore_state function of the object to be invoked passing it the saved ObjectState.
int	nestedCommit() nestedCommit does nothing since the passing of the state up to the parent action is handled by the record list merging system.
int	nestedPrepare() A prepare for a nested transaction has occurred.
void	print(java.io.PrintWriter strm) Write information about this specific instance to the specified stream.
boolean	restore_state(InputObjectState os, int ot) During recovery, the transaction log is given to the recovery system and it will recreate a transaction instance to perform necessary recovery actions.
boolean	save_state(OutputObjectState os, int ot) When the transaction is required to make the intentions list persistent, it scans the list and asks each record whether or not it requires state to be saved (by calling doSave).
void	setValue(java.lang.Object newState)
protected boolean	shadowForced() Cadaver records force write shadows.
boolean	shouldAdd(AbstractRecord a) Should we add the record presented to the intentions list?
boolean	shouldAlter(AbstractRecord a) Should we alter the current record with the one presented?
boolean	shouldMerge(AbstractRecord a) Should we merge the current record with the one presented?
boolean	shouldReplace(AbstractRecord a) Should we replace the record presented with the current record?
int	topLevelAbort() topLevelAbort may have to remove the persistent state that was written into the object store during the processing of topLevelPrepare.
int	topLevelCleanup() topLevelCleanup must leave the persistent state that was written in the object store during the processing of topLevelPrepare intact.
int	topLevelCommit() commit the state saved during the prepare phase.
int	topLevelPrepare() topLevelPrepare attempts to save the object.
java.lang.String	type() Re-implementation of abstract methods inherited from base class.
int	typeIs() Redefintions of abstract functions inherited from RecoveryRecord.
java.lang.Object	value() If this abstract record caused a heuristic then it should return an object which implements HeuristicInformation

Methods inherited from class com.arjuna.ats.arjuna.coordinator.AbstractRecord

create, equals, forgetHeuristic, getNext, getPrevious, getTypeOfObject, greaterThan, lessThan, nestedCleanup, nestedOnePhaseCommit, order, propagateOnAbort, propagateOnCommit, replace, setNext, setPrevious, topLevelOnePhaseCommit

Methods inherited from class com.arjuna.ats.arjuna.StateManager

activate, activate, attributes, cleanup, deactivate, deactivate, deactivate, destroy, disable, forgetAction, get_uid, getMutex, getStore, getStoreRoot, loadObjectState, lockMutex, modified, ObjectType, packHeader, persist, rememberAction, setStatus, setupStore, setupStore, status, terminate, tryLockMutex, unlockMutex, unpackHeader

Methods inherited from class java.lang.Object

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

Field Detail

MAX_OBJECT_SIZE

public static final int MAX_OBJECT_SIZE

See Also:

Constant Field Values

shadowMade

protected boolean shadowMade

store

protected ObjectStore store

topLevelState

protected OutputObjectState topLevelState

classicPrepare

protected static boolean classicPrepare

objectAddr

protected StateManager objectAddr

state

protected OutputObjectState state

Constructor Detail

PersistenceRecord

public PersistenceRecord(OutputObjectState os,
                         ObjectStore objStore,
                         StateManager sm)

This constructor is used to create a new instance of PersistenceRecord.

PersistenceRecord

protected PersistenceRecord()

Creates a 'blank' persistence record. This is used during crash recovery when recreating the prepared list of a server atomic action.

Method Detail

finalize

public void finalize()

Description copied from class: StateManager

Destructor.

typeIs

public int typeIs()

Redefintions of abstract functions inherited from RecoveryRecord.

className

public ClassName className()

Description copied from class: AbstractRecord

Only used for crash recovery, so most records don't need it.

Overrides:

className in class AbstractRecord

Returns:

ClassName to identify this abstract record.

topLevelAbort

public int topLevelAbort()

topLevelAbort may have to remove the persistent state that was written into the object store during the processing of topLevelPrepare. It then does the standard abort processing.

topLevelCommit

public int topLevelCommit()

commit the state saved during the prepare phase.

topLevelPrepare

public int topLevelPrepare()

topLevelPrepare attempts to save the object. It will either do this in the action intention list or directly in the object store by using the 'deactivate' function of the object depending upon the size of the state. To ensure that objects are correctly hidden while they are in an uncommitted state if we use the abbreviated protocol then we write an EMPTY object state as the shadow state - THIS MUST NOT BE COMMITTED. Instead we write_committed the one saved in the intention list. If the store cannot cope with being given an empty state we revert to the old protocol.

topLevelCleanup

public int topLevelCleanup()

topLevelCleanup must leave the persistent state that was written in the object store during the processing of topLevelPrepare intact. Crash recovery will take care of its resolution

Overrides:

topLevelCleanup in class AbstractRecord

Returns:

TwoPhaseOutcome as default is the same as topLevelAbort.

doSave

public boolean doSave()

Description copied from class: AbstractRecord

Should this record be saved in the intentions list? If the record is saved, then it may be recovered later in the event of a failure. Note, however, that the size of the intentions list on disk is critical to the performance of the system (disk I/O is a bottleneck).

Returns:

true

restore_state

public boolean restore_state(InputObjectState os,
                             int ot)

Description copied from class: AbstractRecord

During recovery, the transaction log is given to the recovery system and it will recreate a transaction instance to perform necessary recovery actions. This transaction will recreate the intentions list and give each recreated AbstractRecord the state that that was saved during transaction persistence. The base class will restore information that it needs from the log.

save_state

public boolean save_state(OutputObjectState os,
                          int ot)

Description copied from class: AbstractRecord

When the transaction is required to make the intentions list persistent, it scans the list and asks each record whether or not it requires state to be saved (by calling doSave). If the answer is yes, then save_state is called and the record instance must save enough information to enable it to be restored from that state later. The basic AbstractRecord save_state will save common data that is required by the base class during recovery.

print

public void print(java.io.PrintWriter strm)

Description copied from class: AbstractRecord

Write information about this specific instance to the specified stream.

type

public java.lang.String type()

Description copied from class: AbstractRecord

Re-implementation of abstract methods inherited from base class.

create

public static AbstractRecord create()

shadowForced

protected boolean shadowForced()

Cadaver records force write shadows. This operation supresses to abbreviated commit This should never return false

value

public java.lang.Object value()

Description copied from class: AbstractRecord

If this abstract record caused a heuristic then it should return an object which implements HeuristicInformation

Specified by:

value in class AbstractRecord

Returns:

Object to be used to order.

setValue

public void setValue(java.lang.Object newState)

Specified by:

setValue in class AbstractRecord

nestedAbort

public int nestedAbort()

nestedAbort causes the restore_state function of the object to be invoked passing it the saved ObjectState.

Specified by:

nestedAbort in class AbstractRecord

Returns:

TwoPhaseOutcome to indicate success/failure.

See Also:

TwoPhaseOutcome

nestedCommit

public int nestedCommit()

nestedCommit does nothing since the passing of the state up to the parent action is handled by the record list merging system. In fact since nestedPrepare returns PREPARE_READONLY this function should never actaully be called

Specified by:

nestedCommit in class AbstractRecord

Returns:

TwoPhaseOutcome to indicate success/failure.

See Also:

TwoPhaseOutcome

nestedPrepare

public int nestedPrepare()

Description copied from class: AbstractRecord

A prepare for a nested transaction has occurred.

Specified by:

nestedPrepare in class AbstractRecord

Returns:

TwoPhaseOutcome to indicate success/failure.

See Also:

TwoPhaseOutcome

merge

public void merge(AbstractRecord a)

Description copied from class: AbstractRecord

Merge the current record with the one presented.

Specified by:

merge in class AbstractRecord

alter

public void alter(AbstractRecord a)

Description copied from class: AbstractRecord

Alter the current record with the one presented.

Specified by:

alter in class AbstractRecord

shouldAdd

public boolean shouldAdd(AbstractRecord a)

Description copied from class: AbstractRecord

Should we add the record presented to the intentions list?

Specified by:

shouldAdd in class AbstractRecord

Returns:

true if the record should be added, false otherwise.

shouldAlter

public boolean shouldAlter(AbstractRecord a)

Description copied from class: AbstractRecord

Should we alter the current record with the one presented?

Specified by:

shouldAlter in class AbstractRecord

Returns:

true if the record should be altered, false otherwise.

shouldMerge

public boolean shouldMerge(AbstractRecord a)

Description copied from class: AbstractRecord

Should we merge the current record with the one presented?

Specified by:

shouldMerge in class AbstractRecord

Returns:

true if the record should be merged, false otherwise.

shouldReplace

public boolean shouldReplace(AbstractRecord a)

Description copied from class: AbstractRecord

Should we replace the record presented with the current record?

Specified by:

shouldReplace in class AbstractRecord

Returns:

true if the record should be replaced, false otherwise.

forgetAction

protected final void forgetAction(boolean commit)