com.atomikos.icatch

Interface Participant

All Superinterfaces:

java.io.Serializable

public interface Participant
extends java.io.Serializable

A participant for (distributed) two-phase commit of composite transactions. Implementations can be added as a 2PC participant in the icatch kernel. VERY IMPORTANT: implementations should also override the default equals and hashCode methods, in order for two-phase commit to work properly!

Field Summary

Fields

Modifier and Type	Field and Description
static int	READ_ONLY Indicates that no commit/rollback is needed after prepare.

Method Summary

Methods

Modifier and Type	Method and Description
void	commit(boolean onePhase) Commits the participant's work.
void	forget() Indicates that a heuristic participant can forget about its work.
java.lang.String	getResourceName()
java.lang.String	getURI()
boolean	isRecoverable() Is this instance recoverable or not?
int	prepare() Prepares the participant.
void	rollback() Rollback of the participant's work.
void	setCascadeList(java.util.Map<java.lang.String,java.lang.Integer> allParticipants) For cascading 2PC, this method sets the information needed to cascade.
void	setGlobalSiblingCount(int count) Set by the root coordinator: the total no of siblings detected.

Field Detail

READ_ONLY

static final int READ_ONLY

Indicates that no commit/rollback is needed after prepare.

See Also:

Constant Field Values

Method Detail

getURI

java.lang.String getURI()

Returns:

String The unique URI for this remote participant, or null for local instances.

setCascadeList

void setCascadeList(java.util.Map<java.lang.String,java.lang.Integer> allParticipants)
                    throws SysException

For cascading 2PC, this method sets the information needed to cascade. This method is relevant only for transaction monitors; leave empty otherwise!

Parameters:

allParticipants - The information needed by the transaction monitor.

Throws:

SysException

setGlobalSiblingCount

void setGlobalSiblingCount(int count)

Set by the root coordinator: the total no of siblings detected. This method is relevant only for transaction monitors; leave empty otherwise!

Parameters:

count - The global count.

prepare

int prepare()
            throws RollbackException,
                   HeurHazardException,
                   HeurMixedException,
                   SysException

Prepares the participant. Any locks for this participant's work should be recoverable (either saved to an external file OR be part of the instance's non-transient state so that they can be flushed into the transaction manager's log).

Returns:

int READ_ONLY if no second round is needed. Participants that return this value on prepare will not be called by commit or rollback afterwards.

Throws:

RollbackException - For a NO vote. This indicates that the participant has already rolled back (or marked for rollback) the work on behalf of this participant.

HeurHazardException - On possible conflicts. This happens for remote participants instances, in case of communication failures.

HeurMixedException - If some subordinate participants voted YES, timed out and committed heuristically whereas afterwards some NO votes where received.

SysException

commit

void commit(boolean onePhase)
            throws HeurRollbackException,
                   HeurHazardException,
                   HeurMixedException,
                   RollbackException,
                   SysException

Commits the participant's work. NOTE: custom participant implementations should preferably be made for the server's local VM (e.g., it is better not to do this over RMI). Also, they should rely on the transaction manager for heuristic timeout (and NOT decide to terminate heuristically themselves). In that case, implementations never need to throw any of the heuristic exceptions of this method.

Parameters:

onePhase - If true, one-phase commit is being started. If the participant has received a prepare call earlier, then it should throw a SysException here.

Throws:

HeuristicRollbackException - If the participant has rolled back.

HeuristicMixedException - If part of it was rolled back.

HeurHazardException - On possible conflicts.

RollbackException - In case of one-phase commit, and the transaction has been rolled back at the time commit is called.

SysException

HeurRollbackException

HeurMixedException

rollback

void rollback()
              throws HeurCommitException,
                     HeurMixedException,
                     HeurHazardException,
                     SysException

Rollback of the participant's work. NOTE: custom participant implementations should preferably be made for the server's local VM (e.g., it is better not to do this over RMI). Also, they should rely on the icatch transaction manager for heuristic timeout (and NOT decide to terminate heuristically themselves). In that case, implementations never need to throw any of the heuristic exceptions of this method.

Throws:

HeurCommitException - If the participant committed.

HeurHazardException - If the participant's final state is unsure.

HeurMixedException - If part of the work was rolled back.

SysException

forget

void forget()

Indicates that a heuristic participant can forget about its work. If implementations rely on the transaction manager to decide when to do heuristics (rather then deciding in the participant implementation), then leave this method empty.

isRecoverable

boolean isRecoverable()

Is this instance recoverable or not?

Returns:

True in most cases, false only for particular border cases that do not need recovery, such as read-only instances.

getResourceName

java.lang.String getResourceName()

Returns:

The (unique) name of the recoverable resource as known in the configuration. Null if not relevant.