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 takesStatefulWebServiceManager
.@
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 staticStatefulWebServiceManager
<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 usingsetTimeout(long, Callback)
.StatefulWebServiceManager
is thread-safe. It can be safely invoked from multiple threads concurrently.- Since:
- 2.1
- Author:
- Kohsuke Kawaguchi
- See Also:
StatefulFeature
-
-
Nested Class Summary
Nested Classes Modifier and Type Interface Description static interface
StatefulWebServiceManager.Callback<T>
Used bysetTimeout(long, Callback)
to determine what to do when the time out is reached.
-
Method Summary
All Methods Instance Methods Abstract Methods Deprecated Methods Modifier and Type Method Description <EPR extends jakarta.xml.ws.EndpointReference>
EPRexport(Class<EPR> eprType, Packet currentRequest, T o)
Exports an object.<EPR extends jakarta.xml.ws.EndpointReference>
EPRexport(Class<EPR> eprType, Packet currentRequest, T o, EPRRecipe recipe)
The same asexport(Class, Packet, Object)
except that it takesEPRRecipe
.<EPR extends jakarta.xml.ws.EndpointReference>
EPRexport(Class<EPR> eprType, jakarta.xml.ws.WebServiceContext context, T o)
Exports an object (forasynchronous web services
.)<EPR extends jakarta.xml.ws.EndpointReference>
EPRexport(Class<EPR> eprType, String endpointAddress, T o)
Deprecated.This method is provided as a temporary workaround, and we'll eventually try to remove it.<EPR extends jakarta.xml.ws.EndpointReference>
EPRexport(Class<EPR> epr, T o)
Exports an object.<EPR extends jakarta.xml.ws.EndpointReference>
EPRexport(Class<EPR> epr, T o, EPRRecipe recipe)
Exports an object.jakarta.xml.ws.wsaddressing.W3CEndpointReference
export(T o)
Exports an object.T
resolve(jakarta.xml.ws.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 jakarta.xml.ws.EndpointReference> EPR export(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 suitableepr
parameter.- Parameters:
epr
- EitherW3CEndpointReference
orMemberSubmissionEndpointReference
. If other types are specified, this method throws anWebServiceException
.- Returns:
EndpointReference
-subclass that identifies this exported object.
-
export
@NotNull <EPR extends jakarta.xml.ws.EndpointReference> EPR export(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 suitableepr
parameter.- Parameters:
epr
- EitherW3CEndpointReference
orMemberSubmissionEndpointReference
. If other types are specified, this method throws anWebServiceException
.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 jakarta.xml.ws.wsaddressing.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 jakarta.xml.ws.EndpointReference> EPR export(Class<EPR> eprType, @NotNull jakarta.xml.ws.WebServiceContext context, T o)
Exports an object (forasynchronous web services
.)This method works like
export(Class,Object)
but it takes an extraWebServiceContext
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 toAsyncProvider.invoke(Object, AsyncProviderCallback,WebServiceContext)
.
-
export
@NotNull <EPR extends jakarta.xml.ws.EndpointReference> EPR export(Class<EPR> eprType, @NotNull Packet currentRequest, T o)
Exports an object.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:
export(Class, WebServiceContext, Object)
-
export
@NotNull <EPR extends jakarta.xml.ws.EndpointReference> EPR export(Class<EPR> eprType, @NotNull Packet currentRequest, T o, EPRRecipe recipe)
The same asexport(Class, Packet, Object)
except that it takesEPRRecipe
.- Parameters:
recipe
- Seeexport(Class, Object, EPRRecipe)
.
-
export
@NotNull <EPR extends jakarta.xml.ws.EndpointReference> EPR export(Class<EPR> eprType, 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, likePacket
orWebServiceContext
.
-
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 jakarta.xml.ws.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 newWebServiceException
("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, ortouch
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.
-
-