com.arjuna.ats.internal.jts.resources

Class ResourceRecord

java.lang.Object

com.arjuna.ats.arjuna.StateManager

com.arjuna.ats.arjuna.coordinator.AbstractRecord

com.arjuna.ats.internal.jts.resources.ResourceRecord

public class ResourceRecord
extends AbstractRecord

Arjuna abstract record to handle CORBA (SubtransactionAware)Resource interface. The OTS handling of Resources is bizarre (by Arjuna standards) and confusing Our current understanding is: Resources registered using 'register_resource' ONLY take part in top-level events SubtransactionAwareResources registered using 'register_subtran_aware' ONLY take part in commit/abort of the action in which they are registered - i.e. they DO NOT propagate automatically - the registering object must do the propagation itself using the parent arg in the 'commit_subtransaction' operation. If a SubtransactionAwareResource is registered with 'register_resource' then it will be propagated to the parent when the action commit. Otherwise it is only registered with the current transaction. Subtransactions do not have a 'prepare' phase which can thus lead to inconsistency. If they underwent the full 2-phase protocol (as they do in Arjuna), then all nested participants will have to repond successfully to prepare before they can be told to commit. The way the OTS mandates the protocol, we could tell some to commit before being told by another resource that it cannot commit! We then have to go through the resources and tell them to abort! May cause heuristic decisions! The only problem is if a resource which does not propagate causes a nested action to fail. SubtransactionAwareResources registered using 'register_resource' do appear to propagate. UGH! Braindead!

Since:

JTS 1.0.

Version:

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

Author:

Mark Little (mark@arjuna.com)

Field Summary

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

modifyingActions, objectModel, objectUid, usingActions

Constructor Summary

Constructors

Constructor and Description
ResourceRecord()
ResourceRecord(boolean propagate, Resource theResource, Coordinator myParent, Uid recCoordUid, ArjunaTransactionImple current) Constructor
ResourceRecord(boolean propagate, Resource theResource, Uid recCoordUid)

Method Summary

Modifier and Type	Method and Description
void	alter(AbstractRecord a) Alter the current record with the one presented.
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.
boolean	forgetHeuristic() Forget any heuristic outcome which this implementation may have produced.
Uid	getRCUid()
void	merge(AbstractRecord a) Merge the current record with the one presented.
int	nestedAbort() General nesting rules: Only SubtransactionAware resources get registered with nested actions.
int	nestedCommit() If this resource handles nesting this was done in prepare or it should be ignored.
int	nestedOnePhaseCommit() Perform a nested one phase commit.
int	nestedPrepare() OTS does not use nested prepare at all! However, to make nested commit/abort clean we do commit_subtransaction here.
void	print(PrintWriter strm) Write information about this specific instance to the specified stream.
boolean	propagateOnCommit() Determine if records are discarded on action commit or must be propagated to parents.
static void	remove(AbstractRecord toDelete)
Resource	resourceHandle()
boolean	restore_state(InputObjectState os, int t) restore_state and save_state for ResourceRecords doesn't generally apply due to object pointers.
boolean	save_state(OutputObjectState os, int t) 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(Object o)
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 rec) Should we replace the record presented with the current record?
int	topLevelAbort() A rollback of a top-level transaction has occurred.
int	topLevelCommit() A commit of a top-level transaction has occurred.
int	topLevelOnePhaseCommit() Perform a top-level one phase commit.
int	topLevelPrepare() A prepare for a top-level transaction has occurred.
String	type() Re-implementation of abstract methods inherited from base class.
int	typeIs()
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, getNext, getPrevious, getTypeOfObject, greaterThan, lessThan, nestedCleanup, order, propagateOnAbort, replace, setNext, setPrevious, topLevelCleanup

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

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

Methods inherited from class java.lang.Object

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

Constructor Detail

ResourceRecord

public ResourceRecord(boolean propagate,
                      Resource theResource,
                      Coordinator myParent,
                      Uid recCoordUid,
                      ArjunaTransactionImple current)

Constructor

Parameters:

propagate - tells us whether to propagate the resource at nested commit or not.

theResource - is the proxy that allows us to call out to the object.

myParent - is the proxy for the parent coordinator needed in commit_subtransaction.

ResourceRecord

public ResourceRecord(boolean propagate,
                      Resource theResource,
                      Uid recCoordUid)

ResourceRecord

public ResourceRecord()

Method Detail

resourceHandle

public final Resource resourceHandle()

propagateOnCommit

public boolean propagateOnCommit()

Description copied from class: AbstractRecord

Determine if records are discarded on action commit or must be propagated to parents.

Overrides:

propagateOnCommit in class AbstractRecord

Returns:

true if the record should be propagated to the parent transaction if the current transaction commits, false otherwise. The default is true.

typeIs

public int typeIs()

Specified by:

typeIs in class AbstractRecord

Returns:

RecordType value.

value

public 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(Object o)

Specified by:

setValue in class AbstractRecord

nestedAbort

public int nestedAbort()

General nesting rules: Only SubtransactionAware resources get registered with nested actions. The ResourceRecord creator is assumed to ensure that plain Resources are only registered with the appropriate top level action. That said the _propagateRecord flag ensures that resources registered via register_subtran only take part in the action they where registered in after which they are dropped

Specified by:

nestedAbort in class AbstractRecord

Returns:

TwoPhaseOutcome to indicate success/failure.

See Also:

TwoPhaseOutcome

nestedCommit

public int nestedCommit()

If this resource handles nesting this was done in prepare or it should be ignored. In either case returning FINISH_OK suffices.

Specified by:

nestedCommit in class AbstractRecord

Returns:

TwoPhaseOutcome to indicate success/failure.

See Also:

TwoPhaseOutcome

nestedPrepare

public int nestedPrepare()

OTS does not use nested prepare at all! However, to make nested commit/abort clean we do commit_subtransaction here. Note that we only get a prepare from Arjuna if the action is to be committed so this is safe in Arjuna terms.

Specified by:

nestedPrepare in class AbstractRecord

Returns:

TwoPhaseOutcome to indicate success/failure.

See Also:

TwoPhaseOutcome

topLevelAbort

public int topLevelAbort()

Description copied from class: AbstractRecord

A rollback of a top-level transaction has occurred.

Specified by:

topLevelAbort in class AbstractRecord

Returns:

TwoPhaseOutcome to indicate success/failure.

See Also:

TwoPhaseOutcome

topLevelCommit

public int topLevelCommit()

Description copied from class: AbstractRecord

A commit of a top-level transaction has occurred.

Specified by:

topLevelCommit in class AbstractRecord

Returns:

TwoPhaseOutcome to indicate success/failure.

See Also:

TwoPhaseOutcome

topLevelPrepare

public int topLevelPrepare()

Description copied from class: AbstractRecord

A prepare for a top-level transaction has occurred.

Specified by:

topLevelPrepare in class AbstractRecord

Returns:

TwoPhaseOutcome to indicate success/failure.

See Also:

TwoPhaseOutcome

nestedOnePhaseCommit

public int nestedOnePhaseCommit()

Description copied from class: AbstractRecord

Perform a nested one phase commit.

Overrides:

nestedOnePhaseCommit in class AbstractRecord

Returns:

TwoPhaseOutcome to indicate success/failure.

See Also:

TwoPhaseOutcome

topLevelOnePhaseCommit

public int topLevelOnePhaseCommit()

Description copied from class: AbstractRecord

Perform a top-level one phase commit.

Overrides:

topLevelOnePhaseCommit in class AbstractRecord

Returns:

TwoPhaseOutcome to indicate success/failure.

See Also:

TwoPhaseOutcome

forgetHeuristic

public boolean forgetHeuristic()

Description copied from class: AbstractRecord

Forget any heuristic outcome which this implementation may have produced.

Overrides:

forgetHeuristic in class AbstractRecord

Returns:

true by default. If false is returned then the instance must be remembered by the transaction (in the log) in order for recovery to retry later or for a system administrator to be able to determine which resources have not been successfully completed.

remove

public static void remove(AbstractRecord toDelete)

print

public void print(PrintWriter strm)

Description copied from class: AbstractRecord

Write information about this specific instance to the specified stream.

Overrides:

print in class AbstractRecord

Parameters:

strm - the stream on which to output.

restore_state

public boolean restore_state(InputObjectState os,
                             int t)

restore_state and save_state for ResourceRecords doesn't generally apply due to object pointers. However, we need to save something so we can recover failed transactions. So, rather than insist that all Resources derive from a class which we can guarantee will give us some unique id, we simply rely on string_to_object and object_to_string to be meaningful.

Overrides:

restore_state in class AbstractRecord

Returns:

true if successful, false otherwise.

save_state

public boolean save_state(OutputObjectState os,
                          int t)

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. If a derived class calls super.save_state then it must be called before packing any other data item.

Overrides:

save_state in class AbstractRecord

Returns:

true if successful, false otherwise.

type

public String type()

Description copied from class: AbstractRecord

Re-implementation of abstract methods inherited from base class.

Overrides:

type in class AbstractRecord

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).

Overrides:

doSave in class AbstractRecord

Returns:

true if it should be saved, false otherwise. false is the default.

getRCUid

public final Uid getRCUid()

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

Parameters:

a - the record with which to merge.

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

Parameters:

a - the record with which to alter.

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

Parameters:

a - The record to try to add.

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

Parameters:

a - The record to try to alter.

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

Parameters:

a - The record to try to merge.

Returns:

true if the record should be merged, false otherwise.

shouldReplace

public boolean shouldReplace(AbstractRecord rec)

Description copied from class: AbstractRecord

Should we replace the record presented with the current record?

Specified by:

shouldReplace in class AbstractRecord

Parameters:

rec - The record to try to replace.

Returns:

true if the record should be replaced, false otherwise.