Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## 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, Console console, boolean checkorphans)` Constructor for testing only.
`` | `CoordinatorImp(String root, RecoveryCoordinator coord, Console console, boolean heuristic_commit, boolean checkorphans)` Constructor.
`protected` | `CoordinatorImp(String root, RecoveryCoordinator coord, Console console, 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)` Commit the participant's work.
`HeuristicMessage[]` | `commitHeuristically()`
`protected void` | `dispose()` For cleaning up properly.
`void` | `forget()` Indicate that a heuristic participant can forget about its work.
`String` | `getCoordinatorId()` Get the identifier for this coordinator.
`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()` Get the recovery coordinator instance for this one.
`Object` | `getState()`
`HeuristicMessage[]` | `getTags()` Get the heuristic tags for this coordinator.
`protected long` | `getTimeOut()`
`String` | `getURI()` Gets a unique URI for this participant.
`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()` Prepare the participant.
`boolean` | `recover()` Recover this instance.
`Boolean` | `replayCompletion(Participant participant)` Ask for a repetition of completion.
`protected void` | `restore(ObjectImage image)` Help function for restoration.
`HeuristicMessage[]` | `rollback()` Rollback 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, Console console)` 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,
                             Console console,
                             boolean checkorphans)

  Constructor for testing only.

### CoordinatorImp

    protected CoordinatorImp(String root,
                             RecoveryCoordinator coord,
                             Console console,
                             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,
                          Console console,
                          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 iff recoverable in active state. Null if this information is not available (for imported instances). By default, this is false.

### 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[] The tags set. 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,
                                Console console)

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

  Description copied from interface: `CompositeCoordinator`
  Get the recovery coordinator instance for this one.

  Specified by:
    `getRecoveryCoordinator` in interface `CompositeCoordinator`
  Returns:
    RecoveryCoordinator The recovery coordinator.
  See Also:
    `CompositeCoordinator.`

### getParticipant

    public Participant getParticipant()
                               throws UnsupportedOperationException

  Throws:
    `UnsupportedOperationException`
  See Also:
    `CompositeCoordinator.`

### getCoordinatorId

    public String getCoordinatorId()

  Description copied from interface: `CompositeCoordinator`
  Get the identifier for this coordinator.

  Specified by:
    `getCoordinatorId` in interface `CompositeCoordinator`
  Returns:
    String The coordinator id. 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: `Participant`
  Gets a unique URI for this participant. Local participants should merely return null.

  Specified by:
    `getURI` in interface `Participant`
  Specified by:
    `getURI` in interface `RecoveryCoordinator`
  Returns:
    String The URI for this participant, or null if not applicable.
  See Also:
    `Participant`

### recover

    public boolean recover()
                    throws SysException

  Description copied from interface: `Participant`
  Recover this instance. 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 iff the instance could not be recovered. It is up to the TM to determine the severity of this case.
  Throws:
    `SysException` - On failure.
  See Also:
    `Participant`

### forget

    public void forget()

  Description copied from interface: `Participant`
  Indicate 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 for
  Throws:
    `SysException` - For unexpected failures.
  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`
  Prepare 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 If this is READ_ONLY, then 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` - Unexpected errors.
    `IllegalStateException`
  See Also:
    `Participant.`

### commit

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

  Description copied from interface: `Participant`
  Commit 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:
    `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` - Unexpected failure.
    `HeurRollbackException`
    `HeurMixedException`
    `IllegalStateException`
  See Also:
    `Participant.`

### rollback

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

  Description copied from interface: `Participant`
  Rollback 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 it was rolled back.
    `SysException` - Unexpected failure.
    `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`
  Ask 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.
  NOTE: active recoverability is inherited by any subtransactions that are created afterwards.

  Specified by:
    `setRecoverableWhileActive` in interface `CompositeCoordinator`
  Throws:
    `UnsupportedOperationException`

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright © 2012. All Rights Reserved.