Java Doc for StatefulWebServiceManager.java in  » 6.0-JDK-Modules » jax-ws-runtime » com » sun » xml » ws » developer » Java Source Code / Java DocumentationJava Source Code and Java Documentation

Usage

Application service implementation classes (or providers) who'd like to use the stateful web service support must declare Stateful annotation on a class. It should also have a public static method/field that takes StatefulWebServiceManager .

 @
Stateful  @
WebService class BankAccount {
 protected final int id;
 private int balance;
 BankAccount(int id) { this.id = id; }
 @
WebMethod public synchronized void deposit(int amount) { balance+=amount; }
 // either via a public static field
 
 public static 
StatefulWebServiceManager <BankAccount> manager;
 
 // ... or  via a public static method (the method name could be anything)
 
 public static void setManager(
StatefulWebServiceManager <BankAccount> manager) {
 ...
 }
 
 }
 

After your service is deployed but before you receive a first request, the resource injection occurs on the field or the method.

A stateful web service class does not need to have a default constructor. In fact, most of the time you want to define a constructor that takes some arguments, so that each instance carries certain state (as illustrated in the above example.)

Each instance of a stateful web service class is identified by an unique EndpointReference . Your application creates an instance of a class, then you'll have the JAX-WS RI assign this unique EPR for the instance as follows:

 @
WebService class Bank { // this is ordinary stateless service
 @
WebMethod public synchronized W3CEndpointReference login(int accountId, int pin) {
 if(!checkPin(pin))
 throw new AuthenticationFailedException("invalid pin");
 BankAccount acc = new BankAccount(accountId);
 return BankAccount.manager.
StatefulWebServiceManager.export export (acc);
 }
 }
 

Typically you then pass this EPR to remote systems. When they send messages to this EPR, the JAX-WS RI makes sure that the particular exported instance associated with that EPR will receive a service invocation.

Things To Consider

When you no longer need to tie an instance to the EPR, use StatefulWebServiceManager.unexport(Object) so that the object can be GC-ed (or else you'll leak memory.) You may choose to do so explicitly, or you can rely on the time out by using StatefulWebServiceManager.setTimeout(long,Callback) .

StatefulWebServiceManager is thread-safe. It can be safely invoked from multiple threads concurrently.
author:
   Kohsuke Kawaguchi
See Also:   StatefulFeature
since:
   2.1

This method works like StatefulWebServiceManager.export(Object) except that you can obtain the EPR in your choice of addressing version, by passing in the suitable epr parameter.
Parameters:
  epr - Either W3CEndpointReference or MemberSubmissionEndpointReference.If other types are specified, this method throws an WebServiceException.
Parameters:
  o - The object to be exported, whose identity be referenced by the returned EPR.
Parameters:
  recipe - The additional data to be put into EPR.

JAX-WS RI assigns an unique EPR to the exported object, and from now on, messages that are sent to this EPR will be routed to the given object.

The object will be locked in memory, so be sure to StatefulWebServiceManager.unexport(Object) unexport it when it's no longer needed.

Notice that the obtained EPR contains the address of the service, which depends on the currently processed request.

This method works like StatefulWebServiceManager.export(Class,Object) but it takes an extra WebServiceContext that represents the request currently being processed by the caller (the JAX-WS RI remembers this when the service processing is synchronous, and that's why this parameter is only needed for asynchronous web services.)

Why WebServiceContext is needed?

The obtained EPR contains address, such as host name.

This method is not meant for application code. This is for Tube s that wish to use stateful web service support.
Parameters:
  currentRequest - The request that we are currently processing.

When the incoming request does not have the necessary header to distinguish instances of T, or when the header is present but its value does not correspond with any of the active exported instances known to the JAX-WS, then the JAX-WS RI will try to route the request to the fallback instance.

This provides the application an opportunity to perform application specific error recovery.

If no fallback instance is provided, then the JAX-WS RI will send back the fault.

When configured, the JAX-WS RI will internally use a timer so that exported objects that have not received any request for the given amount of minutes will be automatically unexported.

At some point after the time out has occurred for an instance, the JAX-WS RI will invoke the Callback to notify the application that the time out has reached.

This method works like StatefulWebServiceManager.export(Object) except that you can obtain the EPR in your choice of addressing version, by passing in the suitable epr parameter.
Parameters:
  epr - Either W3CEndpointReference or MemberSubmissionEndpointReference.If other types are specified, this method throws an WebServiceException.EndpointReference-subclass that identifies this exportedobject.

This method works like StatefulWebServiceManager.export(Object) except that you can obtain the EPR in your choice of addressing version, by passing in the suitable epr parameter.
Parameters:
  epr - Either W3CEndpointReference or MemberSubmissionEndpointReference.If other types are specified, this method throws an WebServiceException.
Parameters:
  o - The object to be exported, whose identity be referenced by the returned EPR.
Parameters:
  recipe - The additional data to be put into EPR. Can be null.EndpointReference-subclass that identifies this exportedobject.
since:
   2.1.1

JAX-WS RI assigns an unique EPR to the exported object, and from now on, messages that are sent to this EPR will be routed to the given object.

The object will be locked in memory, so be sure to StatefulWebServiceManager.unexport(Object) unexport it when it's no longer needed.

Notice that the obtained EPR contains the address of the service, which depends on the currently processed request. So invoking this method multiple times with the same object may return different EPRs, if such multiple invocations are done while servicing different requests. (Of course all such EPRs point to the same object, so messages sent to those EPRs will be served by the same instance.) W3CEndpointReference that identifies this exportedobject. Always non-null.

This method works like StatefulWebServiceManager.export(Class,Object) but it takes an extra WebServiceContext that represents the request currently being processed by the caller (the JAX-WS RI remembers this when the service processing is synchronous, and that's why this parameter is only needed for asynchronous web services.)

Why WebServiceContext is needed?

The obtained EPR contains address, such as host name. The server does not know what its own host name is (or there are more than one of them), so this value is determined by what the current client thinks the server name is. This is why we need to take WebServiceContext . Pass in the object given to AsyncProvider.invoke(ObjectAsyncProviderCallbackWebServiceContext) .

This method is not meant for application code. This is for Tube s that wish to use stateful web service support.
Parameters:
  currentRequest - The request that we are currently processing. This is used to infer the address in EPR.
See Also:   StatefulWebServiceManager.export(Class,WebServiceContext,Object)

This method can be used to have two endpoints in the same application communicate locally. null if the EPR is not exported from this manager.

When the incoming request does not have the necessary header to distinguish instances of T, or when the header is present but its value does not correspond with any of the active exported instances known to the JAX-WS, then the JAX-WS RI will try to route the request to the fallback instance.

This provides the application an opportunity to perform application specific error recovery.

If no fallback instance is provided, then the JAX-WS RI will send back the fault. By default, no fallback instance is set.

This method can be invoked any time, but most often you'd like to use one instance at the get-go. The following code example illustrates how to do this:

 @
WebService class BankAccount {
 ... continuting from the example in class javadoc ...
 @
Resource  static void setManager(
StatefulWebServiceManager  manager) {
 manager.setFallbackInstance(new BankAccount(0) {
 @
Override void deposit(int amount) {
 putToAuditRecord(id);
 if(thisLooksBad())   callPolice();
 throw new 
WebServiceException ("No such bank account exists");
 }
 });
 }
 }
 

When configured, the JAX-WS RI will internally use a timer so that exported objects that have not received any request for the given amount of minutes will be automatically unexported.

At some point after the time out has occurred for an instance, the JAX-WS RI will invoke the Callback to notify the application that the time out has reached. Application then has a choice of either let the object go unexported, or StatefulWebServiceManager.touch(Object) touch let the object live for another round of timer interval.

If no callback is set, the expired object will automatically unexported.

When you call this method multiple times, its effect on existing instances are unspecified, although deterministic.
Parameters:
  milliseconds - The time out interval. Specify 0 to cancel the timeout timer.Note that this only guarantees that time out does not occurat least until this amount of time has elapsed. It does notguarantee that the time out will always happen right afterthe timeout is reached.
Parameters:
  callback - application may choose to install a callback to control thetimeout behavior.

If the object is null, not exported, or already unexported, this method will be no-op.

JAX-WS will release a strong reference to unexported objects, and they will never receive further requests (requests targeted for those unexported objects will be served by the fallback object.)
Parameters:
  o - if null, this method will be no-op.