Module com.sun.xml.ws.jaxws

Package com.sun.xml.ws.server

Class StatefulInstanceResolver<T>

java.lang.Object

com.sun.xml.ws.api.server.InstanceResolver<T>

com.sun.xml.ws.api.server.AbstractInstanceResolver<T>

com.sun.xml.ws.server.AbstractMultiInstanceResolver<T>

com.sun.xml.ws.server.StatefulInstanceResolver<T>

All Implemented Interfaces:

StatefulWebServiceManager<T>

public final class StatefulInstanceResolver<T>
extends AbstractMultiInstanceResolver<T>
implements StatefulWebServiceManager<T>

InstanceResolver that looks at JAX-WS cookie header to determine the instance to which a message will be routed.

See StatefulWebServiceManager for more about user-level semantics.

Author:

Kohsuke Kawaguchi, Jitendra Kotamraju (added high availability)

Nested Class Summary

Nested classes/interfaces inherited from interface com.sun.xml.ws.developer.StatefulWebServiceManager

StatefulWebServiceManager.Callback<T>

Field Summary

Fields inherited from class com.sun.xml.ws.server.AbstractMultiInstanceResolver

clazz, owner

Constructor Summary

Constructors

Constructor	Description
StatefulInstanceResolver(Class<T> clazz)

Method Summary

Modifier and Type	Method	Description
void	dispose()	Called by WSEndpoint when WSEndpoint.dispose() is called.
<EPR extends EndpointReference> EPR	export(Class<EPR> adrsVer, Packet currentRequest, T o)	Exports an object.
<EPR extends EndpointReference> EPR	export(Class<EPR> adrsVer, Packet currentRequest, T o, EPRRecipe recipe)	The same as StatefulWebServiceManager.export(Class, Packet, Object) except that it takes EPRRecipe.
<EPR extends EndpointReference> EPR	export(Class<EPR> adrsVer, String endpointAddress, String wsdlAddress, T o, EPRRecipe recipe)
<EPR extends EndpointReference> EPR	export(Class<EPR> adrsVer, String endpointAddress, T o)	Exports an object.
<EPR extends EndpointReference> EPR	export(Class<EPR> epr, WebServiceContext context, T o)	Exports an object (for asynchronous web services.)
<EPR extends EndpointReference> EPR	export(Class<EPR> epr, T o)	Exports an object.
<EPR extends EndpointReference> EPR	export(Class<EPR> epr, T o, EPRRecipe recipe)	Exports an object.
W3CEndpointReference	export(T o)	Exports an object.
void	postInvoke(Packet request, T servant)	Called by the default Invoker after the method call is done.
T	resolve(Packet request)	Decides which instance of 'T' serves the given request message.
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	start(WSWebServiceContext wsc, WSEndpoint endpoint)	Called by WSEndpoint when it's set up.
void	touch(T o)	Resets the time out timer for the given instance.
void	unexport(T o)	Unexports the given instance.

Methods inherited from class com.sun.xml.ws.server.AbstractMultiInstanceResolver

create, dispose, prepare

Methods inherited from class com.sun.xml.ws.api.server.AbstractInstanceResolver

findAnnotatedMethod, getResourceInjector, invokeMethod

Methods inherited from class com.sun.xml.ws.api.server.InstanceResolver

createDefault, createDefault, createFromInstanceResolverAnnotation, createInvoker, createNewInstance, createSingleton, start

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

StatefulInstanceResolver

public StatefulInstanceResolver(Class<T> clazz)

Method Detail

resolve

@NotNull
public T resolve(Packet request)

Description copied from class: InstanceResolver

Decides which instance of 'T' serves the given request message.

This method is called concurrently by multiple threads. It is also on a criticail path that affects the performance. A good implementation should try to avoid any synchronization, and should minimize the amount of work as much as possible.

Specified by:

resolve in class InstanceResolver<T>

Parameters:

request - Always non-null. Represents the request message to be served. The caller may not consume the Message.

postInvoke

public void postInvoke(@NotNull
                       Packet request,
                       @NotNull
                       T servant)

Description copied from class: InstanceResolver

Called by the default Invoker after the method call is done. This gives InstanceResolver a chance to do clean up.

Alternatively, one could override InstanceResolver.createInvoker() to create a custom invoker to do this in more flexible way.

The default implementation is a no-op.

Overrides:

postInvoke in class InstanceResolver<T>

Parameters:

request - The same request packet given to InstanceResolver.resolve(Packet) method.

servant - The object returned from the InstanceResolver.resolve(Packet) method.

start

public void start(WSWebServiceContext wsc,
                  WSEndpoint endpoint)

Description copied from class: InstanceResolver

Called by WSEndpoint when it's set up.

This is an opportunity for InstanceResolver to do a endpoint-specific initialization process.

Overrides:

start in class AbstractMultiInstanceResolver<T>

Parameters:

wsc - The WebServiceContext instance to be injected to the user instances (assuming InstanceResolver

dispose

public void dispose()

Description copied from class: InstanceResolver

Called by WSEndpoint when WSEndpoint.dispose() is called. This allows InstanceResolver to do final clean up.

This method is guaranteed to be only called once by WSEndpoint.

Overrides:

dispose in class InstanceResolver<T>

export

@NotNull
public W3CEndpointReference export(T o)

Description copied from interface: StatefulWebServiceManager

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

Specified by:

export in interface StatefulWebServiceManager<T>

Returns:

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

export

@NotNull
public <EPR extends EndpointReference> EPR export(Class<EPR> epr,
                                                  T o)

Description copied from interface: StatefulWebServiceManager

Exports an object.

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.

Specified by:

export in interface StatefulWebServiceManager<T>

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

public <EPR extends EndpointReference> EPR export(Class<EPR> epr,
                                                  T o,
                                                  EPRRecipe recipe)

Description copied from interface: StatefulWebServiceManager

Exports an object.

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.

Specified by:

export in interface StatefulWebServiceManager<T>

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.

export

@NotNull
public <EPR extends EndpointReference> EPR export(Class<EPR> epr,
                                                  WebServiceContext context,
                                                  T o)

Description copied from interface: StatefulWebServiceManager

Exports an object (for asynchronous web services.)

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(Object, AsyncProviderCallback,WebServiceContext).

Specified by:

export in interface StatefulWebServiceManager<T>

export

@NotNull
public <EPR extends EndpointReference> EPR export(Class<EPR> adrsVer,
                                                  @NotNull
                                                  Packet currentRequest,
                                                  T o)

Description copied from interface: StatefulWebServiceManager

Exports an object.

This method is not meant for application code. This is for Tubes that wish to use stateful web service support.

Specified by:

export in interface StatefulWebServiceManager<T>

currentRequest - The request that we are currently processing. This is used to infer the address in EPR.

See Also:

StatefulWebServiceManager.export(Class, WebServiceContext, Object)

export

public <EPR extends EndpointReference> EPR export(Class<EPR> adrsVer,
                                                  @NotNull
                                                  Packet currentRequest,
                                                  T o,
                                                  EPRRecipe recipe)

Description copied from interface: StatefulWebServiceManager

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

Specified by:

export in interface StatefulWebServiceManager<T>

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

export

@NotNull
public <EPR extends EndpointReference> EPR export(Class<EPR> adrsVer,
                                                  String endpointAddress,
                                                  T o)

Description copied from interface: StatefulWebServiceManager

Exports an object.

Specified by:

export in interface StatefulWebServiceManager<T>

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

export

@NotNull
public <EPR extends EndpointReference> EPR export(Class<EPR> adrsVer,
                                                  String endpointAddress,
                                                  String wsdlAddress,
                                                  T o,
                                                  EPRRecipe recipe)

unexport

public void unexport(@Nullable
                     T o)

Description copied from interface: StatefulWebServiceManager

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

Specified by:

unexport in interface StatefulWebServiceManager<T>

Parameters:

o - if null, this method will be no-op.

resolve

public T resolve(EndpointReference epr)

Description copied from interface: StatefulWebServiceManager

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.

Specified by:

resolve in interface StatefulWebServiceManager<T>

Returns:

null if the EPR is not exported from this manager.

setFallbackInstance

public void setFallbackInstance(T o)

Description copied from interface: StatefulWebServiceManager

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

Specified by:

setFallbackInstance in interface StatefulWebServiceManager<T>

Parameters:

o - Can be null.

setTimeout

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

Description copied from interface: StatefulWebServiceManager

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.

Specified by:

setTimeout in interface StatefulWebServiceManager<T>

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

public void touch(T o)

Description copied from interface: StatefulWebServiceManager

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.

Specified by:

touch in interface StatefulWebServiceManager<T>