com.ibm.ws.javax.activity.coordination
Interface SignalSet

All Known Subinterfaces:
SubordinateSignalSet
public interface SignalSet

A SignalSet is an entity that is provided by a high-level service (HLS) built on top of the Activity service that produces Signals and understands the responses to those Signals. The SignalSet abstracts from the ActivityCoordinator the knowledge of which Signal should be distributed to the registered Actions based on the state of the Activity and responses to previous Signals. The Activity service itself then needs to provide only a very generic ActivityCoordinator to drive any specific SignalSet. The ActivityCoordinator simply asks a SignalSet for the next Signal and then broadcasts it to each interested Action in turn. The response from each Action is fed back to the SignalSet which has the knowledge of what that result means and which Signal should be sent next.

Method Summary
 void destroy()
          Called on the target object, by the Activity service, when the target object is no longer required and indicates to the object that it should perform any necessary clean-up.
 int getCompletionStatus()
          Returns the CompletionStatus for the Activity as the SignalSet has recorded it.
 Outcome getOutcome()
          Returns the final Outcome of the SignalSet.
 Signal getSignal()
          Returns the Signal to be sent to the Actions registered for this SignalSet.
 java.lang.String getSignalSetName()
          Returns the name of the target SignalSet.
 void setActivityCoordinator(ActivityCoordinator coord)
          Called by the Activity service to pass a reference to the ActivityCoordinator to the target SignalSet.
 void setCompletionStatus(int completionStatus, int status)
          Called by the Activity service to set both the CompletionStatus and Status before any signals are requested.
 CoordinationInformation setResponse(Outcome response)
          Called by an ActivityCoordinator to notify the target SignalSet of the Outcome returned by an Action in response to a Signal produced by the SignalSet.
 

Method Detail

getSignalSetName

public java.lang.String getSignalSetName()
Returns the name of the target SignalSet.

Returns:
the name of the target SignalSet.

getSignal

public Signal getSignal()
Returns the Signal to be sent to the Actions registered for this SignalSet. The Signal returned may depend upon the responses received from Actions that have been sent previous signals. If null is returned then this indicates that no other signals are to be sent and the SignalSet should not be asked for further Signals.

Returns:
The next Signal to distribute to the registered Actions.

setResponse

public CoordinationInformation setResponse(Outcome response)
                                    throws SignalSetInactiveException
Called by an ActivityCoordinator to notify the target SignalSet of the Outcome returned by an Action in response to a Signal produced by the SignalSet. The CoordinationInformation object returned indicates whether the Action whose Outcome has just been processed should continue to receive signals and whether the calling ActivityCoordinator should continue to use the current Signal or request the next one.
The logic of the SignalSet implementation determines how signaling should proceed. For example, an OTS Resource could be registered as an Action interested in a two-phase-commit SignalSet. If such an Action produced a VoteReadOnly Outcome in response to a prepare signal then it should receive no further signals. If it produced a VoteRollback Outcome then the signaling could proceed immediately to the next Signal even though some Actions may not have received the prepare Signal.

Parameters:
response - The Outcome of a registered Action in response to the current Signal. It is valid for response to be null.
Returns:
The CoordinationInformation object that describes whether the Action that produced the response Outcome should receive further signals and whether the current Signal should continue to be used.
Throws:
SignalSetInactiveException - Thrown if response is set without there first having been a call to the SignalSet getSignal or setSignal methods.

getOutcome

public Outcome getOutcome()
                   throws SignalSetActiveException
Returns the final Outcome of the SignalSet.

Returns:
The final Outcome of the SignalSet. It is valid for the Outcome to be null.
Throws:
SignalSetActiveException - Thrown if an attempt is made to obtain the final Outcome after the SignalSet has started to produce signals and before it has finished producing them.

setCompletionStatus

public void setCompletionStatus(int completionStatus,
                                int status)
Called by the Activity service to set both the CompletionStatus and Status before any signals are requested. The signals produced may be influenced by these two statuses. Once completion of an Activity has begun, control of the CompletionStatus belongs to the completion SignalSet and cannot be overridden by any other entity.

Parameters:
completionStatus - The CompletionStatus of the Activity at the time of the invocation.
status - The Status of the Activity at the time of the invocation.

getCompletionStatus

public int getCompletionStatus()
                        throws SignalSetActiveException
Returns the CompletionStatus for the Activity as the SignalSet has recorded it. This may be different from the CompletionStatus of the Activity prior to the SignalSet producing signals as it may have been modified during Signal processing.

Throws:
SignalSetActiveException - Thrown if no Signals have been produced by the SignalSet.

destroy

public void destroy()
Called on the target object, by the Activity service, when the target object is no longer required and indicates to the object that it should perform any necessary clean-up. The ActivityCoordinator with which the target object was associated is not available at the time this method is called.

setActivityCoordinator

public void setActivityCoordinator(ActivityCoordinator coord)
                            throws SignalSetActiveException
Called by the Activity service to pass a reference to the ActivityCoordinator to the target SignalSet. This may be used by a SignalSet to obtain references to all registered Actions in order to satisfy persistence requirements if the HLS, through its SignalSet and Actions, is recoverable. For example, consider the case of a two-phase commit SignalSet: once prepare signals have been sent and acknowledged successfully by Actions, the HLS needs to make those Action references persistent.

Parameters:
coord - - The ActivityCoordinator reference for the Activity under which the target SignalSet is operating.
Throws:
SignalSetActiveException - - Thrown if this method is called after the SignalSet has started to produce signals.

 

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.