Stateful Web Services  Locate

Overview  Locate

With the exception of the simplest data retrieval or computation services, a service has to maintain some kind of state. Many services have a distinct state associated with every single client accessing them. A common example of such a service is a shopping application with the so-called shopping cart unique for each client.

In WSO2 SOA Enablement Server, this is accomplished with per-client instantiated services. In a per-client instantiated service, a new instance of the service class is created upon the first call of any client and this instance is associated with this client. For WSO2 SOA Enablement Server clients, the term "client" refers to a single proxy. Therefore, one client program can have as many distinct logical clients of the service as it needs.

The first section below describes how this mechanism works. The second section explains how this feature is enabled when deploying a service.

How It Works  Locate

When a client first calls a service, the service creates a new instance and adds the ID that identifies the new instance to the response message. The client then sends the ID along with every subsequent call. The server recognizes the first call by seeing that it does not contain an instance ID. During the service call, instance ID is accessible in proper contexts.

The code in Example 44 shows how to access the instance ID on the client side.

Client side

Example 44. Accessing Instance ID on the Client Side

ServiceClientContext sCtx = serviceClient.getContext();
String id = 
    (String) sCtx.getContextData().get(
    org.systinet.wasp.webservice.CallContext.INSTANCE_ID_KEY);

The code in Example 45 shows how to access the instance ID on the server side.

Example 45. Server Side

CallContext callCtx = Current.getCallContext();
String id = (String)callCtx.getContextData().get(CallContext.INSTANCE_ID_KEY);

The newly created instances have a limited lifetime. That is, they time out if not called for a given period of time. The instances and their time to live can be manipulated using an instance of ServiceInstance. At runtime, org.systinet.wasp.webservice.ServiceInstance can be obtained from ServiceEndpoint, which is retrieved by org.systinet.wasp.webservice.Registry.

Generating Proxy from WSDL  Locate

This feature is implemented by sending SOAP headers in the messages. By default the WSDL provided by SSJ for the service does not contain a declaration of these instance headers. However, to generate for example a .NET client proxy that will include instance value, it is necessary for the service's WSDL to contain a definition of this header. To get such a WSDL from a running service use the URL in the format:

http://host:port/service/path/wsdl?allheaders,

for example:

http://localhost:6060/demo/advanced/stateful/PerClientService/wsdl?allheaders

This URL should be passed to the .NET client proxy generator (wsdl.exe command line tool or via GUI dialog).

Deployment  Locate

To make a per-client instantiated service, its deployment descriptor must set the instantiation method to per-client. See the bullet on instantiation-method in <service-instance> for more information.