IBM WebSphere Application ServerTM
Release 8

com.ibm.websphere.ActivitySession
Interface UserActivitySession


public interface UserActivitySession

The UserActivitySession interface is used to begin and end ActivitySessions and to query various attributes of the ActivitySession associated with the calling thread.

An ActivitySession is a unit of work scope that can be used to coordinate multiple one-phase commit (1PC) resources to complete with a common outcome. In addition to providing a means for the coordination of 1PC resources an ActivitySession can also be used to provide a user-signon (e.g. HttpSession) scoped activation policy for EJBs.

An ActivitySession is used in much the same way as a JTA transaction. Application components may use the UserActivitySession interface to provide bean-managed demaracation of ActivitySession contexts. EJB components may alternatively be deployed to use container-managed ActivitySessions, in which case the EJB container manages the demarcation of ActivitySession contexts.

This interface defines the set of ActivitySession operations available to an application component that has been configured to use bean-managed ActivitySessions. An implementation of this interface is obtained via a JNDI lookup of the URI "java:comp/websphere/UserActivitySession".


Field Summary
static int EndModeCheckPoint
          Directs all the resources enlisted with the ActivitySession to checkpoint.
static int EndModeReset
          Directs all the resources enlisted with the ActivitySession to reset.
static int StatusNoSession
          There is no active ActivitySession associated with the calling thread
static int StatusSessionActive
          There is an active ActivitySession associated with the calling thread
static int StatusSessionCompleted
          The ActivitySession associated with the calling thread has completed
static int StatusSessionCompleting
          The ActivitySession associated with the calling thread is in the process of ending
static int StatusUnknown
          The ActivitySession service is unable to determine the status of the ActivitySession associated with the calling thread.
 
Method Summary
 void beginSession()
          Create a new ActivitySession and associate it with the current thread.
 void checkpointSession()
          Checkpoints all the resources enisted in the current ActivitySession but allows further work within the ActivitySession.
 void endSession(int EndMode)
          Completes the ActivitySession associated with the current thread and checkpoints or resets all of the resources enlisted with it.
 java.lang.String getSessionName()
          Obtain the name of the ActivitySession associated with the thread.
 int getSessionTimeout()
          Returns the default timeout value.
 int getStatus()
          Obtain the status of the ActivitySession associated with the current thread.
 void resetSession()
          Resets all the resources enlisted in the current ActivitySession but allows further work within the ActivitySession.
 void setResetOnly()
          Marks the ActivitySession associated with the current thread such that the only possible outcome is reset.
 void setSessionTimeout(int timeout)
          Sets the default timeout, in seconds, after which any subsequently started ActivitySessions may be automatically completed by the ActivitySession service.
 

Field Detail

EndModeCheckPoint

static final int EndModeCheckPoint
Directs all the resources enlisted with the ActivitySession to checkpoint. ActivitySession resources are one-phase resources, such as JDBC connections, executing in a local transaction that is scoped to the ActivitySession. Checkpointing the ActivitySession causes the enlisted resources' local transaction to be directed to commit.

See Also:
Constant Field Values

EndModeReset

static final int EndModeReset
Directs all the resources enlisted with the ActivitySession to reset. ActivitySession resources are one-phase resources, such as JDBC connections, executing in a local transaction that is scoped to the ActivitySession. Resetting the ActivitySession causes the enlisted resources' local transaction to be directed to rollback.

See Also:
Constant Field Values

StatusSessionActive

static final int StatusSessionActive
There is an active ActivitySession associated with the calling thread

See Also:
Constant Field Values

StatusSessionCompleting

static final int StatusSessionCompleting
The ActivitySession associated with the calling thread is in the process of ending

See Also:
Constant Field Values

StatusSessionCompleted

static final int StatusSessionCompleted
The ActivitySession associated with the calling thread has completed

See Also:
Constant Field Values

StatusNoSession

static final int StatusNoSession
There is no active ActivitySession associated with the calling thread

See Also:
Constant Field Values

StatusUnknown

static final int StatusUnknown
The ActivitySession service is unable to determine the status of the ActivitySession associated with the calling thread. This is a transient condition.

See Also:
Constant Field Values
Method Detail

beginSession

void beginSession()
                  throws ActivitySessionAlreadyActiveException,
                         TransactionPendingException,
                         NotSupportedException,
                         SystemException
Create a new ActivitySession and associate it with the current thread.

Throws:
ActivitySessionAlreadyActiveException - Thrown if the thread is already associated with a session.
TransactionPendingException - Thrown if the thread is associated with a transaction. ActivitySessions may not be nested within transactions.
NotSupportedException - Thrown if the access to the UserActivitySession interface is not allowed, for example if the caller is executing under an ActivitySession container policy of ActivitySessionNotSupported
SystemException - Thrown if the ActivitySession service encounters an unexpected error condition

endSession

void endSession(int EndMode)
                throws ActivitySessionPendingException,
                       ContextPendingException,
                       NoActivitySessionException,
                       NotOriginatorException,
                       MixedOutcomeException,
                       ActivitySessionResetException,
                       NotSupportedException,
                       SystemException
Completes the ActivitySession associated with the current thread and checkpoints or resets all of the resources enlisted with it. When this method completes the thread becomes associated with no ActivitySession.

If there is a contained transaction within the ActivitySession context and the end more is EndModeCheckpoint, then a ContextPendingException is raised and neither the transaction context nor the ActivitySession context are affected by the operation. The caller must either complete the transaction first or end the ActivitySession with an end mode of EndModeReset. If there are contained transactions within the ActivitySession context and the end mode is EndModeReset, then the contained transactions are marked rollback_only.

Parameters:
EndMode - indicates the end mode with which enlisted resources should be directed to complete. The EndMode value must be EndModeCheckpoint or EndModeReset
Throws:
ActivitySessionPendingException - Thrown to indicate that there is outstanding asynchronous work associated with the ActivitySession. The ActivitySession remains active.
ContextPendingException - Thrown if there is a contained transaction that has not been completed and the EndMode is EndModeCheckPoint. The ActivitySession and transaction contexts remain unchanged.
NoActivitySessionException - Thrown to indicate that no ActivitySession is associated with the current thread.
NotOriginatorException - Thrown to indicate that the calling thread does not belong in the originating execution environment and that this operation is therefore disallowed.
MixedOutcomeException - Thrown if the ActivitySessionResources enlisted in the ActivitySesison were not all completed in the same direction. An array of NotProcessedExceptions indicates the resources that were Reset.
ActivitySessionResetException - Thrown if a request to checkpoint resulted in all the ActivitySessionResources being reset.
NotSupportedException - Thrown if the access to the UserActivitySession interface is not allowed, for example if the caller is executing under an ActivitySession container policy of ActivitySessionNotSupported
SystemException - Thrown if the ActivitySession service encounters an unexpected error condition
See Also:
EndModeCheckPoint, EndModeReset

resetSession

void resetSession()
                  throws ActivitySessionPendingException,
                         NoActivitySessionException,
                         NotOriginatorException,
                         NotSupportedException,
                         SystemException
Resets all the resources enlisted in the current ActivitySession but allows further work within the ActivitySession. Resetting the ActivitySession causes the enlisted resources' local transaction to be directed to rollback. Any further work involving a resource occurs in a new local transaction scoped to the ActivitySession.

When this method completes, the thread is associated with the same ActivitySession as it was prior to this method being called. The enlisted resources remain associated with the ActivitySession although they may not participate further in the ActivitySession.

Throws:
ActivitySessionPendingException - Thrown to indicate that there is outstanding asynchronous work associated with the ActivitySession. No enlisted resources are reset
NoActivitySessionException - Thrown to indicate that no ActivitySession is associated with the current thread.
NotOriginatorException - Thrown to indicate that the ActivitySession associated with the calling thread did not originate in the current execution environment and that this operation is therefore disallowed.
NotSupportedException - Thrown if the access to the UserActivitySession interface is not allowed, for example if the caller is executing under an ActivitySession container policy of ActivitySessionNotSupported
SystemException - Thrown if the ActivitySession service encounters an unexpected error condition

checkpointSession

void checkpointSession()
                       throws ActivitySessionPendingException,
                              NoActivitySessionException,
                              NotOriginatorException,
                              MixedOutcomeException,
                              ActivitySessionResetException,
                              NotSupportedException,
                              SystemException
Checkpoints all the resources enisted in the current ActivitySession but allows further work within the ActivitySession. Checkpointing the ActivitySession causes the enlisted resources' local transaction to be directed to commit. Any further work involving a resource occurs under a new local transaction scoped to the ActivitySession.

When this method completes, the thread is associated with the same ActivitySession as it was prior to this method being called. The enlisted resources remain associated with the ActivitySession although they may not participate further in the ActivitySession.

Throws:
ActivitySessionPendingException - Thrown to indicate that there is outstanding asynchronous work associated with the ActivitySession. No enlisted resources are checkpointed.
NoActivitySessionException - Thrown to indicate that no ActivitySession is associated with the current thread.
NotOriginatorException - Thrown to indicate that the ActivitySession associated with the calling thread did not originate in the current execution environment and that this operation is therefore disallowed.
MixedOutcomeException - Thrown if the resources enlisted in the ActivitySession were not all completed in the same direction. The nested NotProcessedException indicates the resources that were reset.
ActivitySessionResetException - Thrown if a request to checkpoint resulted in all the enlisted resources being reset.
NotSupportedException - Thrown if the access to the UserActivitySession interface is not allowed, for example if the caller is executing under an ActivitySession container policy of ActivitySessionNotSupported
SystemException - Thrown if the ActivitySession service encounters an unexpected error condition

getStatus

int getStatus()
              throws SystemException
Obtain the status of the ActivitySession associated with the current thread.

Returns:
The ActivitySession status. If no ActivitySession is associated with the current thread, this method returns the status StatusNoSession
Throws:
SystemException - Thrown if the ActivitySession service encounters an unexpected error condition
See Also:
StatusNoSession, StatusSessionActive, StatusSessionCompleted, StatusSessionCompleting, StatusUnknown

getSessionName

java.lang.String getSessionName()
                                throws SystemException
Obtain the name of the ActivitySession associated with the thread. Typically this is a human-readable form of a unique identity value - e.g. the string-form of a UUID - that distinctly identifies this ActivitySession.

Returns:
The ActivitySession name. If no ActivitySession is associated with the current thread, this method returns an empty string.
Throws:
SystemException - Thrown if the ActivitySession service encounters an unexpected error condition

setSessionTimeout

void setSessionTimeout(int timeout)
                       throws TimeoutOutOfRangeException,
                              SystemException
Sets the default timeout, in seconds, after which any subsequently started ActivitySessions may be automatically completed by the ActivitySession service.

The timeout is a useful mechanism for protecting against clients that fail to end an ActivitySession in a timely fashion.

Parameters:
timeout - the default time, in seconds, after which an ActivitySession may be automatically reset by the ActivitySession service.
  • A value of -1 indicates no timeout.
  • A value of 0 indicates that a system-managed value or implementation-specific default should be used.
Throws:
TimeoutRangeException - Thrown if timeout is less than -1 or if it is greater than 1000000000 (1 billion).
SystemException - Thrown if the ActivitySession service encounters an unexpected error condition.
TimeoutOutOfRangeException

getSessionTimeout

int getSessionTimeout()
                      throws SystemException
Returns the default timeout value.

Returns:
The default timeout value in seconds.
Throws:
SystemException - Thrown if the ActivitySession service encounters an unexpected error condition.

setResetOnly

void setResetOnly()
                  throws NoActivitySessionException,
                         SystemException
Marks the ActivitySession associated with the current thread such that the only possible outcome is reset.

Throws:
NoActivitySessionException - Thrown to indicate that no ActivitySession is associated with the current thread.
SystemException - Thrown if the ActivitySession service encounters an unexpected error condition

IBM WebSphere Application ServerTM
Release 8