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

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
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

Constructors

Constructor	Description
WSEndpoint()

Method Summary

Modifier and Type	Method	Description
abstract void	closeManagedObjectManager()	Close the ManagedObjectManager for this endpoint.
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.
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, EntityResolver resolver, boolean isTransportSynchronous, boolean isStandard)
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 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.
abstract void	dispose()	Indicates that the WSEndpoint is about to be turned off, and will no longer serve any packet anymore.
boolean	equalsProxiedInstance(WSEndpoint endpoint)	Used for managed endpoints infrastructure to compare equality of proxies vs proxied endpoints.
abstract ServerTubeAssemblerContext	getAssemblerContext()	This is only needed to expose info for monitoring.
abstract WSBinding	getBinding()	Represents the binding for which this WSEndpoint is created for.
List<BoundEndpoint>	getBoundEndpoints()	Gets the list of BoundEndpoint that are associated with this endpoint.
Set<EndpointComponent>	getComponentRegistry()	Deprecated. Use getComponents() instead
Set<Component>	getComponents()	Gets the list of Components 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	getDefaultPortName(QName serviceName, Class endpointClass, boolean isStandard)
static QName	getDefaultPortName(QName serviceName, Class endpointClass, boolean isStandard, MetadataReader metadataReader)
static QName	getDefaultPortName(QName serviceName, Class endpointClass, MetadataReader metadataReader)
static QName	getDefaultServiceName(Class endpointClass)	Gives the wsdl:service default name computed from the endpoint implementaiton class
static QName	getDefaultServiceName(Class endpointClass, boolean isStandard)
static QName	getDefaultServiceName(Class endpointClass, boolean isStandard, MetadataReader metadataReader)
static QName	getDefaultServiceName(Class endpointClass, MetadataReader metadataReader)
abstract <T extends javax.xml.ws.EndpointReference> T	getEndpointReference(Class<T> clazz, String address, String wsdlAddress, List<Element> metadata, List<Element> referenceParameters)
abstract <T extends javax.xml.ws.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
Engine	getEngine()	Returns Engine for this endpoint
abstract Class<T>	getImplementationClass()	Gets the application endpoint Class that eventually serves the request.
abstract org.glassfish.gmbal.ManagedObjectManager	getManagedObjectManager()	Get the ManagedObjectManager for this endpoint.
abstract OperationDispatcher	getOperationDispatcher()	Nullable when there is no associated WSDL Model
abstract PolicyMap	getPolicyMap()	Deprecated. Do not use this method as the PolicyMap API is not final yet and might change in next few months.
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.
<S> S	getSPI(Class<S> spiType)	Gets the specified SPI.
void	process(Packet request, WSEndpoint.CompletionCallback callback, FiberContextSwitchInterceptor interceptor)
final 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 Details

WSEndpoint

public WSEndpoint()

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:

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

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.

getComponentRegistry

@Deprecated
@NotNull
public Set<EndpointComponent> getComponentRegistry()

Deprecated.

Use getComponents() instead

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.

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

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:

javax.xml.ws.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

@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

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 javax.xml.ws.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

Type Parameters:

T -

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 javax.xml.ws.EndpointReference>
T getEndpointReference(Class<T> clazz,
 String address,
 String wsdlAddress,
 List<Element> metadata,
 List<Element> referenceParameters)

Type Parameters:

T -

Parameters:

clazz -

address -

wsdlAddress -

metadata -

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.

Parameters:

endpoint -

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

Returns:

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.