com.sun.xml.ws.api.server
Class WSEndpoint<T>

java.lang.Object
  extended by com.sun.xml.ws.api.server.WSEndpoint<T>
Direct Known Subclasses:
WSEndpointImpl

public abstract class WSEndpoint<T>
extends Object

Root object that hosts the Packet processing code at the server.

One instance of WSEndpoint is created for each deployed service endpoint. A hosted service usually handles multiple concurrent requests. To do this efficiently, an endpoint handles incoming Packet through WSEndpoint.PipeHeads, where many copies can be created for each endpoint.

Each WSEndpoint.PipeHead is thread-unsafe, and request needs to be serialized. A WSEndpoint.PipeHead represents a sizable resource (in particular a whole pipeline), so the caller is expected to reuse them and avoid excessive allocations as much as possible. Making WSEndpoint.PipeHeads thread-unsafe allow the JAX-WS RI internal to tie thread-local resources to WSEndpoint.PipeHead, and reduce the total resource management overhead.

To abbreviate this resource management (and for a few other reasons), JAX-WS RI provides Adapter class. If you are hosting a JAX-WS service, you'll most likely want to send requests to WSEndpoint through Adapter.

WSEndpoint is ready to handle Packets as soon as it's created. No separate post-initialization step is necessary. However, to comply with the JAX-WS spec requirement, the caller is expected to call the dispose() method to allow an orderly shut-down of a hosted service.

Objects Exposed From Endpoint

WSEndpoint exposes a series of information that represents how an endpoint is configured to host a service. See the getXXX methods for more details.

Implementation Notes

WSEndpoint owns a WSWebServiceContext implementation. But a bulk of the work is delegated to WebServiceContextDelegate, which is passed in as a parameter to WSEndpoint.PipeHead.process(Packet, WebServiceContextDelegate, TransportBackChannel).


Nested Class Summary
static interface WSEndpoint.CompletionCallback
          Callback to notify that jax-ws runtime has finished execution of a request submitted via schedule().
static interface WSEndpoint.PipeHead
          Represents a resource local to a thread.
 
Constructor Summary
WSEndpoint()
           
 
Method Summary
static
<T> WSEndpoint<T>
create(Class<T> implType, boolean processHandlerAnnotation, Invoker invoker, QName serviceName, QName portName, Container container, WSBinding binding, SDDocumentSource primaryWsdl, Collection<? extends SDDocumentSource> metadata, EntityResolver resolver)
          Deprecated. 
static
<T> WSEndpoint<T>
create(Class<T> implType, boolean processHandlerAnnotation, Invoker invoker, QName serviceName, QName portName, Container container, WSBinding binding, SDDocumentSource primaryWsdl, Collection<? extends SDDocumentSource> metadata, EntityResolver resolver, boolean isTransportSynchronous)
          Creates an endpoint from deployment or programmatic configuration
static
<T> WSEndpoint<T>
create(Class<T> implType, boolean processHandlerAnnotation, Invoker invoker, QName serviceName, QName portName, Container container, WSBinding binding, SDDocumentSource primaryWsdl, Collection<? extends SDDocumentSource> metadata, URL catalogUrl)
          The same as create(Class, boolean, Invoker, QName, QName, Container, WSBinding, SDDocumentSource, Collection, EntityResolver) except that this version takes an url of the jax-ws-catalog.xml.
abstract  Codec createCodec()
          Gets the Endpoint's codec that is used to encode/decode Messages.
abstract  WSEndpoint.PipeHead createPipeHead()
          Creates a new WSEndpoint.PipeHead to process incoming requests.
abstract  void dispose()
          Indicates that the WSEndpoint is about to be turned off, and will no longer serve any packet anymore.
abstract  WSBinding getBinding()
          Represents the binding for which this WSEndpoint is created for.
abstract  Set<EndpointComponent> getComponentRegistry()
          Gets the list of EndpointComponent that are associated with this endpoint.
abstract  Container getContainer()
          Gets the Container object.
static QName getDefaultPortName(QName serviceName, Class endpointClass)
          Gives the wsdl:service/wsdl:port default name computed from the endpoint implementaiton class
static QName getDefaultServiceName(Class endpointClass)
          Gives the wsdl:service default name computed from the endpoint implementaiton class
abstract  Class<T> getImplementationClass()
          Gets the application endpoint Class that eventually serves the request.
abstract  WSDLPort getPort()
          Gets the port that this endpoint is serving.
abstract  QName getPortName()
          Gets the application endpoint's portName.
abstract  SEIModel getSEIModel()
          Gets the SEIModel that represents the relationship between WSDL and Java SEI.
abstract  ServiceDefinition getServiceDefinition()
          Gets the description of the service.
abstract  QName getServiceName()
          Gets the application endpoint's serviceName.
 void schedule(Packet request, WSEndpoint.CompletionCallback callback)
          This method takes a Packet that represents a request, run it through a Tubeline, eventually pass it to the user implementation code, which produces a reply, then run that through the tubeline again, and eventually return it as a return value through WSEndpoint.CompletionCallback.
abstract  void schedule(Packet request, WSEndpoint.CompletionCallback callback, FiberContextSwitchInterceptor interceptor)
          Schedule invocation of web service asynchronously.
abstract  void setExecutor(Executor exec)
          Set this Executor to run asynchronous requests using this executor.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

WSEndpoint

public WSEndpoint()
Method Detail

createCodec

@NotNull
public abstract Codec createCodec()
Gets the Endpoint's codec that is used to encode/decode Messages. This is a copy of the master codec and it shouldn't be shared across two requests running concurrently(unless it is stateless).

Returns:
codec to encode/decode

getServiceName

@NotNull
public abstract QName getServiceName()
Gets the application endpoint's serviceName. It could be got from DD or annotations

Returns:
same as wsdl:service QName if WSDL exists or generated

getPortName

@NotNull
public abstract QName getPortName()
Gets the application endpoint's portName. It could be got from DD or annotations

Returns:
same as wsdl:port QName if WSDL exists or generated

getImplementationClass

@NotNull
public abstract Class<T> getImplementationClass()
Gets the application endpoint Class that eventually serves the request.

This is the same value given to the create(java.lang.Class, boolean, com.sun.xml.ws.api.server.Invoker, javax.xml.namespace.QName, javax.xml.namespace.QName, com.sun.xml.ws.api.server.Container, com.sun.xml.ws.api.WSBinding, com.sun.xml.ws.api.server.SDDocumentSource, java.util.Collection, org.xml.sax.EntityResolver, boolean) method.


getBinding

@NotNull
public abstract WSBinding getBinding()
Represents the binding for which this WSEndpoint is created for.

Returns:
always same object.

getContainer

@NotNull
public abstract Container getContainer()
Gets the Container object.

The components inside WSEndpoint uses this reference to communicate with the hosting environment.

Returns:
always same object. If no "real" Container instance is given, Container.NONE will be returned.

getPort

@Nullable
public abstract WSDLPort getPort()
Gets the port that this endpoint is serving.

A service is not required to have a WSDL, and when it doesn't, this method returns null. Otherwise it returns an object that describes the port that this WSEndpoint is serving.

Returns:
Possibly null, but always the same value.

setExecutor

public abstract void setExecutor(@NotNull
                                 Executor exec)
Set this Executor to run asynchronous requests using this executor. This executor is set on Engine and must be set before calling schedule(Packet,CompletionCallback) and schedule(Packet,CompletionCallback,FiberContextSwitchInterceptor) methods.

Parameters:
exec - Executor to run async requests

schedule

public final void schedule(@NotNull
                           Packet request,
                           @NotNull
                           WSEndpoint.CompletionCallback callback)
This method takes a Packet that represents a request, run it through a Tubeline, eventually pass it to the user implementation code, which produces a reply, then run that through the tubeline again, and eventually return it as a return value through WSEndpoint.CompletionCallback.

This takes care of pooling of Tubelines and reuses tubeline for requests. Same instance of tubeline is not used concurrently for two requests.

If the transport is capable of asynchronous execution, use this instead of using WSEndpoint.PipeHead.process(com.sun.xml.ws.api.message.Packet, com.sun.xml.ws.api.server.WebServiceContextDelegate, com.sun.xml.ws.api.server.TransportBackChannel).

Before calling this method, set the executor using setExecutor(java.util.concurrent.Executor). The executor may used multiple times to run this request in a asynchronous fashion. The calling thread will be returned immediately, and the callback will be called in a different a thread.

Packet.transportBackChannel should have the correct value, so that one-way message processing happens correctly. Packet.webServiceContextDelegate should have the correct value, so that some WebServiceContext methods correctly.

Parameters:
request - web service request
callback - callback to get response packet
See Also:
Packet#transportBackChannel}, Packet#webServiceContextDelegate}

schedule

public abstract void schedule(@NotNull
                              Packet request,
                              @NotNull
                              WSEndpoint.CompletionCallback callback,
                              @Nullable
                              FiberContextSwitchInterceptor interceptor)
Schedule invocation of web service asynchronously.

Parameters:
request - web service request
callback - callback to get response packet(exception if there is one)
interceptor - caller's interceptor to impose a context of execution
See Also:
#schedule(Packet, CompletionCallback)}

createPipeHead

@NotNull
public abstract WSEndpoint.PipeHead createPipeHead()
Creates a new WSEndpoint.PipeHead to process incoming requests.

This is not a cheap operation. The caller is expected to reuse the returned WSEndpoint.PipeHead. See class javadoc for details.

Returns:
A newly created WSEndpoint.PipeHead that's ready to serve.

dispose

public abstract void dispose()
Indicates that the WSEndpoint is about to be turned off, and will no longer serve any packet anymore.

This method needs to be invoked for the JAX-WS RI to correctly implement some of the spec semantics (TODO: pointer.) It's the responsibility of the code that hosts a WSEndpoint to invoke this method.

Once this method is called, the behavior is undefed for all in-progress WSEndpoint.PipeHead.process(com.sun.xml.ws.api.message.Packet, com.sun.xml.ws.api.server.WebServiceContextDelegate, com.sun.xml.ws.api.server.TransportBackChannel) methods (by other threads) and future WSEndpoint.PipeHead.process(com.sun.xml.ws.api.message.Packet, com.sun.xml.ws.api.server.WebServiceContextDelegate, com.sun.xml.ws.api.server.TransportBackChannel) method invocations.


getServiceDefinition

@Nullable
public abstract ServiceDefinition getServiceDefinition()
Gets the description of the service.

A description is a set of WSDL/schema and other documents that together describes a service. A service is not required to have a description, and when it doesn't, this method returns null.

Returns:
Possibly null, but always the same value.

getComponentRegistry

@NotNull
public abstract Set<EndpointComponent> getComponentRegistry()
Gets the list of EndpointComponent that are associated with this endpoint.

Components (such as codec, tube, handler, etc) who wish to provide some service to other components in the endpoint can iterate the registry and call its EndpointComponent.getSPI(Class) to establish a private contract between components.

Components who wish to subscribe to such a service can add itself to this set.

Returns:
always return the same set.

getSEIModel

@Nullable
public abstract SEIModel getSEIModel()
Gets the SEIModel that represents the relationship between WSDL and Java SEI.

This method returns a non-null value if and only if this endpoint is ultimately serving an application through an SEI.

Returns:
maybe null. See above for more discussion. Always the same value.

create

public static <T> WSEndpoint<T> create(@NotNull
                                       Class<T> implType,
                                       boolean processHandlerAnnotation,
                                       @Nullable
                                       Invoker invoker,
                                       @Nullable
                                       QName serviceName,
                                       @Nullable
                                       QName portName,
                                       @Nullable
                                       Container container,
                                       @Nullable
                                       WSBinding binding,
                                       @Nullable
                                       SDDocumentSource primaryWsdl,
                                       @Nullable
                                       Collection<? extends SDDocumentSource> metadata,
                                       @Nullable
                                       EntityResolver resolver,
                                       boolean isTransportSynchronous)
Creates an endpoint from deployment or programmatic configuration

This method works like the following:

  1. ServiceDefinition is modeleed from the given SEI type.
  2. Invoker that always serves implementationObject will be used.

Parameters:
implType - Endpoint class(not SEI). Enpoint class must have @WebService or @WebServiceProvider annotation.
processHandlerAnnotation - Flag to control processing of @HandlerChain on Impl class if true, processes @HandlerChain on Impl if false, DD might have set HandlerChain no need to parse.
invoker - Pass an object to invoke the actual endpoint object. If it is null, a default invoker is created using InstanceResolver.createDefault(java.lang.Class, boolean). Appservers could create its own invoker to do additional functions like transactions, invoking the endpoint through proxy etc.
serviceName - Optional service name(may be from DD) to override the one given by the implementation class. If it is null, it will be derived from annotations.
portName - Optional port name(may be from DD) to override the one given by the implementation class. If it is null, it will be derived from annotations.
container - Allows technologies that are built on top of JAX-WS(such as WSIT) needs to negotiate private contracts between them and the container
binding - JAX-WS implementation of Binding. This object can be created by BindingID.createBinding(). Usually the binding can be got from DD, BindingType. TODO: DD has a configuration for MTOM threshold. Maybe we need something more generic so that other technologies like Tango can get information from DD. TODO: does it really make sense for this to take EntityResolver? Given that all metadata has to be given as a list anyway.
primaryWsdl - The primary WSDL. If null, it'll be generated based on the SEI (if this is an SEI) or no WSDL is associated (if it's a provider.) TODO: shouldn't the implementation find this from the metadata list?
metadata - Other documents that become SDDocuments. Can be null.
resolver - Optional resolver used to de-reference resources referenced from WSDL. Must be null if the url is null.
isTransportSynchronous - If the caller knows that the returned WSEndpoint is going to be used by a synchronous-only transport, then it may pass in true to allow the callee to perform an optimization based on that knowledge (since often synchronous version is cheaper than an asynchronous version.) This value is visible from ServerTubeAssemblerContext.isSynchronous().
Returns:
newly constructed WSEndpoint.
Throws:
javax.xml.ws.WebServiceException - if the endpoint set up fails.

create

@Deprecated
public static <T> WSEndpoint<T> create(@NotNull
                                                  Class<T> implType,
                                                  boolean processHandlerAnnotation,
                                                  @Nullable
                                                  Invoker invoker,
                                                  @Nullable
                                                  QName serviceName,
                                                  @Nullable
                                                  QName portName,
                                                  @Nullable
                                                  Container container,
                                                  @Nullable
                                                  WSBinding binding,
                                                  @Nullable
                                                  SDDocumentSource primaryWsdl,
                                                  @Nullable
                                                  Collection<? extends SDDocumentSource> metadata,
                                                  @Nullable
                                                  EntityResolver resolver)
Deprecated. 

Deprecated version that assumes isTransportSynchronous==false


create

public static <T> WSEndpoint<T> create(@NotNull
                                       Class<T> implType,
                                       boolean processHandlerAnnotation,
                                       @Nullable
                                       Invoker invoker,
                                       @Nullable
                                       QName serviceName,
                                       @Nullable
                                       QName portName,
                                       @Nullable
                                       Container container,
                                       @Nullable
                                       WSBinding binding,
                                       @Nullable
                                       SDDocumentSource primaryWsdl,
                                       @Nullable
                                       Collection<? extends SDDocumentSource> metadata,
                                       @Nullable
                                       URL catalogUrl)
The same as create(Class, boolean, Invoker, QName, QName, Container, WSBinding, SDDocumentSource, Collection, EntityResolver) except that this version takes an url of the jax-ws-catalog.xml.

Parameters:
catalogUrl - if not null, an EntityResolver is created from it and used. otherwise no resolution will be performed.

getDefaultServiceName

@NotNull
public static QName getDefaultServiceName(Class endpointClass)
Gives the wsdl:service default name computed from the endpoint implementaiton class


getDefaultPortName

@NotNull
public static QName getDefaultPortName(@NotNull
                                               QName serviceName,
                                               Class endpointClass)
Gives the wsdl:service/wsdl:port default name computed from the endpoint implementaiton class