ServiceManager (IBM WebSphere Application Server [activity])

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

All Known Subinterfaces:
HighlyAvailableServiceManager, WebSphereServiceManager

public interface ServiceManager

A ServiceManager is an entity that is provided by a high-level service (HLS) that uses the Activity service; it is a factory for the HLS's objects and also specifies how the HLS's Activities should be managed. In particular, it is used to specify:

which PropertyGroups the HLS uses
the CompletionSignalSet that is used to complete the HLS's Activities.
the ServiceInformation for the HLS's Activities. This object describes which ContextGroup the HLS participates in and is propagated as part of the Activity service context.

The methods of the ServiceManager interface may execute with or without an Activity service context being associated with the thread.
The Activity service uses an HLS's ServiceManager when it creates and operates on Activities specific to that HLS.

Method Summary

void activityImported(ServiceInformation serviceInfo)
          Indicates that an Activity of the type specific to the target ServiceManager has been received from another process and is active on the current thread.

int getActivityType()
          Returns the type of the Activities that are created for this HLS.

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.

PropertyGroupManager getPropertyGroupManager(java.lang.String propertyGroupName)
          Returns a reference to an instance of a PropertyGroupManager, responsible for creating and managing the PropertyGroup identified in PropertyGroupName.

java.lang.String[] getPropertyGroupNames()
          Returns the array of PropertyGroup names that are used by the HLS.

ServiceInformation getServiceInformation()
          Returns a reference to the ServiceInformation object that encapsulates all the information about the HLS that needs to be propagated as part of Activity service context in the type_specific_data, for example the ContextGroup name.

SignalSet getSignalSet(java.lang.String signalSetName)
          Returns a reference to an instance of the named SignalSet.

SubordinateSignalSet getSubordinateSignalSet(java.lang.String signalSetName)
          Returns a reference to an instance of the named SubordinateSignalSet.

RecoverableAction[] recoverActions(GlobalId globalId, java.lang.String signalSetName)
          Driven after a failure in order to retrieve recovered Actions that were involved in the Activity identified by globalId prior to the failure and which had been registered with an interest in the SignalSet identified by signalSetName.

SignalSet[] recoverSignalSets(GlobalId globalId)
          Driven after a failure in order to retrieve any recovered SignalSets that were involved in the Activity identified by globalId prior to the failure.

Method Detail

getServiceInformation
public ServiceInformation getServiceInformation()
Returns a reference to the ServiceInformation object that encapsulates all the information about the HLS that needs to be propagated as part of Activity service context in the type_specific_data, for example the ContextGroup name.
The returned value must not change if this method is called multiple times.

Returns:
The ServiceInformation for the HLS.

getSignalSet
public SignalSet getSignalSet(java.lang.String signalSetName)
                       throws SignalSetUnknownException,
                              NoImplementException
Returns a reference to an instance of the named SignalSet.
In some execution environments, such as a J2EE client, this method need not be implemented and calling it may result in a NoImplementException.

Parameters:
signalSetName - the name of the type of SignalSet whose object reference is to be returned.
Throws:
SignalSetUnknownException - Thrown if the named SignalSet is not recognized by the ServiceManager.
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.

getSubordinateSignalSet
public SubordinateSignalSet getSubordinateSignalSet(java.lang.String signalSetName)
                                             throws SignalSetUnknownException,
                                                    NoImplementException
Returns a reference to an instance of the named SubordinateSignalSet.
For each named SignalSet that an HLS provides, it must provide a SubordinateSignalSet of the same name. If the SignalSets provided by an HLS can be used either to produce Signals or to consume Signals received from a superior server then the same SubordinateSignalSet may be returned in response to both getSignalSet and getSubordinateSignalSet
In some execution environments, such as a J2EE client, this method need not be implemented and calling it may result in a NoImplementException.

Parameters:
signalSetName - the name of the type of SignalSet whose object reference is to be returned.
Throws:
SignalSetUnknownException - Thrown if the named SignalSet is not recognized by the ServiceManager.
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.

getPropertyGroupManager
public PropertyGroupManager getPropertyGroupManager(java.lang.String propertyGroupName)
                                             throws PropertyGroupUnknownException
Returns a reference to an instance of a PropertyGroupManager, responsible for creating and managing the PropertyGroup identified in PropertyGroupName.
In some execution environments, such as a J2EE client, this method need not be implemented and calling it may result in a NoImplementationException.

Parameters:
propertyGroupName - the name of the type of PropertyGroupManager whose object reference is to be returned.
Returns:
A PropertyGroupManager instance.
Throws:
PropertyGroupUnknownException - Thrown if the named PropertyGroup is not recognized by the ServiceManager.

getPropertyGroupNames
public java.lang.String[] getPropertyGroupNames()
Returns the array of PropertyGroup names that are used by the HLS.
Each time an Activity for this HLS is started, an instance of each PropertyGroup in the list is started and associated with the Activity.
The returned value must not change if this method is called multiple times.

Returns:
An array of PropertyGroup names that are used by the HLS. If no PropertyGroups have been specified then this method returns null.

getCompletionSignalSetName
public 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.
The returned value must not change if this method is called multiple times.

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.

getActivityType
public int getActivityType()
Returns the type of the Activities that are created for this HLS. The type is propagated in the ActivityIdentity part of the Activity context and confers information about the format of the activity_specific_data encoded in the ActivityIdentity.
This function should return either a value of 2 to indicate that no J2EE-specific information is contained in the ActivityIdentity.activity_specific_data or 0x4A324545 to indicate that a ServiceInformation object is contained in the ActivityIdentity.activity_specific_data
The returned value must not change if this method is called multiple times.

Returns:
The type value that will be set into the omg.org.CosActivity.ActivityIdentity for Activities created on behalf of this HLS.

activityImported
public void activityImported(ServiceInformation serviceInfo)
Indicates that an Activity of the type specific to the target ServiceManager has been received from another process and is active on the current thread. This method is called by the Activity service after its context filter (for example an IIOP portable interceptor), executed on receipt of an inbound request, has imported a new Activity context into the execution domain.
Optional ServiceInformation specific to the type of target ServiceManager may be received with the request in the ActivityContext.

Parameters:
serviceInfo - the ServiceInformation object encoded in the type_specific_data of a received context.

recoverSignalSets
public SignalSet[] recoverSignalSets(GlobalId globalId)
                              throws com.ibm.ws.javax.activity.ActivityCompletedException,
                                     SystemException
Driven after a failure in order to retrieve any recovered SignalSets that were involved in the Activity identified by globalId prior to the failure. The HLS that provides the ServiceManager determines the point, during the processing of an Activity, at which it must persist the state of its SignalSets and Actions. Any failure, between this point and the end of the Activity, requires the HLS to recreate the Activity and, eventually, complete it. Each recreated Activity that uses the target ServiceManager calls this method to retrieve the list of SignalSets recovered by the HLS for the Activity identified by globalId.

Parameters:
globalId - the GlobalId for the recreated Activity.
Returns:
The list of SignalSets recovered by the HLS for the Activity identified by globalId. If there are none, then a zero element array is returned.
Throws:
SystemException - Thrown if the Activity service encounters an unexpected error condition.
com.ibm.ws.javax.activity.ActivityCompletedException

recoverActions
public RecoverableAction[] recoverActions(GlobalId globalId,
                                          java.lang.String signalSetName)
                                   throws com.ibm.ws.javax.activity.ActivityCompletedException,
                                          SignalSetUnknownException,
                                          SystemException
Driven after a failure in order to retrieve recovered Actions that were involved in the Activity identified by globalId prior to the failure and which had been registered with an interest in the SignalSet identified by signalSetName. The HLS that provides the ServiceManager determines the point, during the processing of an Activity, at which it must persist the state of its SignalSets and Actions. Any failure, between this point and the end of the Activity, requires the HLS to recreate the Activity and, eventually, complete it. Each recreated Activity that uses the target ServiceManager recovers its SignalSets via recoverSignalSets and then, for each recovered SignalSet, calls this method to obtain an array of Actions recovered by the HLS. The Actions in the array are ordered according to priority with the highest priority first.

Parameters:
globalId - the GlobalId for the recreated Activity.
signalSetName - the name of a SignalSet supported by the HLS. Only recovered Actions that registered an interest in this SignalSet are returned by this operation. If this parameter is null then all recovered global Actions are returned.
Returns:
The array of RecoverableActions recovered by the HLS for the specified SignalSet in the Activity identified by globalId. 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.
com.ibm.ws.javax.activity.ActivityCompletedException

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.

Method Summary
void	activityImported(ServiceInformation serviceInfo) Indicates that an Activity of the type specific to the target ServiceManager has been received from another process and is active on the current thread.
int	getActivityType() Returns the type of the Activities that are created for this HLS.
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.
PropertyGroupManager	getPropertyGroupManager(java.lang.String propertyGroupName) Returns a reference to an instance of a PropertyGroupManager, responsible for creating and managing the PropertyGroup identified in PropertyGroupName.
java.lang.String[]	getPropertyGroupNames() Returns the array of PropertyGroup names that are used by the HLS.
ServiceInformation	getServiceInformation() Returns a reference to the ServiceInformation object that encapsulates all the information about the HLS that needs to be propagated as part of Activity service context in the type_specific_data, for example the ContextGroup name.
SignalSet	getSignalSet(java.lang.String signalSetName) Returns a reference to an instance of the named SignalSet.
SubordinateSignalSet	getSubordinateSignalSet(java.lang.String signalSetName) Returns a reference to an instance of the named SubordinateSignalSet.
RecoverableAction[]	recoverActions(GlobalId globalId, java.lang.String signalSetName) Driven after a failure in order to retrieve recovered Actions that were involved in the Activity identified by globalId prior to the failure and which had been registered with an interest in the SignalSet identified by signalSetName.
SignalSet[]	recoverSignalSets(GlobalId globalId) Driven after a failure in order to retrieve any recovered SignalSets that were involved in the Activity identified by globalId prior to the failure.

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

getServiceInformation

getSignalSet

getSubordinateSignalSet

getPropertyGroupManager

getPropertyGroupNames

getCompletionSignalSetName

getActivityType

activityImported

recoverSignalSets

recoverActions

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