com.sun.sgs.impl.kernel
Class TrackingAccessCoordinator

java.lang.Object
  com.sun.sgs.impl.kernel.AbstractAccessCoordinator
      com.sun.sgs.impl.kernel.TrackingAccessCoordinator

All Implemented Interfaces:

AccessCoordinatorHandle, AccessCoordinator, NonDurableTransactionParticipant, TransactionParticipant

 class TrackingAccessCoordinator
extends AbstractAccessCoordinator
implements NonDurableTransactionParticipant

A package-private implementation of AccessCoordinator that is used by the system to track access to objects and handle any possible conflict. This implementation is also responsible for reporting the access detail to the profiling system.

This implementation provides the option to keep detail on a backlog of past transactions to discover what may have caused conflict. This is currently only useful for ProfileListeners that wish to diplay this detail. By default this backlog tracking is disabled. To enable, set the com.sun.sgs.impl.kernel.TrackingAccessCoordinator.queue.size property to some positive value indicating the length of backlog to use. Note that with each transaction failure this backlog will be scanned to find a conflicting transaction, so a larger backlog may provide more detail about failure but will also be more compute-intensive.

Nested Class Summary

Nested classes/interfaces inherited from class com.sun.sgs.impl.kernel.AbstractAccessCoordinator

AbstractAccessCoordinator.AbstractAccessReporter<T>

Field Summary

(package private) static String

BACKLOG_QUEUE_PROPERTY The property to set the size of the backlog and enable transaction conflict detail reporting.

Fields inherited from class com.sun.sgs.impl.kernel.AbstractAccessCoordinator

profileCollectorHandle, txnProxy

Constructor Summary

TrackingAccessCoordinator(Properties properties, TransactionProxy txnProxy, ProfileCollectorHandle profileCollector)
Creates an instance of TrackingAccessCoordinator.

Method Summary

void	abort(Transaction txn) Tells the participant to abort its involvement with the given transaction.
void	commit(Transaction txn) Tells the participant to commit its state associated with the given transaction.
Transaction	getConflictingTransaction(Transaction txn) Find out what transaction, if still active, caused the given transaction to fail due to conflict.
String	getTypeName() Returns the fully qualified type name of the participant.
void	notifyNewTransaction(Transaction txn, long requestedStartTime, int tryCount) Notifies the coordinator that a new transaction is starting.
boolean	prepare(Transaction txn) Tells the participant to prepare for commiting its state associated with the given transaction.
void	prepareAndCommit(Transaction txn) Tells the participant to both prepare and commit its state associated with the given transaction.
<T> AccessReporter<T>	registerAccessSource(String sourceName, Class<T> objectIdType) Register as a provider of shared objects, and therefore a possible source of conflict between transactions.

Methods inherited from class java.lang.Object

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

Field Detail

BACKLOG_QUEUE_PROPERTY

static final String BACKLOG_QUEUE_PROPERTY

The property to set the size of the backlog and enable transaction conflict detail reporting. The value set by this property must be non-negative.

Constructor Detail

TrackingAccessCoordinator

TrackingAccessCoordinator(Properties properties,
                          TransactionProxy txnProxy,
                          ProfileCollectorHandle profileCollector)

Creates an instance of TrackingAccessCoordinator.

Throws:

IllegalArgumentException - if the requested backlog queue size is not a valid number greater than 0

Method Detail

registerAccessSource

public <T> AccessReporter<T> registerAccessSource(String sourceName,
                                                  Class<T> objectIdType)

Register as a provider of shared objects, and therefore a possible source of conflict between transactions. This should be used by any component that is providing access to shared objects (e.g., the DataService which provides access to ManagedObjects and name bindings). This ensures that conflict is managed for access to the reported objects, and that a report of all accesses is available through profiling.

Specified by:

registerAccessSource in interface AccessCoordinator

Type Parameters:

T - the type of the id object used to report accesses

Parameters:

sourceName - the name of the source of objects which may cause conflict on access

objectIdType - the type of the identifier that will be used to identify accessed objects

Returns:

an AccessReporter used to notify the system of access to shared objects

getConflictingTransaction

public Transaction getConflictingTransaction(Transaction txn)

Find out what transaction, if still active, caused the given transaction to fail due to conflict. This is particularly useful if you want to wait for that active transaction to finish, e.g. for re-trying the failed transaction.

Specified by:

getConflictingTransaction in interface AccessCoordinator

Parameters:

txn - a Transaction that failed due to conflict

Returns:

the active Transaction that caused the provided Transaction to fail due to conflict, or null if there is no such active Transaction

notifyNewTransaction

public void notifyNewTransaction(Transaction txn,
                                 long requestedStartTime,
                                 int tryCount)

Notifies the coordinator that a new transaction is starting.

Specified by:

notifyNewTransaction in interface AccessCoordinatorHandle

Parameters:

txn - the transaction

requestedStartTime - the time in milliseconds that the task associated with the transaction was originally requested to start

tryCount - the number of times that transactions have been attempted for the task associated with txn

prepare

public boolean prepare(Transaction txn)

Tells the participant to prepare for commiting its state associated with the given transaction. This method returns a boolean flag stating whether the prepared state is read-only, meaning that no external state is modified by this participant. If this method returns true, then neither commit nor abort will be called.

If this method throws an exception, then the preparation failed, and the transaction will be aborted. If this method completes successfully, then the participant is required to be able to commit the transaction without failure.

Specified by:

prepare in interface TransactionParticipant

Parameters:

txn - the Transaction object

Returns:

true if this participant is read-only, false otherwise

commit

public void commit(Transaction txn)

Tells the participant to commit its state associated with the given transaction.

Specified by:

commit in interface TransactionParticipant

Parameters:

txn - the Transaction object

prepareAndCommit

public void prepareAndCommit(Transaction txn)

Tells the participant to both prepare and commit its state associated with the given transaction.

Specified by:

prepareAndCommit in interface TransactionParticipant

Parameters:

txn - the Transaction object

abort

public void abort(Transaction txn)

Tells the participant to abort its involvement with the given transaction.

Specified by:

abort in interface TransactionParticipant

Parameters:

txn - the Transaction object

getTypeName

public String getTypeName()

Returns the fully qualified type name of the participant. If this participant is acting as a proxy for a Service, this will typically be the Service's type name.

Specified by:

getTypeName in interface TransactionParticipant

Returns:

the name of the participant