com.atomikos.icatch.imp
Class CoordinatorImp

java.lang.Object
  extended by 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

All things related to 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()
           
 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()
          Tests 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()
Tests 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()

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


Copyright © 2012. All Rights Reserved.