com.arjuna.mwlabs.wsas

Class UserActivityImple

java.lang.Object

com.arjuna.mwlabs.wsas.UserActivityImple

All Implemented Interfaces:

UserActivity

public class UserActivityImple
extends Object
implements UserActivity

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

Since:

1.0.

Version:

$Id: UserActivityImple.java,v 1.4 2005/03/10 15:37:00 nmcl Exp $

Author:

Mark Little (mark.little@arjuna.com)

Constructor Summary

Constructors

Constructor and Description
UserActivityImple()

Method Summary

Modifier and Type	Method and Description
GlobalId	activityId()
String	activityName() What is the name of the current activity? Use only for debugging purposes!
ActivityImple	current()
ActivityHierarchy	currentActivity()
Outcome	end() Complete the activity with the completion status provided.
Outcome	end(CompletionStatus cs) Complete the activity with the completion status provided.
CompletionStatus	getCompletionStatus() Get the completion status currently associated with the activity.
int	getTimeout() Get the timeout value currently associated with activities.
void	resume(ActivityHierarchy tx) Given a token representing a context, associate it with the current thread of control.
String	serviceType()
void	setCompletionStatus(CompletionStatus endStatus) Set the termination status for the current activity, if any.
void	setTimeout(int timeout) Set the timeout to be associated with all subsequently created activities.
void	start(String serviceType) Start a new activity.
void	start(String serviceType, int timeout) Start a new activity.
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

UserActivityImple

public UserActivityImple()

Method Detail

start

public void start(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:

start in interface UserActivity

Parameters:

serviceType - specifies the type of coordinator which will be instantiated to manage the activity.

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.

start

public void start(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:

start in interface UserActivity

Parameters:

serviceType - specifies the type of coordinator which will be instantiated to manage the activity.

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.

end

public Outcome end()
            throws InvalidActivityException,
                   WrongStateException,
                   ProtocolViolationException,
                   SystemException,
                   NoActivityException,
                   SystemException,
                   NoPermissionException,
                   ActiveChildException

Complete the activity with the completion status provided.

Specified by:

end in interface UserActivity

Returns:

the result of completing the activity. Null is valid and must be interpreted within the context of any HLS that may exist.

Throws:

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

ActiveChildException - Thrown if the current activity is a

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.

NoActivityException - Thrown if there is no activity associated with the invoking thread or none with the given type of coordinator.

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

SystemException - Thrown if some other error occurred.

See Also:

Outcome

end

public Outcome end(CompletionStatus cs)
            throws InvalidActivityException,
                   WrongStateException,
                   ProtocolViolationException,
                   SystemException,
                   NoActivityException,
                   NoPermissionException,
                   ActiveChildException

Complete the activity with the completion status provided.

Specified by:

end in interface UserActivity

Parameters:

cs - The CompletionStatus to use.

Returns:

the result of completing the activity. Null is valid and must be interpreted within the context of any HLS that may exist.

Throws:

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

ActiveChildException - Thrown if the current activity is a

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.

NoActivityException - Thrown if there is no activity associated with the invoking thread or none with the given type of coordinator.

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

SystemException - Thrown if some other error occurred.

See Also:

com.arjuna.mw.wsas.Outcome

setCompletionStatus

public void setCompletionStatus(CompletionStatus endStatus)
                         throws NoActivityException,
                                WrongStateException,
                                SystemException

Set the termination status for the current activity, if any.

Specified by:

setCompletionStatus in interface UserActivity

Parameters:

endStatus - The state in which the activity should attempt to terminate. This may be one of the default values provided by WSAS or may be extended in an implementation specific manner by an HLS.

Throws:

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

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

SystemException - Thrown if any other error occurs.

getCompletionStatus

public CompletionStatus getCompletionStatus()
                                     throws NoActivityException,
                                            SystemException

Get the completion status currently associated with the activity.

Specified by:

getCompletionStatus in interface UserActivity

Returns:

the termination status for the current activity, if any.

Throws:

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

SystemException - Thrown if any other error occurs.

getTimeout

public int getTimeout()
               throws SystemException

Get the timeout value currently associated with activities.

Specified by:

getTimeout in interface UserActivity

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 UserActivity

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

public Status status()
              throws SystemException

Specified by:

status in interface UserActivity

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

activityName

public String activityName()
                    throws NoActivityException,
                           SystemException

What is the name of the current activity? Use only for debugging purposes!

Specified by:

activityName in interface UserActivity

Returns:

the name of the activity.

Throws:

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

SystemException - Thrown if any other error occurs.

activityId

public GlobalId activityId()
                    throws NoActivityException,
                           SystemException

Specified by:

activityId in interface UserActivity

Returns:

the unique activity id.

Throws:

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

SystemException - Thrown if any other error occurs.

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 UserActivity

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 UserActivity

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

public ActivityHierarchy currentActivity()
                                  throws SystemException

Specified by:

currentActivity in interface UserActivity

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.

serviceType

public String serviceType()
                   throws NoActivityException,
                          SystemException

Specified by:

serviceType in interface UserActivity

Returns:

the service type supplied when the current activity was started.

Throws:

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

SystemException - Thrown if any error occurs.

current

public final ActivityImple current()