com.atomikos.icatch.imp
Class CoordinatorImp

java.lang.Object
  com.atomikos.icatch.imp.CoordinatorImp

All Implemented Interfaces:

FSMPreEnterEventSource, FSMPreEnterListener, Stateful, CompositeCoordinator, Participant, RecoveryCoordinator, Recoverable, StateRecoverable, AlarmTimerListener, Identifiable, Serializable, EventListener

public class CoordinatorImp
extends Object
implements CompositeCoordinator, Participant, RecoveryCoordinator, StateRecoverable, AlarmTimerListener, Stateful, FSMPreEnterListener

Implementation of termination logic.

See Also:

Serialized Form

Field Summary

Fields inherited from interface com.atomikos.icatch.Participant

READ_ONLY

Constructor Summary

	CoordinatorImp() No argument constructor as required by Recoverable interface.
protected	CoordinatorImp(String root, boolean heuristic_commit, boolean checkorphans) Constructor for testing only.
	CoordinatorImp(String root, RecoveryCoordinator coord, boolean heuristic_commit, boolean checkorphans) Constructor.
protected	CoordinatorImp(String root, RecoveryCoordinator coord, boolean heuristic_commit, long timeout, boolean checkorphans, boolean single_threaded_2pc) Constructor.

Method Summary

void	addFSMEnterListener(FSMEnterListener l, Object state)
void	addFSMPreEnterListener(FSMPreEnterListener l, Object state)
RecoveryCoordinator	addParticipant(Participant participant)
void	alarm(AlarmTimer timer) Notify the instance of an alarm coming from a timer.
HeuristicMessage[]	commit(boolean onePhase) Commits the participant's work.
HeuristicMessage[]	commitHeuristically()
protected void	dispose() For cleaning up properly.
void	forget() Indicates that a heuristic participant can forget about its work.
String	getCoordinatorId()
Object[]	getFinalStates() Needed by the Recovery system to determine when a logged state can be forgotten.
HeuristicMessage[]	getHeuristicMessages() Get the heuristic info for the message round.
HeuristicMessage[]	getHeuristicMessages(Object heuristicState) Gets the heuristic messages for all participants that are in the given heuristic state
Object	getId() Get the id.
ObjectImage	getObjectImage() Get an object image for this instance.
ObjectImage	getObjectImage(Object state) Get an object image for the given state.
Participant	getParticipant()
Object[]	getRecoverableStates() Get the states that should be recoverable.
RecoveryCoordinator	getRecoveryCoordinator()
Object	getState()
HeuristicMessage[]	getTags() Get the heuristic tags for this coordinator.
protected long	getTimeOut()
String	getURI() Gets the URI identifier for this coordinator.
protected void	incLocalSiblingCount() Called when a tx import is being done.
boolean	isCommitted() Test if the transaction was committed or not.
Boolean	isRecoverableWhileActive() Checks whether the instance is recoverable in the active state.
void	preEnter(FSMEnterEvent event) Called BEFORE the FSM enters the new state, so that the callee is sure that nobody has seen the new state yet.
int	prepare() Prepares the participant.
boolean	recover() Called by the transaction manager (TM) at recovery time, and this should reconstruct the internal state.
Boolean	replayCompletion(Participant participant) Asks for a repetition of completion.
protected void	restore(ObjectImage image) Help function for restoration.
HeuristicMessage[]	rollback() Rollback of the participant's work.
HeuristicMessage[]	rollbackHeuristically()
void	setCascadeList(Dictionary 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.
void	setRecoverableWhileActive() Sets this coordinator to be recoverable while active.
protected void	startThreads(long timeout) Start threads, propagator and timer logic.
protected void	terminate(boolean commit) Terminate the work, on behalf of Terminator.

Methods inherited from class java.lang.Object

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

Constructor Detail

CoordinatorImp

protected CoordinatorImp(String root,
                         boolean heuristic_commit,
                         boolean checkorphans)

Constructor for testing only.

CoordinatorImp

protected CoordinatorImp(String root,
                         RecoveryCoordinator coord,
                         boolean heuristic_commit,
                         long timeout,
                         boolean checkorphans,
                         boolean single_threaded_2pc)

Constructor.

Parameters:

root - The root tid.

coord - The RecoverCoordinator, null if root.

console - The console to log to, or null if none.

heuristic_commit - Whether to do commit on heuristic.

timeout - The timeout in milliseconds for indoubts. before a heuristic decision is made.

checkorphans - If true, orphan checks are made on prepare. For OTS, this is false.

single_threaded_2pc - If true then commit is done in the same thread as the one that started the tx.

CoordinatorImp

public CoordinatorImp(String root,
                      RecoveryCoordinator coord,
                      boolean heuristic_commit,
                      boolean checkorphans)

Constructor.

Parameters:

root - The root String for this one.

console - The console to log to, or null if none.

coord - The recovery coordinator for indoubt resolution.

heuristic_commit - If true, heuristic decision is commit.

checkorphans - If true, orphan checking is done at prepare.

CoordinatorImp

public CoordinatorImp()

No argument constructor as required by Recoverable interface.

Method Detail

isRecoverableWhileActive

public Boolean isRecoverableWhileActive()

Description copied from interface: CompositeCoordinator

Checks whether the instance is recoverable in the active state. Although active recoverability requires more logging overhead, some protocols may need this capability.

Specified by:

isRecoverableWhileActive in interface CompositeCoordinator

Returns:

Boolean True if the instance is recoverable in active state, or null if this information is not available (e.g., for imported instances).

getHeuristicMessages

public HeuristicMessage[] getHeuristicMessages(Object heuristicState)

Gets the heuristic messages for all participants that are in the given heuristic state

Parameters:

heuristicState - The heuristic state, or the terminated state.

Returns:

HeuristicMessage[] The heuristic messages of all participants in the given state, or an empty array if none.

isCommitted

public boolean isCommitted()

Test if the transaction was committed or not.

Returns:

boolean True iff committed.

getHeuristicMessages

public HeuristicMessage[] getHeuristicMessages()

Get the heuristic info for the message round.

Specified by:

getHeuristicMessages in interface Participant

Returns:

HeuristicMessages[] The heuristic messages, or an empty array if none.

getTags

public HeuristicMessage[] getTags()

Get the heuristic tags for this coordinator. This info is returned to remote client TMs by a Participant proxy.

Specified by:

getTags in interface CompositeCoordinator

Returns:

HeuristicMessage[] Any tags set by the application. These serve as a summary of the local work towards remote client TMs (that way, these do not have to see ALL local heuristic messages, but rather get a relevant summary). The participant proxy for a local coordinator returns these tags as its heuristic messages.

startThreads

protected void startThreads(long timeout)

Start threads, propagator and timer logic. Needed on construction AND by replay request events: timers have stopped by then!

Parameters:

timeout - The timeout for the thread wakeup interval.

console - The console, null if none.

getTimeOut

protected long getTimeOut()

getState

public Object getState()

Specified by:

getState in interface Stateful

Returns:

The object representing the state.

See Also:

Stateful

addFSMEnterListener

public void addFSMEnterListener(FSMEnterListener l,
                                Object state)

See Also:

FSMEnterEventSource.

addFSMPreEnterListener

public void addFSMPreEnterListener(FSMPreEnterListener l,
                                   Object state)

Specified by:

addFSMPreEnterListener in interface FSMPreEnterEventSource

getRecoveryCoordinator

public RecoveryCoordinator getRecoveryCoordinator()

Specified by:

getRecoveryCoordinator in interface CompositeCoordinator

Returns:

RecoveryCoordinator.

See Also:

CompositeCoordinator.

getParticipant

public Participant getParticipant()
                           throws UnsupportedOperationException

Throws:

UnsupportedOperationException

See Also:

CompositeCoordinator.

getCoordinatorId

public String getCoordinatorId()

Specified by:

getCoordinatorId in interface CompositeCoordinator

Returns:

String The coordinatorId. For imported transactions, this will be the id of the top-level or root transaction. For subtransactions, this will be an independent id.

See Also:

com.atomikos.icatch.CompositeCoordinator.

addParticipant

public RecoveryCoordinator addParticipant(Participant participant)
                                   throws SysException,
                                          IllegalStateException,
                                          RollbackException

Throws:

SysException

IllegalStateException

RollbackException

incLocalSiblingCount

protected void incLocalSiblingCount()

Called when a tx import is being done.

preEnter

public void preEnter(FSMEnterEvent event)
              throws IllegalStateException

Description copied from interface: FSMPreEnterListener

Called BEFORE the FSM enters the new state, so that the callee is sure that nobody has seen the new state yet.

Specified by:

preEnter in interface FSMPreEnterListener

Throws:

IllegalStateException - on failure. The callee can use this to prevent the state change from happening.

See Also:

FSMPreEnterListener.

getURI

public String getURI()

Description copied from interface: RecoveryCoordinator

Gets the URI identifier for this coordinator.

Specified by:

getURI in interface Participant

Specified by:

getURI in interface RecoveryCoordinator

Returns:

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

See Also:

Participant

recover

public boolean recover()
                throws SysException

Description copied from interface: Participant

Called by the transaction manager (TM) at recovery time, and this should reconstruct the internal state.

Specified by:

recover in interface Participant

Returns:

boolean False if the instance could not be recovered. It is up to the transaction manager to determine the severity of this case.

Throws:

SysException

See Also:

Participant

forget

public void forget()

Description copied from interface: Participant

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.

Specified by:

forget in interface Participant

See Also:

Participant.

setCascadeList

public void setCascadeList(Dictionary allParticipants)
                    throws SysException

Description copied from interface: Participant

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

Specified by:

setCascadeList in interface Participant

Parameters:

allParticipants - The information needed by the transaction monitor.

Throws:

SysException

See Also:

Participant.

setGlobalSiblingCount

public void setGlobalSiblingCount(int count)

Description copied from interface: Participant

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

Specified by:

setGlobalSiblingCount in interface Participant

Parameters:

count - The global count.

See Also:

Participant.

prepare

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

Description copied from interface: Participant

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

Specified by:

prepare in interface Participant

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

IllegalStateException

See Also:

Participant.

commit

public HeuristicMessage[] commit(boolean onePhase)
                          throws HeurRollbackException,
                                 HeurMixedException,
                                 HeurHazardException,
                                 IllegalStateException,
                                 RollbackException,
                                 SysException

Description copied from interface: Participant

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.

Specified by:

commit in interface Participant

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.

Returns:

HeuristicMessage[] An array of messages, null if none.

Throws:

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

IllegalStateException

See Also:

Participant.

rollback

public HeuristicMessage[] rollback()
                            throws HeurCommitException,
                                   HeurMixedException,
                                   SysException,
                                   HeurHazardException,
                                   IllegalStateException

Description copied from interface: Participant

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.

Specified by:

rollback in interface Participant

Returns:

HeuristicMessage[] An array of messages, null if none.

Throws:

HeurCommitException - If the participant committed.

HeurMixedException - If part of the work was rolled back.

SysException

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

IllegalStateException

See Also:

Participant.

rollbackHeuristically

public HeuristicMessage[] rollbackHeuristically()
                                         throws HeurCommitException,
                                                HeurMixedException,
                                                SysException,
                                                HeurHazardException,
                                                IllegalStateException

Throws:

HeurCommitException

HeurMixedException

SysException

HeurHazardException

IllegalStateException

commitHeuristically

public HeuristicMessage[] commitHeuristically()
                                       throws HeurMixedException,
                                              SysException,
                                              HeurRollbackException,
                                              HeurHazardException,
                                              IllegalStateException,
                                              RollbackException

Throws:

HeurMixedException

SysException

HeurRollbackException

HeurHazardException

IllegalStateException

RollbackException

replayCompletion

public Boolean replayCompletion(Participant participant)
                         throws IllegalStateException

Description copied from interface: RecoveryCoordinator

Asks for a repetition of completion.

Specified by:

replayCompletion in interface RecoveryCoordinator

Parameters:

participant - The indoubt participant asking for replay

Returns:

Boolean Null if decision not know to coordinator yet; True if commit is known, False if abort is known.

Throws:

IllegalStateException - If no prepare was done for the participant asking the replay.

See Also:

RecoveryCoordinator.

restore

protected void restore(ObjectImage image)

Help function for restoration.

getObjectImage

public ObjectImage getObjectImage()

Description copied from interface: Recoverable

Get an object image for this instance. Allows later reconstruction of the instance.

Specified by:

getObjectImage in interface Recoverable

See Also:

Recoverable

getObjectImage

public ObjectImage getObjectImage(Object state)

Description copied from interface: StateRecoverable

Get an object image for the given state.

Specified by:

getObjectImage in interface StateRecoverable

Parameters:

state - The state about to be reached. Because the instance is not yet IN the new state, this state is supplied as a parameter.

Returns:

ObjectImage The image, or null to override the recoverability preference. In other words, if null is returned that logging is not done for the given state, even if the state was returned as one of the recoverable states.

See Also:

StateRecoverable

getRecoverableStates

public Object[] getRecoverableStates()

Description copied from interface: StateRecoverable

Get the states that should be recoverable.

Specified by:

getRecoverableStates in interface StateRecoverable

Returns:

Object[] An array of states that are meant to be recoverable. For efficiency, this should also include a state where the logimage is forgettable!

See Also:

StateRecoverable

getFinalStates

public Object[] getFinalStates()

Description copied from interface: StateRecoverable

Needed by the Recovery system to determine when a logged state can be forgotten. If the instance reaches one of these states, then it will no longer be recoverable.

Specified by:

getFinalStates in interface StateRecoverable

Returns:

Object[] The list of final states.

See Also:

StateRecoverable

getId

public Object getId()

Description copied from interface: Identifiable

Get the id.

Specified by:

getId in interface Identifiable

Returns:

Object The id, should be the same as returned by the corresponding logimage.

See Also:

Recoverable

alarm

public void alarm(AlarmTimer timer)

Description copied from interface: AlarmTimerListener

Notify the instance of an alarm coming from a timer.

Specified by:

alarm in interface AlarmTimerListener

Parameters:

timer - The timer raising the alarm.

dispose

protected void dispose()

For cleaning up properly.

terminate

protected void terminate(boolean commit)
                  throws HeurRollbackException,
                         HeurMixedException,
                         SysException,
                         SecurityException,
                         HeurCommitException,
                         HeurHazardException,
                         RollbackException,
                         IllegalStateException

Terminate the work, on behalf of Terminator.

Parameters:

commit - True iff commit termination is asked.

Throws:

HeurRollbackException

HeurMixedException

SysException

SecurityException

HeurCommitException

HeurHazardException

RollbackException

IllegalStateException

setRecoverableWhileActive

public void setRecoverableWhileActive()
                               throws UnsupportedOperationException

Description copied from interface: CompositeCoordinator

Sets this coordinator to be recoverable while active. Ideally, this method is called before any participants are added (otherwise, some participants may have been added and not recovered due to an intermediate crash). This operation may not be unavailable for imported coordinators, but it should always work for locally created (sub)transactions. Calling this method is optional, and it defaults to false.
NOTE: active recoverability is inherited by any subtransactions that are created afterwards.

Specified by:

setRecoverableWhileActive in interface CompositeCoordinator

Throws:

UnsupportedOperationException