PropertyGroupManager (IBM WebSphere Application Server [activity])

com.ibm.ws.javax.activity.propertygroup
Interface PropertyGroupManager

public interface PropertyGroupManager

A PropertyGroupManager is an entity that is provided by a PropertyGroup implementation and understands how to create and manipulate a specific type of PropertyGroup. It is registered with the Activity service and is used by the Activity service to create PropertyGroup instances and to manipulate the PropertyGroupContext that is implicitly propagated as part of an Activity context.
For a particular type of PropertyGroup, there must be a PropertyGroupManager registered in each client and server execution environment for which the PropertyGroup will be accessed. If PropertyGroupContext is propagated, as part of an Activity context, to an environment in which there is no appropriate PropertyGroupManager registered, then the PropertyGroupContext is ignored and is not available within that environment although it will be passed on to any downstream environment to which the Activity context is further distributed.

Method Summary

PropertyGroup create(PropertyGroup parent, GlobalId globalId)
          Creates a new instance of a PropertyGroup specialization.

java.util.Properties getProperties()
          Returns a Properties object that describes meta-properties for the behaviour of the PropertyGroupManager.

PropertyGroupContext marshalRequest(PropertyGroup pg)
          Called by the Activity service when it marshals an Activity context for an outbound request.

PropertyGroupContext marshalResponse(PropertyGroup pg)
          Called by the Activity service when it marshals an Activity context for an outbound response.

PropertyGroup recoverPropertyGroup(PropertyGroup parent, GlobalId globalId)
          Driven after a failure in order to retrieve any recovered PropertyGroup that was involved in the Activity identified by globalId prior to the failure.

PropertyGroup unmarshalRequest(PropertyGroupContext ctx, PropertyGroup pg, PropertyGroup parent, GlobalId globalId)
          Creates a new instance of a PropertyGroup specialization from an inbound PropertyGroupContext.

void unmarshalResponse(PropertyGroupContext ctx, PropertyGroup pg)
          Called by the Activity service when it unmarshals an Activity context on an inbound response.

Method Detail

create
public PropertyGroup create(PropertyGroup parent,
                            GlobalId globalId)
Creates a new instance of a PropertyGroup specialization. This method is called by the Activity service when a new Activity, with the specified Global, is begun. A null value for the parent indicates that this is a top-level Activity.
It is implementation-dependent whether or not the Activity is active on the thread when this method executes.

Parameters:
parent - the PropertyGroup object associated with the parent Activity. A value of null indicates that the new Activity is a top-level Activity.
globalId - the Global of the new Activity.
Returns:
The reference of the PropertyGroup specialization created.

recoverPropertyGroup
public PropertyGroup recoverPropertyGroup(PropertyGroup parent,
                                          GlobalId globalId)
                                   throws SystemException
Driven after a failure in order to retrieve any recovered PropertyGroup that was involved in the Activity identified by globalId prior to the failure. A null value for the parent indicates that there is no parent for this PropertyGroup instance. On completion of this method, the recovered PropertyGroup has been recreated and associated with Activity identified by globalId. The HLS that provides the PropertyGroupManager determines the point, during the processing of an Activity, at which it must persist the state of any PropertyGroup and other persistent state. 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 any PropertyGroup recovered by the HLS for the Activity identified by globalId.

Parameters:
parent - the PropertyGroup object associated with the recovered Activity's parent. A value of null indicates that the new Activity has no ancestor Activities from the same HLS.
globalId - the GlobalId for the recreated Activity.
Returns:
The PropertyGroup recovered by the HLS for the Activity identified by globalId. If there is none, then null is returned.
Throws:
SystemException - Thrown if the Activity service encounters an unexpected error condition.

marshalRequest
public PropertyGroupContext marshalRequest(PropertyGroup pg)
Called by the Activity service when it marshals an Activity context for an outbound request. The PropertyGroupManager is responsible for marshalling its own PropertyGroupContext to be included in that Activity context.
The Activity is active on the thread when this method executes.

Parameters:
pg - the PropertyGroup object whose contents are to be encapsulated by a PropertyGroupContext.
Returns:
A PropertyGroupContext that represents the context of the PropertyGroup being managed. The Activity service converts this object to an org.omg.CosActivity.PropertyGroupIdentity and marshals it for propagation over the wire with the remote request.

marshalResponse
public PropertyGroupContext marshalResponse(PropertyGroup pg)
Called by the Activity service when it marshals an Activity context for an outbound response. The PropertyGroupManager is responsible for marshalling its own PropertyGroupContext to be included in that Activity context.
The Activity is active on the thread when this method executes.
This method is only called if the MarshalResponseUpdate Property is set in the Properties returned by getProperties.

Parameters:
pg - the PropertyGroup object whose contents are to be encapsulated by a PropertyGroupContext.
Returns:
A PropertyGroupContext that represents the context of the PropertyGroup being managed. The Activity service converts this object to an org.omg.CosActivity.PropertyGroupIdentity and marshals it for propagation over the wire with the remote response.

unmarshalRequest
public PropertyGroup unmarshalRequest(PropertyGroupContext ctx,
                                      PropertyGroup pg,
                                      PropertyGroup parent,
                                      GlobalId globalId)
Creates a new instance of a PropertyGroup specialization from an inbound PropertyGroupContext. Called by the Activity service when it unmarshals an Activity context, identified by globalId, on an inbound request. The PropertyGroupManager is responsible for unmarshalling its own PropertyGroupContext. If this is a nested Activity, then the parent Activity's PropertyGroup is passed as the parent, otherwise parent is null. Any existing PropertyGroup already maintained by the Activity, or null, is passed in the pg parameter, and this is replaced by the new PropertyGroup.
It is implementation-dependent whether or not the Activity is active on the thread when this method executes.

Parameters:
ctx - the PropertyGroupContext received on an inbound request.
pg - the PropertyGroup currently associated with the Activity, or null if there is none.
parent - the PropertyGroup associated with the parent Activity, or null if the current Activity is a top-level Activity.
globalId - the Global of the new Activity.
Returns:
The reference of the PropertyGroup specialization created.

unmarshalResponse
public void unmarshalResponse(PropertyGroupContext ctx,
                              PropertyGroup pg)
Called by the Activity service when it unmarshals an Activity context on an inbound response. The PropertyGroupManager is responsible for unmarshalling its own PropertyGroupContext.
The Activity is active on the thread when this method executes.
This method is only called if the UnmarshalResponseUpdate property is set in the Properties returned by getProperties.

Parameters:
ctx - the PropertyGroupContext received on an inbound response.
pg - the PropertyGroup currently associated with the Activity, or null if there is none.

getProperties
public java.util.Properties getProperties()
Returns a Properties object that describes meta-properties for the behaviour of the PropertyGroupManager.
The following properties may be specified by a PropertyGroupManager implementation and may be used to influence the behaviour of an Activity service implementation, although these are hints to the Activity service rather than required behaviour.

"marshalResponseUpdate"
Indicates whether or not the PropertyGroupManager should be called when an outbound response is marshalled.
A value of "true" indicates that the context for the managed PropertyGroup should be updated on a response.
A value of "false" indicates that the context for the managed PropertyGroup is not updated on a response so the PropertyGroupManager is not called for marshalResponse.
The default value is "false"
It may be preferable for either a security or a performance point of view not to transmit server context back to a client with a response.
"unmarshalResponseUpdate"
Indicates whether or not the PropertyGroupManager should be called when an inbound response is unmarshalled.
A value of "true" indicates that the context for the managed PropertyGroup should be updated by the response.
A value of "false" indicates that the context for the managed PropertyGroup is not updated by the response so the PropertyGroupManager is not called for unmarshalResponse.
The default value is "false"
It may be preferable for either a security or a performance point of view not to allow the local context to be updated by changes made in a downstream node.
"cacheable"
Indicates whether or not the PropertyGroup implementation caches context during the lifetime of the Activity. Any Activity that uses such a PropertyGroup is required to manage the timeout of such PropertyGroups. Possible values are "true" and "false".
The default value is "false"
"maxSendSize"
Indicates the maximum size of the PropertyGroup context data that should be allowed to be passed on outbound requests and responses. The maximum size applies to the length of the InputStream or OutputStream occupied by the marshalled form of the PropertyGroupContext. An attempt to send more data than the maximum allowed may result in an org.omg.CORBA.IMP_LIMIT exception being raised during marshalling. Possible values are String representations of an int type.
There is no default value for this property, indicating that there is no limit on the size of the data.
"maxRecvSize"
Indicates the maximum size of the PropertyGroup context data that the Activity service should accept and pass on to a PropertyGroupManager on an inbound request or response. The maximum size applies to the length of the InputStream or OutputStream occupied by the marshalled form of the PropertyGroupContext. Any inbound request or response that contains more data than the maximum allowed may result in an org.omg.CORBA.IMP_LIMIT exception being raised during unmarshalling. Possible values are String representations of an int type.
There is no default value for this property, indicating that there is no limit on the size of the data.

Other properties may be defined in the future or may be introduced between consenting PropertyGroup and Activity service implementors.

Returns:
A Properties object that describes meta-properties for the behaviour of the PropertyGroupManager.

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
PropertyGroup	create(PropertyGroup parent, GlobalId globalId) Creates a new instance of a PropertyGroup specialization.
java.util.Properties	getProperties() Returns a Properties object that describes meta-properties for the behaviour of the PropertyGroupManager.
PropertyGroupContext	marshalRequest(PropertyGroup pg) Called by the Activity service when it marshals an Activity context for an outbound request.
PropertyGroupContext	marshalResponse(PropertyGroup pg) Called by the Activity service when it marshals an Activity context for an outbound response.
PropertyGroup	recoverPropertyGroup(PropertyGroup parent, GlobalId globalId) Driven after a failure in order to retrieve any recovered PropertyGroup that was involved in the Activity identified by globalId prior to the failure.
PropertyGroup	unmarshalRequest(PropertyGroupContext ctx, PropertyGroup pg, PropertyGroup parent, GlobalId globalId) Creates a new instance of a PropertyGroup specialization from an inbound PropertyGroupContext.
void	unmarshalResponse(PropertyGroupContext ctx, PropertyGroup pg) Called by the Activity service when it unmarshals an Activity context on an inbound response.

com.ibm.ws.javax.activity.propertygroup Interface PropertyGroupManager

create

recoverPropertyGroup

marshalRequest

marshalResponse

unmarshalRequest

unmarshalResponse

getProperties

com.ibm.ws.javax.activity.propertygroup
Interface PropertyGroupManager