com.arjuna.mw.wscf.model.sagas.api

Interface UserCoordinator

All Known Subinterfaces:

CoordinatorManager

All Known Implementing Classes:

CoordinatorServiceImple

public interface UserCoordinator

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: UserCoordinator.java,v 1.3 2005/05/19 12:13:24 nmcl Exp $

Author:

Mark Little (mark.little@arjuna.com)

Method Summary

Methods

Modifier and Type	Method and Description
void	begin(String coordinationType) Start a new activity.
void	begin(String coordinationType, int timeout) Start a new activity.
void	cancel() Cancel the activity.
void	close() Confirm the current activity.
void	complete() Complete the activity.
ActivityHierarchy	currentActivity()
int	getTimeout() Get the timeout value currently associated with activities.
CoordinatorId	identifier()
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.

Method Detail

begin

void begin(String coordinationType)
           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).

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

void begin(String coordinationType,
         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. If the activity is still active when the specified timeout elapses, it will be terminated.

Parameters:

timeout - The timeout associated with the activity (in seconds). 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.

close

void close()
           throws InvalidActivityException,
                  WrongStateException,
                  ProtocolViolationException,
                  NoCoordinatorException,
                  CoordinatorCancelledException,
                  NoPermissionException,
                  SystemException

Confirm the current activity.

Throws:

InvalidActivityException - Thrown if the current activity is invalid in the execution environment.

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

cancel

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

Cancel the activity.

Throws:

InvalidActivityException - Thrown if the current activity is invalid in the execution environment.

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

See Also:

Outcome

complete

void complete()
              throws InvalidActivityException,
                     WrongStateException,
                     ProtocolViolationException,
                     NoCoordinatorException,
                     NoPermissionException,
                     SystemException

Complete the activity.

Throws:

InvalidActivityException - Thrown if the current activity is invalid in the execution environment.

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

See Also:

Outcome

setCancelOnly

void setCancelOnly()
                   throws NoCoordinatorException,
                          WrongStateException,
                          SystemException

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

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

int getTimeout()
               throws SystemException

Get the timeout value currently associated with activities.

Returns:

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

Throws:

SystemException - Thrown if any error occurs.

setTimeout

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.

Parameters:

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

Status status()
              throws SystemException

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

identifier

CoordinatorId identifier()
                         throws NoActivityException,
                                SystemException

Returns:

the unique coordinator id for the current coordinator. This may or may not be the same as the activity id.

Throws:

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

SystemException - Thrown if some other error occurred.

suspend

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.

Returns:

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

Throws:

SystemException - Thrown if any error occurs.

resume

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.

Parameters:

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.

currentActivity

ActivityHierarchy currentActivity()
                                  throws SystemException

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.