com.ibm.ws.javax.activity
Interface ActivityCoordinator

All Known Subinterfaces:
PersistentActivityCoordinator
public interface ActivityCoordinator

The ActivityCoordinator is responsible for broadcasting signals to registered Actions. It has no logic to understand the signals or the meaning of Action outcomes, it simply acts as the messenger for the signals. There is a single ActivityCoordinator instance per Activity context.
This object’s equals method returns true if the parameter object represents the same Activity as the target object.

Method Summary
 void addAction(Action action, java.lang.String signalSetName, int priority)
          Establishes an interest relationship between the specified Action and SignalSet for the Activity represented by the target ActivityCoordinator.
 void addGlobalAction(Action action, int priority)
          Establishes an interest relationship between the specified Action and all SignalSets used by the Activity represented by the target ActivityCoordinator.
 Outcome completeActivity(int completionStatus)
          Causes the Activity associated with the target ActivityCoordinator to complete with the specified CompletionStatus.
 Action[] getActions(java.lang.String signalSetName)
          Returns all the Actions that have been registered with an interest in the specified signalSetName.
 java.lang.String getCompletionSignalSetName()
          Returns the name of the SignalSet, if any, that will be used for the distribution of completion signals when the current Activity completes.
 GlobalId getGlobalId()
          Returns the GlobalId of the Activity represented by the target ActivityCoordinator.
 java.lang.String getName()
          Returns a printable string describing the Activity represented by the target ActivityCoordinator.
 int getNumberRegisteredActions(java.lang.String signalSetName)
          Returns the number of Actions, including global Actions, registered with the target ActivityCoordinator with an interest in the specified SignalSet.
 ActivityCoordinator getParent()
          Returns the parent ActivityCoordinator or null if the target ActivityCoordinator represents a top-level Activity.
 int getParentStatus()
          Returns the Status of the Activity represented by the target ActivityCoordinator's parent.
 int getStatus()
          Returns the Status of the Activity represented by the target ActivityCoordinator.
 Outcome heuristicComplete(int completionStatus, boolean remember)
          Causes the Activity associated with the target ActivityCoordinator to complete with the specified CompletionStatus, but in a manner that acknowledges that the completion request has been driven heuristically.
 boolean isSameActivity(ActivityCoordinator coord)
          Returns true if the specified coord represents the same Activity as the target ActivityCoordinator.
 Outcome processSignalSet(java.lang.String signalSetName, int completionStatus)
          Causes the SignalSet specified by signalSetName to start producing signals for all registered Actions at times other than during completion.
 void removeAction(Action action, java.lang.String signalSetName)
          Removes the interest relationship between the specified Action and SignalSet for the Activity represented by the target ActivityCoordinator.
 void removeGlobalAction(Action action)
          Removes the interest relationship between the specified Action and all SignalSets for the Activity represented by the target ActivityCoordinator.
 void setCompletionSignalSetName(java.lang.String signalSetName)
          Sets the name of the SignalSet that should be used for the distribution of completion signals when the current Activity completes.
 

Method Detail

addAction

public void addAction(Action action,
                      java.lang.String signalSetName,
                      int priority)
               throws SignalSetUnknownException,
                      SystemException,
                      java.lang.IllegalStateException
Establishes an interest relationship between the specified Action and SignalSet for the Activity represented by the target ActivityCoordinator. When a Signal which is a member of the SignalSet is sent, the processSignal method of the Action will be invoked with that Signal. If multiple Actions are registered, then priority may be used to place an order on how they will be invoked when Signals are sent: higher priority Actions will occur first in the Action list, and hence be invoked before other, lower priority, Actions. The priority value must be a positive value; a value of zero means that the Activity Service implementation is free to place the Action at any point in the Action list.
If the specified Action is registered multiple times for the same SignalSet then it will be invoked multiple times with the Signals from that SignalSet.

Parameters:
action - the action to add an interest for.
signalSetName - the name of the SignalSet from which Signals are required by the Action
priority - the priority order, with respect to other registered Actions, with which the specified Action is called by the ActivityCoordinator.
A value of zero means that the Activity Service implementation is free to place the Action at any point in the Action list.
Throws:
SignalSetUnknownException - Thrown if the specified signalSetName is not recognized.
java.lang.IllegalStateException - Thrown if the Activity represented by the target ActivityCoordinator has begun completion or has completed.
SystemException - Thrown if the Activity service encounters an unexpected error condition.

addGlobalAction

public void addGlobalAction(Action action,
                            int priority)
                     throws SystemException,
                            java.lang.IllegalStateException
Establishes an interest relationship between the specified Action and all SignalSets used by the Activity represented by the target ActivityCoordinator. When a Signal which is a member of any of the SignalSets is sent, the processSignal method of the Action will be invoked with that Signal. If multiple Actions are registered, then priority may be used to place an order on how they will be invoked when Signals are sent: higher priority Actions will occur first in the Action list, and hence be invoked before other, lower priority, Actions. The priority value must be a positive value; a value of zero means that the Activity Service implementation is free to place the Action at any point in the Action list.
If the specified Action is registered multiple times with the target ActivityCoordinator then it will be invoked multiple times with each Signal.

Parameters:
action - the action to add an interest for.
priority - the priority order, with respect to other registered Actions, with which the specified Action is called by the ActivityCoordinator.
A value of zero means that the Activity Service implementation is free to place the Action at any point in the Action list.
Throws:
java.lang.IllegalStateException - Thrown if the Activity represented by the target ActivityCoordinator has begun completion or has completed.
SystemException - Thrown if the Activity service encounters an unexpected error condition.

removeAction

public void removeAction(Action action,
                         java.lang.String signalSetName)
                  throws ActionNotFoundException,
                         SystemException,
                         java.lang.IllegalStateException
Removes the interest relationship between the specified Action and SignalSet for the Activity represented by the target ActivityCoordinator. If signalSetName is an empty String then the interest relationship is removed between the specified Action and all SignalSets in the target Activity. This operation has no effect on any global actions.
If the specified Action was registered multiple times with the target ActivityCoordinator then only a single instance of this Action is removed by each call to this method.

Parameters:
action - the action to remove.
signalSetName - the name of the SignalSet from which Signals are no longer required by the Action. If signalSetName is an empty String then no Signals from any any SignalSets will be sent to the Action.
Throws:
ActionNotFoundException - Thrown if the specified Action is not recognized.
java.lang.IllegalStateException - Thrown if the Activity represented by the target ActivityCoordinator has begun completion or has completed.
SystemException - Thrown if the Activity service encounters an unexpected error condition.

removeGlobalAction

public void removeGlobalAction(Action action)
                        throws ActionNotFoundException,
                               SystemException,
                               java.lang.IllegalStateException
Removes the interest relationship between the specified Action and all SignalSets for the Activity represented by the target ActivityCoordinator. This operation has no effect on any non-global actions.
If the specified Action was registered multiple times with the target ActivityCoordinator then only a single instance of this Action is removed by each call to this method.

Parameters:
action - the action to remove.
Throws:
ActionNotFoundException - Thrown if the specified Action is not recognized.
java.lang.IllegalStateException - Thrown if the Activity represented by the target ActivityCoordinator has begun completion or has completed.
SystemException - Thrown if the Activity service encounters an unexpected error condition.

getNumberRegisteredActions

public int getNumberRegisteredActions(java.lang.String signalSetName)
                               throws SignalSetUnknownException,
                                      SystemException
Returns the number of Actions, including global Actions, registered with the target ActivityCoordinator with an interest in the specified SignalSet.

Returns:
The number of Actions registered to receive signals from the specified SignalSet.
Throws:
SignalSetUnknownException - Thrown if the specified signalSetName is not recognized.
SystemException - Thrown if the Activity service encounters an unexpected error condition.

setCompletionSignalSetName

public void setCompletionSignalSetName(java.lang.String signalSetName)
                                throws SignalSetUnknownException,
                                       SystemException,
                                       java.lang.IllegalStateException
Sets the name of the SignalSet that should be used for the distribution of completion signals when the current Activity completes.
This method can be called multiple times during the lifetime of an Activity, before the Activity starts completion processing. The last value specified before completion processing starts is used during completion processing.

Parameters:
signalSetName - the name of the SignalSet that will be used for the distribution of completion signals when the current Activity completes.
Throws:
SignalSetUnknownException - Thrown if the specified signalSetName is not recognized.
java.lang.IllegalStateException - Thrown if the Activity represented by the target ActivityCoordinator has begun completion or has completed.
SystemException - Thrown if the Activity service encounters an unexpected error condition.

getCompletionSignalSetName

public java.lang.String getCompletionSignalSetName()
                                            throws SystemException
Returns the name of the SignalSet, if any, that will be used for the distribution of completion signals when the current Activity completes.

Returns:
The name of the SignalSet that will be used for the distribution of completion signals when the current Activity completes. If no CompletionSignalSet has been set then null is returned.
Throws:
SystemException - Thrown if the Activity service encounters an unexpected error condition.

getParent

public ActivityCoordinator getParent()
                              throws SystemException
Returns the parent ActivityCoordinator or null if the target ActivityCoordinator represents a top-level Activity.

Returns:
The parent ActivityCoordinator or null if the target ActivityCoordinator represents a top-level Activity.
Throws:
SystemException - Thrown if the Activity service encounters an unexpected error condition.

getGlobalId

public GlobalId getGlobalId()
                     throws SystemException
Returns the GlobalId of the Activity represented by the target ActivityCoordinator.

Returns:
The GlobalId of the Activity represented by the target ActivityCoordinator.
Throws:
SystemException - Thrown if the Activity service encounters an unexpected error condition.

getStatus

public int getStatus()
              throws SystemException
Returns the Status of the Activity represented by the target ActivityCoordinator.

Returns:
The Status of the Activity represented by the target ActivityCoordinator.
Throws:
SystemException - Thrown if the Activity service encounters an unexpected error condition.

getParentStatus

public int getParentStatus()
                    throws SystemException
Returns the Status of the Activity represented by the target ActivityCoordinator's parent. If the target ActivityCoordinator represents a top-level Activity, then the Status of this top-level Activity is returned.

Returns:
The Status of the target ActivityCoordinator's parent Activity or the Status of the target ActivityCoordinator if the target object represents a top-level Activity.
Throws:
SystemException - Thrown if the Activity service encounters an unexpected error condition.

getName

public java.lang.String getName()
                         throws SystemException
Returns a printable string describing the Activity represented by the target ActivityCoordinator.

Returns:
A printable string describing the Activity represented by the target ActivityCoordinator.
Throws:
SystemException - Thrown if the Activity service encounters an unexpected error condition.

isSameActivity

public boolean isSameActivity(ActivityCoordinator coord)
                       throws SystemException
Returns true if the specified coord represents the same Activity as the target ActivityCoordinator.

Returns:
true if the specified coord represents the same Activity as the target ActivityCoordinator.
Throws:
SystemException - Thrown if the Activity service encounters an unexpected error condition.

getActions

public Action[] getActions(java.lang.String signalSetName)
                    throws SignalSetUnknownException,
                           SystemException
Returns all the Actions that have been registered with an interest in the specified signalSetName. This method may be used by a HLS that has determined that an Activity needs to be persisted and needs to log the Actions registered in the Activity.

Parameters:
signalSetName - the name of a SignalSet supported by the HLS. Only Actions registered with an interest in this SignalSet are returned by this operation. If this parameter is null then all global Actions are returned.
Returns:
The array of Actions registered with an interest in the specified SignalSet. If there are none, then a zero element array is returned.
Throws:
SignalSetUnknownException - Thrown if the specified signalSetName is not recognized.
SystemException - Thrown if the Activity service encounters an unexpected error condition.

completeActivity

public Outcome completeActivity(int completionStatus)
                         throws ActivityPendingException,
                                ContextPendingException,
                                NotOriginatorException,
                                InvalidStateException,
                                ActivityNotProcessedException,
                                SystemException
Causes the Activity associated with the target ActivityCoordinator to complete with the specified CompletionStatus. The Activity service sets the Status to StatusCompleting before asking any completion SignalSet to start producing Signals.
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.
The UserActivity interface should be used in preference to the ActivityCoordinator for completing Activities in most circumstances. This method is provided primarily for use after recovery when the Activity to be completed is not associated with the calling thread.

Parameters:
completionStatus - the CompletionStatus with which the target 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:
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.
SystemException - Thrown if the Activity service encounters an unexpected error condition.

heuristicComplete

public Outcome heuristicComplete(int completionStatus,
                                 boolean remember)
                          throws ActivityPendingException,
                                 ContextPendingException,
                                 InvalidStateException,
                                 ActivityNotProcessedException,
                                 SystemException
Causes the Activity associated with the target ActivityCoordinator to complete with the specified CompletionStatus, but in a manner that acknowledges that the completion request has been driven heuristically. The Activity service sets the Status to StatusCompletingHeuristic before asking any completion SignalSet to start producing Signals. The boolean remember flag indicates if the outcome of such a partial activity completion will be persisted to become involved in a latter normal completion activity driven from the root node.


This method may be used in an environment that is different from that in which the Activity to be completed was started. It is otherwise identical to completeActivity.

Parameters:
completionStatus - the CompletionStatus with which the target Activity should end.
remember - Instructs the coordinator wether or not to persist the completion outcome.
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
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.
Throws:
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.
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.
SystemException - Thrown if the Activity service encounters an unexpected error condition.

processSignalSet

public Outcome processSignalSet(java.lang.String signalSetName,
                                int completionStatus)
                         throws SignalSetUnknownException,
                                ActivityNotProcessedException,
                                com.ibm.ws.javax.activity.InvalidActivityException,
                                SystemException
Causes the SignalSet specified by signalSetName to start producing signals for all registered Actions at times other than during completion. Pre-defined SignalSets, such as Synchronization, cannot be requested to produce signals via this method.

Parameters:
signalSetName - the name of the SignalSet that is to produce signals.
completionStatus - the CompletionStatus of the Activity at the time of calling. The completionStatus may influence the signals that are produced.
Returns:
The Outcome returned is both set by and given meaning by the specified SignalSet. It may be null.
Throws:
SignalSetUnknownException - Thrown if the specified signalSetName is not recognized.
ActivityNotProcessedException - Thrown if the signals required to complete this operation could not be produced. The Activity's final Status is StatusError.
InvalidActivityException - Thrown if the SignalSet is already producing signals or if the Activity has completed.
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.