com.sun.sgs.kernel
Interface AccessReporter<T>

Type Parameters:

T - the type of the identifier used to identify accessed objects

All Known Implementing Classes:

AbstractAccessCoordinator.AbstractAccessReporter, NullAccessCoordinator

public interface AccessReporter<T>

Used to report to the AccessCoordinator when access is requested to a shared object. Methods must be called in the context of an active transaction, or provide a transaction in which the context of the request took place. The latter option is primarily provided for services to report accesses that were only detected during the prepare phase when the transaction is no longer active.

All methods of AccessReporter take an object identifier as a parameter. This parameter must implement equals() and hashCode(). To make the resulting detail provided to the profiler as useful as possible, the identifier should have a meaningful toString() method. Other than this the identifier may be any arbitrary instance, including the requested object itself, as long as it uniquely identifies the object across transactions.

For the reportObjectAccess methods, access should be reported as early as possible. In particular, if actually resolving or retrieving the object could fail, or incur any significant expense, the report should be made first. This is to ensure that access is always noted, and has the chance to abort the transaction before any unneeded processing is done. For instance, in the case of the DataService, before a name binding is resolved in the getBinding method, the requested access to that bound object should be reported.

If the implementation of the reportObjectAccess methods detect a conflict and wish to cause the calling transaction to fail, they will abort the transaction and then throw a TransactionAbortedException.

Nested Class Summary

static class

AccessReporter.AccessType The type of access requested.

Method Summary

void	reportObjectAccess(T objId, AccessReporter.AccessType type) Reports to the coordinator that object access has been requested in the context of the current transaction.
void	reportObjectAccess(T objId, AccessReporter.AccessType type, Object description) Reports to the coordinator that an object access with the provided description has been requested in the context of the current transaction.
void	reportObjectAccess(Transaction txn, T objId, AccessReporter.AccessType type) Reports to the coordinator that object access has been requested in the context of the provided transaction.
void	reportObjectAccess(Transaction txn, T objId, AccessReporter.AccessType type, Object description) Reports to the coordinator that an object access with the provided description has been requested in the context of the provided transaction.
void	setObjectDescription(T objId, Object description) In the current transaction, associates the given object with some description that should have a meaningful toString method.
void	setObjectDescription(Transaction txn, T objId, Object description) In the provided transaction, associates the given object with some description that should have a meaningful toString method.

Method Detail

reportObjectAccess

void reportObjectAccess(T objId,
                        AccessReporter.AccessType type)

Reports to the coordinator that object access has been requested in the context of the current transaction. The requested object is shared, and may be the cause of conflict.

Parameters:

objId - an identifier for the object being accessed

type - the AccessType being requested

Throws:

TransactionNotActiveException - if not called in the context of an active transaction

TransactionAbortedException - if access failed due to a conflict

reportObjectAccess

void reportObjectAccess(Transaction txn,
                        T objId,
                        AccessReporter.AccessType type)

Reports to the coordinator that object access has been requested in the context of the provided transaction. The requested object is shared, and may be the cause of conflict.

Parameters:

txn - the transaction in which the provided objId was accessed

objId - an identifier for the object being accessed

type - the AccessType being requested

Throws:

IllegalArgumentException - if the provided transaction is invalid, has already committed, or is otherwise unknown to the AccessCoordinator

TransactionAbortedException - if access failed due to a conflict

reportObjectAccess

void reportObjectAccess(T objId,
                        AccessReporter.AccessType type,
                        Object description)

Reports to the coordinator that an object access with the provided description has been requested in the context of the current transaction. The requested object is shared, and may be the cause of conflict. See setObjectDescription for more details about description.

Parameters:

objId - an identifier for the object being accessed

type - the AccessType being requested

description - an arbitrary object that contains a description of the object being accessed

Throws:

TransactionNotActiveException - if not called in the context of an active transaction

TransactionAbortedException - if access failed due to a conflict

reportObjectAccess

void reportObjectAccess(Transaction txn,
                        T objId,
                        AccessReporter.AccessType type,
                        Object description)

Reports to the coordinator that an object access with the provided description has been requested in the context of the provided transaction. The requested object is shared, and may be the cause of conflict. See setObjectDescription for more details about description.

Parameters:

txn - the transaction in which the provided objId was accessed

objId - an identifier for the object being accessed

type - the AccessType being requested

description - an arbitrary object that contains a description of the object being accessed

Throws:

IllegalArgumentException - if the provided transaction is invalid, has already committed, or is otherwise unknown to the AccessCoordinator

TransactionAbortedException - if access failed due to a conflict

setObjectDescription

void setObjectDescription(T objId,
                          Object description)

In the current transaction, associates the given object with some description that should have a meaningful toString method. This description will be available in the profiling data, and is useful when displaying details about a given accessed object. The intent is that an arbitrary description can be included with an object, but that the description is not accessed unless a ProfileListener finds it useful to do so. At that point the description's toString method may be called, or the object itself might be cast to some known type to extract more detail about the accessed object.

Note that this may be called before the associated object is actually accessed, and therefore before reportObjectAccess is called for the given objId. Use of this method is optional, and only used to provide additional detail for profiling and debugging.

If a description has already been set for the identified object, or if the provided description is null, then no change is made to the description of the object.

Parameters:

objId - the identifier for the associated object

description - an arbitrary Object that contains a description of the objId being accessed

Throws:

TransactionNotActiveException - if not called in the context of an active transaction

setObjectDescription

void setObjectDescription(Transaction txn,
                          T objId,
                          Object description)

In the provided transaction, associates the given object with some description that should have a meaningful toString method. This description will be available in the profiling data, and is useful when displaying details about a given accessed object. The intent is that an arbitrary description can be included with an object, but that the description is not accessed unless a ProfileListener finds it useful to do so. At that point the description's toString method may be called, or the object itself might be cast to some known type to extract more detail about the accessed object.

Note that this may be called before the associated object is actually accessed, and therefore before reportObjectAccess is called for the given objId. Use of this method is optional, and only used to provide additional detail for profiling and debugging.

If a description has already been set for the identified object, or if the provided description is null, then no change is made to the description of the object.

Parameters:

txn - the transaction in which the provided objId was accessed

objId - the identifier for the associated object

description - an arbitrary Object that contains a description of the objId being accessed

Throws:

IllegalArgumentException - if the provided transaction is invalid, has already committed, or is otherwise unknown to the AccessCoordinator