com.arjuna.mwlabs.wscf.model.twophase.arjunacore

Class CoordinatorServiceImple

java.lang.Object

com.arjuna.mwlabs.wscf.model.twophase.arjunacore.CoordinatorServiceImple

All Implemented Interfaces:

CoordinatorManager, UserCoordinator

public class CoordinatorServiceImple
extends Object
implements UserCoordinator, CoordinatorManager

The user portion of the coordinator API. An implementation of this interface presents each thread with the capability to create and manage coordinators. It is very similar to the OTS Current and JTA UserTransaction.

Since:

1.0.

Version:

$Id: CoordinatorServiceImple.java,v 1.8 2005/05/19 12:13:38 nmcl Exp $

Author:

Mark Little (mark.little@arjuna.com)

Constructor Summary

Constructors

Constructor and Description
CoordinatorServiceImple()

Method Summary

Modifier and Type	Method and Description
void	begin(String serviceType) Start a new activity.
void	begin(String serviceType, int timeout) Start a new activity.
void	cancel() Cancel the activity.
void	confirm() Confirm the activity.
CoordinatorControl	coordinatorControl()
ActivityImple	current()
ActivityHierarchy	currentActivity()
void	delistParticipant(Participant act) Remove the specified participant from the coordinator's list.
void	delistSynchronization(Synchronization act) Remove the specified synchronization from the coordinator's list.
void	enlistParticipant(Participant act) Enrol the specified participant with the coordinator associated with the current thread.
void	enlistSynchronization(Synchronization act) Enrol the specified synchronization with the coordinator associated with the current thread.
int	getTimeout() Get the timeout value currently associated with activities.
CoordinatorId	identifier()
void	participantReadOnly(String participantId) A participant is readonly.
void	participantRolledback(String participantId) The participant has rolled back.
void	resume(ActivityHierarchy tx) Given a token representing a context, associate it with the current thread of control.
void	setCancelOnly() Set the termination status for the current activity to cancel only.
void	setTimeout(int timeout) Set the timeout to be associated with all subsequently created activities.
Status	status()
ActivityHierarchy	suspend() Suspend the current activity from this thread and return the token representing the context, if any, or null otherwise.

Methods inherited from class java.lang.Object

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

Constructor Detail

CoordinatorServiceImple

public CoordinatorServiceImple()

Method Detail

begin

public void begin(String serviceType)
           throws WrongStateException,
                  SystemException

Start a new activity. If there is already an activity associated with the thread then it will be nested. An implementation specific timeout will be associated with the activity (which may be no timeout).

Specified by:

begin in interface UserCoordinator

Throws:

WrongStateException - Thrown if the any currently associated activity is in a state that does not allow a new activity to be enlisted.

SystemException - Thrown in any other situation.

begin

public void begin(String serviceType,
                  int timeout)
           throws WrongStateException,
                  InvalidTimeoutException,
                  SystemException

Start a new activity. If there is already an activity associated with the thread then it will be nested.

Specified by:

begin in interface UserCoordinator

Parameters:

timeout - timeout The timeout associated with the activity. If the activity has not been terminated by the time this period elapses, then it will automatically be terminated.

Throws:

WrongStateException - Thrown if the currently associated activity is in a state that does not allow a new activity to be enlisted as a child.

InvalidTimeoutException - Thrown if the specified timeout is invalid within the current working environment.

SystemException - Thrown in any other situation.

confirm

public void confirm()
             throws InvalidActivityException,
                    WrongStateException,
                    ProtocolViolationException,
                    NoCoordinatorException,
                    CoordinatorCancelledException,
                    HeuristicMixedException,
                    HeuristicHazardException,
                    NoPermissionException,
                    SystemException

Confirm the activity.

Specified by:

confirm in interface UserCoordinator

Throws:

InvalidActivityException - Thrown if the current activity is a parent activity with active children.

WrongStateException - Thrown if the current activity is not in a state that allows it to be completed in the status requested.

ProtocolViolationException - Thrown if the a violation of the activity service or HLS protocol occurs.

NoPermissionException - Thrown if the invoking thread does not have permission to terminate the transaction.

SystemException - Thrown if some other error occurred.

NoCoordinatorException

CoordinatorCancelledException

HeuristicMixedException

HeuristicHazardException

cancel

public void cancel()
            throws InvalidActivityException,
                   WrongStateException,
                   ProtocolViolationException,
                   NoCoordinatorException,
                   CoordinatorConfirmedException,
                   HeuristicMixedException,
                   HeuristicHazardException,
                   NoPermissionException,
                   SystemException

Cancel the activity.

Specified by:

cancel in interface UserCoordinator

Throws:

InvalidActivityException - Thrown if the current activity is a parent activity with active children.

WrongStateException - Thrown if the current activity is not in a state that allows it to be completed, or is incompatible with the completion status provided.

ProtocolViolationException - Thrown if the a violation of the activity service or HLS protocol occurs.

NoPermissionException - Thrown if the invoking thread does not have permission to terminate the transaction.

SystemException - Thrown if some other error occurred.

NoCoordinatorException

CoordinatorConfirmedException

HeuristicMixedException

HeuristicHazardException

See Also:

Outcome

setCancelOnly

public void setCancelOnly()
                   throws NoCoordinatorException,
                          WrongStateException,
                          SystemException

Set the termination status for the current activity to cancel only.

Specified by:

setCancelOnly in interface UserCoordinator

Throws:

WrongStateException - Thrown if the completion status is incompatible with the current state of the activity.

SystemException - Thrown if any other error occurs.

NoCoordinatorException

getTimeout

public int getTimeout()
               throws SystemException

Get the timeout value currently associated with activities.

Specified by:

getTimeout in interface UserCoordinator

Returns:

the timeout value in seconds, or 0 if no application specified timeout has been provided.

Throws:

SystemException - Thrown if any error occurs.

setTimeout

public void setTimeout(int timeout)
                throws InvalidTimeoutException,
                       SystemException

Set the timeout to be associated with all subsequently created activities. A default value of 0 is automatically associated with each thread and this means that no application specified timeout is set for activities.

Specified by:

setTimeout in interface UserCoordinator

Parameters:

timeout - timeout The timeout (in seconds) to associate with all subsequently created activities. This value must be 0 or greater.

Throws:

InvalidTimeoutException - Thrown if the timeout value provided is negative, too large, or if timeouts are simply not supported by the activity implementation.

SystemException - Thrown if any other error occurs.

status

public Status status()
              throws SystemException

Specified by:

status in interface UserCoordinator

Returns:

the status of the current activity. If there is no activity associated with the thread then NoActivity will be returned.

Throws:

SystemException - Thrown if any error occurs.

See Also:

Status

suspend

public ActivityHierarchy suspend()
                          throws SystemException

Suspend the current activity from this thread and return the token representing the context, if any, or null otherwise. Once called, the thread will have no activities associated with it.

Specified by:

suspend in interface UserCoordinator

Returns:

the token representing the current context, if any, or null otherwise.

Throws:

SystemException - Thrown if any error occurs.

resume

public void resume(ActivityHierarchy tx)
            throws InvalidActivityException,
                   SystemException

Given a token representing a context, associate it with the current thread of control. This will implicitly disassociate the thread from any activities that it may already be associated with. If the parameter is null then the thread is associated with no activity.

Specified by:

resume in interface UserCoordinator

Parameters:

ActivityHierarchy - tx The activity to associate with this thread. This may be null in which case the current thread becomes associated with no activity.

Throws:

InvalidActivityException - Thrown if the activity handle is invalid in this context.

SystemException - Thrown if any other error occurs.

enlistParticipant

public void enlistParticipant(Participant act)
                       throws WrongStateException,
                              DuplicateParticipantException,
                              InvalidParticipantException,
                              NoCoordinatorException,
                              SystemException

Enrol the specified participant with the coordinator associated with the current thread.

Specified by:

enlistParticipant in interface CoordinatorManager

Parameters:

Participant - act The participant.

Throws:

WrongStateException - Thrown if the coordinator is not in a state that allows participants to be enrolled.

DuplicateParticipantException - Thrown if the participant has already been enrolled and the coordination protocol does not support multiple entries.

InvalidParticipantException - Thrown if the participant is invalid.

SystemException - Thrown if any other error occurs.

NoCoordinatorException

delistParticipant

public void delistParticipant(Participant act)
                       throws InvalidParticipantException,
                              NoCoordinatorException,
                              WrongStateException,
                              SystemException

Remove the specified participant from the coordinator's list.

Specified by:

delistParticipant in interface CoordinatorManager

Parameters:

act - The participant to remove.

Throws:

InvalidParticipantException - Thrown if the participant is not known of by the coordinator.

WrongStateException - Thrown if the state of the coordinator does not allow the participant to be removed (e.g., in a two-phase protocol the coordinator is committing.)

SystemException - Thrown if any other error occurs.

NoCoordinatorException

enlistSynchronization

public void enlistSynchronization(Synchronization act)
                           throws WrongStateException,
                                  DuplicateSynchronizationException,
                                  InvalidSynchronizationException,
                                  NoCoordinatorException,
                                  SystemException

Enrol the specified synchronization with the coordinator associated with the current thread.

Specified by:

enlistSynchronization in interface CoordinatorManager

Parameters:

Synchronization - act The synchronization to remove.

Throws:

WrongStateException - Thrown if the coordinator is not in a state that allows participants to be enrolled.

DuplicateSynchronizationException - Thrown if the participant has already been enrolled and the coordination protocol does not support multiple entries.

InvalidSynchronizationException - Thrown if the participant is invalid.

SystemException - Thrown if any other error occurs.

NoCoordinatorException

delistSynchronization

public void delistSynchronization(Synchronization act)
                           throws InvalidSynchronizationException,
                                  NoCoordinatorException,
                                  WrongStateException,
                                  SystemException

Remove the specified synchronization from the coordinator's list.

Specified by:

delistSynchronization in interface CoordinatorManager

Parameters:

act - The synchronization to remove.

Throws:

InvalidSynchronizationException - Thrown if the participant is not known of by the coordinator.

WrongStateException - Thrown if the state of the coordinator does not allow the participant to be removed (e.g., in a two-phase protocol the coordinator is committing.)

SystemException - Thrown if any other error occurs.

NoCoordinatorException

participantRolledback

public void participantRolledback(String participantId)
                           throws NoActivityException,
                                  InvalidParticipantException,
                                  WrongStateException,
                                  SystemException

The participant has rolled back. Mark the transaction as rolled back.

Specified by:

participantRolledback in interface CoordinatorManager

Parameters:

Participant - act The participant.

Throws:

NoActivityException - Thrown if there is no activity associated with the current thread.

WrongStateException - Thrown if the coordinator is not in a state that allows participants to be removed.

InvalidParticipantException - Thrown if the participant is invalid.

SystemException - Thrown if any other error occurs.

participantReadOnly

public void participantReadOnly(String participantId)
                         throws NoActivityException,
                                InvalidParticipantException,
                                SystemException

A participant is readonly. Remove it from the list.

Specified by:

participantReadOnly in interface CoordinatorManager

Parameters:

Participant - act The participant.

Throws:

NoActivityException - Thrown if there is no activity associated with the current thread.

InvalidParticipantException - Thrown if the participant is invalid.

SystemException - Thrown if any other error occurs.

currentActivity

public ActivityHierarchy currentActivity()
                                  throws SystemException

Specified by:

currentActivity in interface UserCoordinator

Returns:

the token representing the current activity context hierarchy, or null if there is none associated with the invoking thread.

Throws:

SystemException - Thrown if any error occurs.

identifier

public CoordinatorId identifier()
                         throws NoActivityException,
                                SystemException

Specified by:

identifier in interface UserCoordinator

Returns:

the unique coordinator identifier.

Throws:

NoActivityException - Thrown if there is no activity associated with the invoking thread.

SystemException - Thrown if some other error occurred.

current

public final ActivityImple current()

coordinatorControl

public final CoordinatorControl coordinatorControl()