com.sun.sgs.service
Interface TransactionParticipant

All Known Subinterfaces:

NonDurableTransactionParticipant

public interface TransactionParticipant

This interface is used by participants in transactions. Typically, each implementation of Service will either implement TransactionParticipant directly, or use some proxy as their participant. Classes that implement TransactionParticipant must also implement Serializable.

Note that the general model assumes that Services will use each other during a transaction. For instance, most Services will use the DataService to persist data. However once the transaction begins to prepare or is aborted (i.e., once any of the methods defined here are called on a participant), a Service may not interact with any other Service in the context of that transaction. Doing so results in unspecified behavior.

This interface does not specify how transaction participants learn the outcome of prepared transactions following a crash. Doing so requires a separate interaction between the participant and the transaction coordinator that is not specified by this interface. Without that additional communication, this interface is sufficient to support transactions with at most one durable transaction participant.

See Also:

NonDurableTransactionParticipant

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.
String	getTypeName() Returns the fully qualified type name of the participant.
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.

Method Detail

prepare

boolean prepare(Transaction txn)
                throws Exception

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.

Parameters:

txn - the Transaction object

Returns:

true if this participant is read-only, false otherwise

Throws:

Exception - if there are any failures in preparing

IllegalStateException - if this participant has already been prepared, committed, or aborted, or if this participant is not participating in the given transaction

commit

void commit(Transaction txn)

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

Parameters:

txn - the Transaction object

Throws:

IllegalStateException - if this participant was not previously prepared, or if this participant has already committed or aborted, or if this participant is not participating in the given transaction

prepareAndCommit

void prepareAndCommit(Transaction txn)
                      throws Exception

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

Parameters:

txn - the Transaction object

Throws:

Exception - if there are any failures in preparing

IllegalStateException - if this participant has already been prepared, committed, or aborted, or if this participant is not participating in the given transaction

abort

void abort(Transaction txn)

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

Parameters:

txn - the Transaction object

Throws:

IllegalStateException - if this participant has already been aborted or committed, or if this participant is not participating in the given transaction

getTypeName

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.

Returns:

the name of the participant