Package com.sun.xml.ws.api.server

Class WSEndpoint<T>

java.lang.Object
com.sun.xml.ws.api.server.WSEndpoint<T>
All Implemented Interfaces:
Component, ComponentRegistry
Direct Known Subclasses:
ManagedEndpoint, WSEndpointImpl, WSEndpointMOMProxy
public abstract class WSEndpoint<T> extends Object implements ComponentRegistry
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).

Author:
Kohsuke Kawaguchi

  • Constructor Details

    • WSEndpoint

      protected WSEndpoint()
      Default constructor.

  • Method Details

    • 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<T>, 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<? extends com.sun.xml.ws.api.server.SDDocumentSource>, 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:

    • 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:

    • process

      public void process(@NotNull Packet request, @NotNull WSEndpoint.CompletionCallback callback, @Nullable FiberContextSwitchInterceptor interceptor)

    • getEngine

      public Engine getEngine()
      Returns Engine for this endpoint
      Returns:
      Engine

    • 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, always the same value under ordinary circumstances but may change if the endpoint is managed.

    • getBoundEndpoints

      public List<BoundEndpoint> getBoundEndpoints()
      Gets the list of BoundEndpoint that are associated with this endpoint.
      Returns:
      always return the same set.

    • getComponents

      @NotNull public Set<Component> getComponents()
      Gets the list of Components 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 Component.getSPI(Class) to establish a private contract between components.

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

      Specified by:
      getComponents in interface ComponentRegistry
      Returns:
      always return the same set.

    • getSPI

      @Nullable public <S> S getSPI(@NotNull Class<S> spiType)
      Description copied from interface: Component
      Gets the specified SPI.

      This method works as a kind of directory service for SPIs, allowing various components to define private contract and talk to each other.

      Specified by:
      getSPI in interface Component
      Returns:
      null if such an SPI is not provided by this object.

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

    • getPolicyMap

      @Deprecated public abstract PolicyMap getPolicyMap()
      Deprecated.
      Do not use this method as the PolicyMap API is not final yet and might change in next few months.
      Gives the PolicMap that captures the Policy for the endpoint
      Returns:
      PolicyMap

    • getManagedObjectManager

      @NotNull public abstract org.glassfish.gmbal.ManagedObjectManager getManagedObjectManager()
      Get the ManagedObjectManager for this endpoint.

    • closeManagedObjectManager

      public abstract void closeManagedObjectManager()
      Close the ManagedObjectManager for this endpoint. This is used by the Web Service Configuration Management system so that it closes the MOM before it creates a new WSEndpoint. Then it calls dispose on the existing endpoint and then installs the new endpoint. The call to dispose also calls closeManagedObjectManager, but is a noop if that method has already been called.

    • getAssemblerContext

      @NotNull public abstract ServerTubeAssemblerContext getAssemblerContext()
      This is only needed to expose info for monitoring.

    • 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<T>, 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:
      WebServiceException - if the endpoint set up fails.

    • 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, boolean isStandard)

    • 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)
      Takes an url of the jax-ws-catalog.xml. Assumes isTransportSynchronous==false
      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

    • getDefaultServiceName

      @NotNull public static QName getDefaultServiceName(Class endpointClass, MetadataReader metadataReader)

    • getDefaultServiceName

      @NotNull public static QName getDefaultServiceName(Class endpointClass, boolean isStandard)

    • getDefaultServiceName

      @NotNull public static QName getDefaultServiceName(Class endpointClass, boolean isStandard, MetadataReader metadataReader)

    • 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

    • getDefaultPortName

      @NotNull public static QName getDefaultPortName(@NotNull QName serviceName, Class endpointClass, MetadataReader metadataReader)

    • getDefaultPortName

      @NotNull public static QName getDefaultPortName(@NotNull QName serviceName, Class endpointClass, boolean isStandard)

    • getDefaultPortName

      @NotNull public static QName getDefaultPortName(@NotNull QName serviceName, Class endpointClass, boolean isStandard, MetadataReader metadataReader)

    • getEndpointReference

      public abstract <T extends EndpointReference> T getEndpointReference(Class<T> clazz, String address, String wsdlAddress, Element... referenceParameters)
      Return EndpointReference instance, based on passed parameters and spec version represented by clazz
      Parameters:
      clazz - represents spec version
      address - endpoint address
      wsdlAddress - wsdl address
      referenceParameters - any reference parameters to be added to the instance
      Returns:
      EndpointReference instance based on passed parameters and values obtained from current instance

    • getEndpointReference

      public abstract <T extends EndpointReference> T getEndpointReference(Class<T> clazz, String address, String wsdlAddress, List<Element> metadata, List<Element> referenceParameters)
      Returns:
      EndpointReference instance based on passed parameters and values obtained from current instance

    • equalsProxiedInstance

      public boolean equalsProxiedInstance(WSEndpoint<?> endpoint)
      Used for managed endpoints infrastructure to compare equality of proxies vs proxied endpoints.
      Returns:
      true if the proxied endpoint instance held by this instance equals to 'endpoint', otherwise return false.

    • getOperationDispatcher

      @Nullable public abstract OperationDispatcher getOperationDispatcher()
      Nullable when there is no associated WSDL Model

    • createServiceResponseForException

      public abstract Packet createServiceResponseForException(ThrowableContainerPropertySet tc, Packet responsePacket, SOAPVersion soapVersion, WSDLPort wsdlPort, SEIModel seiModel, WSBinding binding)
      This is used by WsaServerTube and WSEndpointImpl to create a Packet with SOAPFault message from a Java exception.