com.sun.xml.ws.developer
Interface StatefulWebServiceManager<T>

All Known Implementing Classes:

StatefulInstanceResolver

public interface StatefulWebServiceManager<T>

Stateful web service support in the JAX-WS RI.

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.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 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 setTimeout(long, Callback).

StatefulWebServiceManager is thread-safe. It can be safely invoked from multiple threads concurrently.

Since:

2.1

See Also:

StatefulFeature

Nested Class Summary

static interface

StatefulWebServiceManager.Callback<T> Used by setTimeout(long, Callback) to determine what to do when the time out is reached.

Method Summary

<EPR extends EndpointReference> EPR	export(java.lang.Class<EPR> eprType, Packet currentRequest, T o) Exports an object.
<EPR extends EndpointReference> EPR	export(java.lang.Class<EPR> eprType, Packet currentRequest, T o, EPRRecipe recipe) The same as export(Class, Packet, Object) except that it takes EPRRecipe.
<EPR extends EndpointReference> EPR	export(java.lang.Class<EPR> eprType, java.lang.String endpointAddress, T o) Deprecated. This method is provided as a temporary workaround, and we'll eventually try to remove it.
<EPR extends EndpointReference> EPR	export(java.lang.Class<EPR> epr, T o) Exports an object.
<EPR extends EndpointReference> EPR	export(java.lang.Class<EPR> epr, T o, EPRRecipe recipe) Exports an object.
<EPR extends EndpointReference> EPR	export(java.lang.Class<EPR> eprType, WebServiceContext context, T o) Exports an object (for asynchronous web services.)
W3CEndpointReference	export(T o) Exports an object.
T	resolve(EndpointReference epr) Checks if the given EPR represents an object that has been exported from this manager.
void	setFallbackInstance(T o) Sets the "fallback" instance.
void	setTimeout(long milliseconds, StatefulWebServiceManager.Callback<T> callback) Configures timeout for exported instances.
void	touch(T o) Resets the time out timer for the given instance.
void	unexport(T o) Unexports the given instance.

Method Detail

export

@NotNull
<EPR extends EndpointReference> EPR export(java.lang.Class<EPR> epr,
                                                   T o)

Exports an object.

This method works like 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.

Returns:

EndpointReference-subclass that identifies this exported object.

export

@NotNull
<EPR extends EndpointReference> EPR export(java.lang.Class<EPR> epr,
                                                   T o,
                                                   @Nullable
                                                   EPRRecipe recipe)

Exports an object.

This method works like 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.

o - The object to be exported, whose identity be referenced by the returned EPR.

recipe - The additional data to be put into EPR. Can be null.

Returns:

EndpointReference-subclass that identifies this exported object.

Since:

2.1.1

export

@NotNull
W3CEndpointReference export(T o)

Exports an object.

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 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.)

Returns:

W3CEndpointReference that identifies this exported object. Always non-null.

export

@NotNull
<EPR extends EndpointReference> EPR export(java.lang.Class<EPR> eprType,
                                                   @NotNull
                                                   WebServiceContext context,
                                                   T o)

Exports an object (for asynchronous web services.)

This method works like 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(Object, AsyncProviderCallback,WebServiceContext).

export

@NotNull
<EPR extends EndpointReference> EPR export(java.lang.Class<EPR> eprType,
                                                   @NotNull
                                                   Packet currentRequest,
                                                   T o)

Exports an object.

This method is not meant for application code. This is for Tubes 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:

export(Class, WebServiceContext, Object)

export

@NotNull
<EPR extends EndpointReference> EPR export(java.lang.Class<EPR> eprType,
                                                   @NotNull
                                                   Packet currentRequest,
                                                   T o,
                                                   EPRRecipe recipe)

The same as export(Class, Packet, Object) except that it takes EPRRecipe.

Parameters:

recipe - See export(Class, Object, EPRRecipe).

export

@NotNull
<EPR extends EndpointReference> EPR export(java.lang.Class<EPR> eprType,
                                                   java.lang.String endpointAddress,
                                                   T o)

Deprecated. This method is provided as a temporary workaround, and we'll eventually try to remove it.

Exports an object.

Parameters:

endpointAddress - The endpoint address URL. Normally, this information is determined by other inputs, like Packet or WebServiceContext.

unexport

void unexport(@Nullable
              T o)

Unexports the given instance.

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.

resolve

@Nullable
T resolve(@NotNull
                   EndpointReference epr)

Checks if the given EPR represents an object that has been exported from this manager.

This method can be used to have two endpoints in the same application communicate locally.

Returns:

null if the EPR is not exported from this manager.

setFallbackInstance

void setFallbackInstance(T o)

Sets the "fallback" instance.

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");
            }
        });
     }
 }
 

Parameters:

o - Can be null.

setTimeout

void setTimeout(long milliseconds,
                @Nullable
                StatefulWebServiceManager.Callback<T> callback)

Configures timeout for exported instances.

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 StatefulWebServiceManager.Callback to notify the application that the time out has reached. Application then has a choice of either let the object go unexported, or 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 occur at least until this amount of time has elapsed. It does not guarantee that the time out will always happen right after the timeout is reached.

callback - application may choose to install a callback to control the timeout behavior.

touch

void touch(T o)

Resets the time out timer for the given instance.

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