com.ibm.ws.javax.activity
Interface UserActivity

All Known Subinterfaces:
ActivityManager, WebSphereUserActivity
public interface UserActivity

The UserActivity interface defines the methods offered to a high-level service (HLS) constructed on top of the Activity service framework. These methods control the demarcation scope of an Activity associated with the calling thread of execution.
The specific behaviour of an individual HLS is encapsulated by a ServiceManager. An instance of the UserActivity interface has a ServiceManager registered with it prior to any Activities being begun by that instance.
Each Activity started by a UserActivity instance is an Activity instance of the HLS represented by the registered ServiceManager. Methods of the UserActivity interface that operate on the active Activity context are operating on the HLS Activity instance most recently associated with the calling thread.

Method Summary
 void begin(int timeout)
          Create a new Activity and associate it with the current thread.
 Outcome broadcast(java.lang.String signalSetName)
          Causes the SignalSet specified by signalSetName to start producing signals for all registered Actions.
 Outcome complete()
          Causes the active Activity context to be completed with its current CompletionStatus.
 Outcome completeWithStatus(int completionStatus)
          Causes the active Activity context to complete with the specified CompletionStatus.
 void forget(GlobalId globalId)
          Forget the specified GlobalId.
 int getCompletionStatus()
          Returns the current value of the CompletionStatus of the active Activity.
 ActivityCoordinator getCoordinator()
          Returns the ActivityCoordinator of the active Activity, or null if there is no Activity associated with the calling thread.
 GlobalId getGlobalId()
          Returns the GlobalId of the active Activity.
 java.lang.String getName()
          Returns a printable string describing the active Activity.
 ActivityCoordinator getParentCoordinator()
          Returns the ActivityCoordinator of the parent of the active Activity, or null if the active Activity is a top-level Activity.
 PropertyGroup getPropertyGroup(java.lang.String name)
          Returns the instance of the type of PropertyGroup, identified by name, scoped to the active Activity.
 ServiceManager getService()
          Returns the registered ServiceManager for this UserActivity instance.
 int getStatus()
          Returns the current value of the Status of the active Activity.
 int getTimeout()
          Returns the default timeout value.
 GlobalId[] recover()
          Driven by a HLS, after a failure, to retrieve a list of GlobalIds that the Activity service itself has logged information about.
 ActivityCoordinator recreate(GlobalId activity, GlobalId parent, boolean resume)
          Recreates an Activity after a failure.
 void registerService(ServiceManager service)
          Registers a ServiceManager for the type of high-level service (HLS) whose activities are to be demarcated through the target UserActivity instance.
 void setCompletionStatus(int completionStatus)
          Sets the CompletionStatus of the active Activity.
 void setTimeout(int timeout)
          Sets the default timeout, in seconds, after which an Activity may be automatically completed by the Activity service.
 

Method Detail

begin

public void begin(int timeout)
           throws InvalidStateException,
                  ServiceNotRegisteredException,
                  TimeoutRangeException,
                  SystemException
Create a new Activity and associate it with the current thread.

Parameters:
timeout - the period (in seconds) within which the Activity must be completed. If it is not completed within this period then it is subject to being completed by the Activity service with the CompletionStatusFail status. timeout can have the following possible values:
any positive value
the Activity must complete within this number of seconds.
-1
the Activity will never be completed automatically by the Activity Service implementation (i.e., it will never be considered to have timed out).
0
the last value specified using setTimeout method is used. If no prior call to setTimeout has occurred for this thread, or the value returned is 0, then it is implementation dependent as to the timeout value associated with this Activity.

Any other value results in the TimeoutRangeException being thrown.

Throws:
InvalidStateException - Thrown if the parent Activity has been marked as CompletionStatusFailOnly.
TimeoutRangeException - Thrown if timeout is less than -1 or if it is outside an administratively configured range in the deployed system.
ServiceNotRegisteredException - Thrown if no ServiceManager has been registered.
SystemException - Thrown if the Activity service encounters an unexpected error condition.

complete

public Outcome complete()
                 throws NoActivityException,
                        ActivityPendingException,
                        ContextPendingException,
                        ServiceNotRegisteredException,
                        NotOriginatorException,
                        ActivityNotProcessedException,
                        SystemException
Causes the active Activity context to be completed with its current CompletionStatus. If a CompletionSignalSet is used by the registered ServiceManager, then it will be driven by the Activity service to obtain completion signals to distribute to any registered Actions.
If the Activity is nested within a parent, then the parent Activity becomes associated with the thread on completion of this operation.
If there are any child active or suspended Activities or transactions and the CompletionStatus is CompletionStatusFail or CompletionStatusFailOnly then those child Activites will have their CompletionStatus set to CompletionStatusFailOnly and any child transaction will be called to setRollbackOnly.

Returns:
The Outcome returned is both set by and given meaning by the SignalSet used for completion. In the absence of a CompletionSignalSet a null Outcome object reference is returned.
Throws:
NoActivityException - Thrown if there is no Activity associated with the calling thread of execution.
ActivityPendingException - Thrown if the thread from which the completion is initiated is not the only thread associated with the target Activity. The application response should be to try again later when any asynchronous work on other threads has been suspended.
ContextPendingException - Thrown if the CompletionStatus is CompletionStatusSuccess and the target Activity encompasses active or suspended Activities or transactions. The application response should be to complete the encompassed Activities and transactions and then complete the target Activity or to force the target Activity to end by setting the CompletionStatus to CompletionStatusFail and then ending it.
NotOriginatorException - Thrown if an attempt is made by an application to end an Activity in a different execution environment from that in which the Activity was begun.
ActivityNotProcessedException - Thrown if the signals required to complete this operation could not be produced. The Activity's final Status is StatusError.
ServiceNotRegisteredException - Thrown if no ServiceManager has been registered.
SystemException - Thrown if the Activity service encounters an unexpected error condition.

completeWithStatus

public Outcome completeWithStatus(int completionStatus)
                           throws NoActivityException,
                                  ActivityPendingException,
                                  ContextPendingException,
                                  ServiceNotRegisteredException,
                                  NotOriginatorException,
                                  InvalidStateException,
                                  ActivityNotProcessedException,
                                  SystemException
Causes the active Activity context to complete with the specified CompletionStatus. If a CompletionSignalSet is used by the registered ServiceManager, then it will be driven by the Activity service to obtain completion signals to distribute to any registered Actions.
If the Activity is nested within a parent, then the parent Activity becomes associated with the thread on completion of this operation.
If there are any child active or suspended Activities or transactions and the CompletionStatus is CompletionStatusFail or CompletionStatusFailOnly then those child Activites will have their CompletionStatuses set to CompletionStatusFailOnly and any child transaction will be called to setRollbackOnly.

Parameters:
completionStatus - the CompletionStatus with which the active Activity should end.
Returns:
The Outcome returned is both set by and given meaning by the SignalSet used for completion. In the absence of a CompletionSignalSet a null Outcome object reference is returned.
Throws:
NoActivityException - Thrown if there is no Activity associated with the calling thread of execution.
ActivityPendingException - Thrown if the thread from which the completion is initiated is not the only thread associated with the target Activity. The application response should be to try again later when any asynchronous work on other threads has been suspended.
ContextPendingException - Thrown if the CompletionStatus is CompletionStatusSuccess and the target Activity encompasses active or suspended Activities or transactions. The application response should be to complete the encompassed Activities and transactions and then complete the target Activity or to force the target Activity to end by setting the CompletionStatus to CompletionStatusFail and then ending it.
NotOriginatorException - Thrown if an attempt is made by an application to end an Activity in a different execution environment from that in which the Activity was begun.
InvalidStateException - Thrown if the target Activity cannot be completed with the requested CompletionStatus, for example because the CompletionStatus may not be changed from CompletionStatusFailOnly to any other value, or if a null or invalid value is specified by completionStatus.
ActivityNotProcessedException - Thrown if the signals required to complete this operation could not be produced. The Activity's final Status is StatusError.
ServiceNotRegisteredException - Thrown if no ServiceManager has been registered.
SystemException - Thrown if the Activity service encounters an unexpected error condition.

setCompletionStatus

public void setCompletionStatus(int completionStatus)
                         throws NoActivityException,
                                InvalidStateException,
                                ServiceNotRegisteredException,
                                SystemException
Sets the CompletionStatus of the active Activity. This method may be called multiple times before the Activity is completed, and the CompletionStatus may be changed between CompletionStatusSuccess and CompletionStatusFail to indicate a point in time value. Once the CompletionStatus has been set to CompletionStatusFailOnly, it may not be changed again.

Parameters:
completionStatus - the CompletionStatus value to set.
Throws:
NoActivityException - Thrown if there is no Activity associated with the calling thread of execution.
InvalidStateException - Thrown if an attempt is made to update a CompletionStatus of CompletionStatusFailOnly or if a null or invalid value is specified by completionStatus.
ServiceNotRegisteredException - Thrown if no ServiceManager has been registered.
SystemException - Thrown if the Activity service encounters an unexpected error condition.

getCompletionStatus

public int getCompletionStatus()
                        throws ServiceNotRegisteredException,
                               NoActivityException,
                               SystemException
Returns the current value of the CompletionStatus of the active Activity.

Returns:
The CompletionStatus of the active Activity.
Throws:
NoActivityException - Thrown if there is no Activity associated with the calling thread of execution.
ServiceNotRegisteredException - Thrown if no ServiceManager has been registered.
SystemException - Thrown if the Activity service encounters an unexpected error condition.

getStatus

public int getStatus()
              throws ServiceNotRegisteredException,
                     SystemException
Returns the current value of the Status of the active Activity.

Returns:
The Status of the active Activity.
Throws:
ServiceNotRegisteredException - Thrown if no ServiceManager has been registered.
SystemException - Thrown if the Activity service encounters an unexpected error condition.

getName

public java.lang.String getName()
                         throws ServiceNotRegisteredException,
                                SystemException
Returns a printable string describing the active Activity.

Returns:
A printable string describing the active Activity. If no Activity is associated with the calling thread then null is returned.
Throws:
ServiceNotRegisteredException - Thrown if no ServiceManager has been registered.
SystemException - Thrown if the Activity service encounters an unexpected error condition.

setTimeout

public void setTimeout(int timeout)
                throws ServiceNotRegisteredException,
                       TimeoutRangeException,
                       SystemException
Sets the default timeout, in seconds, after which an Activity may be automatically completed by the Activity service. This default is used for an Activity that is begun with a timeout parameter value of 0. A value of -1 indicates no timeout. A value of 0 for the default timeout indicates that a system-managed value or implementation-specific default should be used.
The timeout is a useful mechanism for protecting against clients that fail to end an Activity in a timely fashion.

Parameters:
timeout - the default timeout period (in seconds) used by any future Activities begun with a timeout value of zero.
Throws:
TimeoutRangeException - Thrown if timeout is less than -1 or if it is outside an administratively configured range in the deployed system.
ServiceNotRegisteredException - Thrown if no ServiceManager has been registered.
SystemException - Thrown if the Activity service encounters an unexpected error condition.

getTimeout

public int getTimeout()
               throws ServiceNotRegisteredException,
                      SystemException
Returns the default timeout value.

Returns:
The default timeout value, in seconds.
Throws:
ServiceNotRegisteredException - Thrown if no ServiceManager has been registered.
SystemException - Thrown if the Activity service encounters an unexpected error condition.

getGlobalId

public GlobalId getGlobalId()
                     throws ServiceNotRegisteredException,
                            SystemException
Returns the GlobalId of the active Activity.

Returns:
The GlobalId of the active Activity, or null if there is no Activity associated with the thread.
Throws:
ServiceNotRegisteredException - Thrown if no ServiceManager has been registered.
SystemException - Thrown if the Activity service encounters an unexpected error condition.

broadcast

public Outcome broadcast(java.lang.String signalSetName)
                  throws NoActivityException,
                         SignalSetUnknownException,
                         ServiceNotRegisteredException,
                         com.ibm.ws.javax.activity.InvalidActivityException,
                         ActivityNotProcessedException,
                         SystemException
Causes the SignalSet specified by signalSetName to start producing signals for all registered Actions. This method is used to distribute Signals to Actions at times other than during completion. The implementation of the Activity service must ensure that pre-defined SignalSets, such as Synchronization, are not used.

Parameters:
signalSetName - the name of the SignalSet that is to produce the signals.
Returns:
The Outcome returned is both set by and given meaning by the SignalSet. A null Outcome object reference may be returned if the SignalSet does not produce an Outcome.
Throws:
NoActivityException - Thrown if there is no Activity associated with the calling thread of execution.
SignalSetUnknownException - Thrown if the named SignalSet is not recognized.
InvalidActivityException - Thrown if an attempt is made to use the Synchronization or ChildLifetime SignalSets, or if the Activity is in the process of completion.
ActivityNotProcessedException - Thrown if the signals required to complete this operation could not be produced.
ServiceNotRegisteredException - Thrown if no ServiceManager has been registered.
SystemException - Thrown if the Activity service encounters an unexpected error condition.

getCoordinator

public ActivityCoordinator getCoordinator()
                                   throws ServiceNotRegisteredException,
                                          NoImplementException,
                                          SystemException
Returns the ActivityCoordinator of the active Activity, or null if there is no Activity associated with the calling thread. In some execution environments, such as a J2EE client, this method need not be implemented and calling it may result in a NoImplementationException.

Returns:
The ActivityCoordinator of the active Activity. If there is no Activity associated with the calling thread then a null object reference is returned.
Throws:
NoImplementException - Thrown if the Activity service does not provide an implementation of this method in the calling environment, for example if a J2EE client calls this method.
ServiceNotRegisteredException - Thrown if no ServiceManager has been registered.
SystemException - Thrown if the Activity service encounters an unexpected error condition.

getParentCoordinator

public ActivityCoordinator getParentCoordinator()
                                         throws ServiceNotRegisteredException,
                                                NoImplementException,
                                                SystemException
Returns the ActivityCoordinator of the parent of the active Activity, or null if the active Activity is a top-level Activity. In some execution environments, such as a J2EE client, this method need not be implemented and calling it may result in a NoImplementationException.

Returns:
The ActivityCoordinator of the parent of the active Activity. If the active Activity is a top-level Activity then a null object reference is returned.
Throws:
NoImplementException - Thrown if the Activity service does not provide an implementation of this method in the calling environment, for example if a J2EE client calls this method.
ServiceNotRegisteredException - Thrown if no ServiceManager has been registered.
SystemException - Thrown if the Activity service encounters an unexpected error condition.

getPropertyGroup

public PropertyGroup getPropertyGroup(java.lang.String name)
                               throws PropertyGroupUnknownException,
                                      ServiceNotRegisteredException,
                                      NoActivityException,
                                      SystemException
Returns the instance of the type of PropertyGroup, identified by name, scoped to the active Activity. The PropertyGroup identified by name must be supported by the ServiceManager for this UserActivity instance.

Parameters:
name - the name of the type of PropertyGroup to return.
Returns:
A PropertyGroup instance of the type indicated by name.
Throws:
PropertyGroupUnknownException - Thrown if the named PropertyGroup type is not recognized.
NoActivityException - Thrown if there is no Activity associated with the calling thread of execution.
ServiceNotRegisteredException - Thrown if no ServiceManager has been registered.
SystemException - Thrown if the Activity service encounters an unexpected error condition.

registerService

public void registerService(ServiceManager service)
                     throws PropertyGroupUnknownException,
                            ServiceAlreadyRegisteredException,
                            SystemException
Registers a ServiceManager for the type of high-level service (HLS) whose activities are to be demarcated through the target UserActivity instance. The Activity service uses the properties of the registered ServiceManager to create and operate on Activities specific to that service. The UserActivity (or specialised ActivityManager) instance requires a ServiceManager to be registered with it before it may be used to begin new Activities.

Parameters:
service - the ServiceManager for the HLS whose activities are to be demarcated through the target UserActivity instance.
Throws:
PropertyGroupUnknownException - Thrown if the ServiceManager cannot obtain a PropertyGroupManager for one or more of the PropertyGroups it uses.
ServiceAlreadyRegisteredException - Thrown if a ServiceManager has already been registered with the UserActivity instance.
SystemException - Thrown if the Activity service encounters an unexpected error condition.

getService

public ServiceManager getService()
                          throws SystemException
Returns the registered ServiceManager for this UserActivity instance.

Returns:
The ServiceManager for this UserActivity instance, or null if none has been registered.
Throws:
SystemException - Thrown if the Activity service encounters an unexpected error condition.

recreate

public ActivityCoordinator recreate(GlobalId activity,
                                    GlobalId parent,
                                    boolean resume)
                             throws ServiceNotRegisteredException,
                                    com.ibm.ws.javax.activity.ActivityCompletedException,
                                    java.lang.IllegalArgumentException,
                                    SystemException
Recreates an Activity after a failure. The Activity to be recreated is identified by the activity parameter. Activity context hierarchies may be recreated by an HLS in two ways:
  1. By specifying the parent, if any, of each recreated Activity. Activities so created are not associated with the calling thread on completion of this operation.
  2. By specifying true for the resume flag to associate each recreated Activity with the calling thread. An Activity recreated in this way is recreated as a child of any Activity already associated with the calling thread. The parent parameter must be null when using this approach.

The Activity service contacts the reqistered ServiceManager to recreate the Actions and SignalSets for the Activity identified by the GlobalId parameter.

Parameters:
activity - the GlobalId for the Activity to be recreated.
parent - the GlobalId of the parent of the Activity to be recreated.
resume - specifies whether or not the recreated Activity context becomes associated with the calling thread. This parameter is used only when the parent is null. A value of true combined with a non-null parent is an illegal combination and results in an IllegalArgumentException.
Returns:
The ActivityCoordinator for the recreated Activity.
Throws:
ServiceNotRegisteredException - Thrown if no ServiceManager has been registered or if the ServiceManager for a recreated Activity is not available.
ActivityCompletedException - Thrown if the Activity service and ServiceManager have no knowledge of the specified globalId - for example if the Activity it identifies has already completed or if it never got as far as logging persistent state.
java.lang.IllegalArgumentException - Thrown if an illegal combination of parent and resume values is specified.
SystemException - Thrown if the Activity service encounters an unexpected error condition.

recover

public GlobalId[] recover()
                   throws ServiceNotRegisteredException,
                          SystemException
Driven by a HLS, after a failure, to retrieve a list of GlobalIds that the Activity service itself has logged information about. The Activity service itself is not responsible for persisting any information that is owned by an HLS, such as Actions and SignalSets.

The Activity service may persist data of its own to facilitate recoverability. Any data persisted by the Activity service is discarded when the relevant Activity completes. The recover method ensures that the HLS has a means by which it can drive the Activity service to complete any Activity that the Activity service had persisted data for. The recovery requirements placed on an HLS mean that any Activity whose GlobalId is returned on the recover method, for which the HLS has no record of its own, may be assumed to have completed successfully already or may be assumed never to have performed any recoverable work. Such recovered Activities may be immediately discarded by calling forget.

An Activity service implementation that does not log information of its own returns null when this method is called.

Returns:
The list of GlobalIds for which the Activity service has information persisted. If there are none, or if the Activity service does not log information of its own, then null is returned.
Throws:
ServiceNotRegisteredException - Thrown if no ServiceManager has been registered.
SystemException - Thrown if the Activity service encounters an unexpected error condition.

forget

public void forget(GlobalId globalId)
            throws ServiceNotRegisteredException,
                   SystemException
Forget the specified GlobalId. Driven by a HLS for each GlobalId returned by the recover method for which the HLS has no knowledge. Such Activities may be assumed to have completed successfully already or may be assumed never to have performed any recoverable work.

Parameters:
globalId - the GlobalId to be forgotten.
Throws:
ServiceNotRegisteredException - Thrown if no ServiceManager has been registered.
SystemException - Thrown if the Activity service encounters an unexpected error condition.

 

WebSphere is a trademark of the IBM Corporation in the United States, other countries, or both.

 

IBM is a trademark of the IBM Corporation in the United States, other countries, or both.