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 thePacket
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 incomingPacket
throughWSEndpoint.PipeHead
s, where many copies can be created for each endpoint.Each
WSEndpoint.PipeHead
is thread-unsafe, and request needs to be serialized. AWSEndpoint.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. MakingWSEndpoint.PipeHead
s thread-unsafe allow the JAX-WS RI internal to tie thread-local resources toWSEndpoint.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 toWSEndpoint
throughAdapter
.WSEndpoint
is ready to handlePacket
s 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 thedispose()
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 aWSWebServiceContext
implementation. But a bulk of the work is delegated toWebServiceContextDelegate
, which is passed in as a parameter toWSEndpoint.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
All Methods Static Methods Instance Methods Abstract Methods Concrete Methods Deprecated Methods 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 ascreate(Class, boolean, Invoker, QName, QName, Container, WSBinding, SDDocumentSource, Collection, EntityResolver)
except that this version takes an url of thejax-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 configurationstatic <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/decodeMessage
s.abstract WSEndpoint.PipeHead
createPipeHead()
Creates a newWSEndpoint.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 theWSEndpoint
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 thisWSEndpoint
is created for.List<BoundEndpoint>
getBoundEndpoints()
Gets the list ofBoundEndpoint
that are associated with this endpoint.abstract Set<EndpointComponent>
getComponentRegistry()
Deprecated.Set<Component>
getComponents()
Returns the set ofComponent
s registered with this objectabstract Container
getContainer()
Gets theContainer
object.static QName
getDefaultPortName(QName serviceName, Class endpointClass)
Gives the wsdl:service/wsdl:port default name computed from the endpoint implementaiton classstatic 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 classstatic 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 jakarta.xml.ws.EndpointReference>
TgetEndpointReference(Class<T> clazz, String address, String wsdlAddress, List<Element> metadata, List<Element> referenceParameters)
abstract <T extends jakarta.xml.ws.EndpointReference>
TgetEndpointReference(Class<T> clazz, String address, String wsdlAddress, Element... referenceParameters)
Return EndpointReference instance, based on passed parameters and spec version represented by clazzEngine
getEngine()
ReturnsEngine
for this endpointabstract Class<T>
getImplementationClass()
Gets the application endpointClass
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 Modelabstract 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 theSEIModel
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)
void
schedule(Packet request, WSEndpoint.CompletionCallback callback)
This method takes aPacket
that represents a request, run it through aTube
line, 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 throughWSEndpoint.CompletionCallback
.abstract void
schedule(Packet request, WSEndpoint.CompletionCallback callback, FiberContextSwitchInterceptor interceptor)
Schedule invocation of web service asynchronously.abstract void
setExecutor(Executor exec)
Set thisExecutor
to run asynchronous requests using this executor.
-
-
-
Method Detail
-
createCodec
@NotNull public abstract Codec createCodec()
Gets the Endpoint's codec that is used to encode/decodeMessage
s. 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 endpointClass
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 thisWSEndpoint
is created for.- Returns:
- always same object.
-
getContainer
@NotNull public abstract Container getContainer()
Gets theContainer
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 thisExecutor
to run asynchronous requests using this executor. This executor is set onEngine
and must be set before callingschedule(Packet,CompletionCallback)
andschedule(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 aPacket
that represents a request, run it through aTube
line, 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 throughWSEndpoint.CompletionCallback
.This takes care of pooling of
Tube
lines 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 someWebServiceContext
methods correctly.- Parameters:
request
- web service requestcallback
- 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 requestcallback
- 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)
-
createPipeHead
@NotNull public abstract WSEndpoint.PipeHead createPipeHead()
Creates a newWSEndpoint.PipeHead
to process incoming requests.This is not a cheap operation. The caller is expected to reuse the returned
WSEndpoint.PipeHead
. Seeclass javadoc
for details.- Returns:
- A newly created
WSEndpoint.PipeHead
that's ready to serve.
-
dispose
public abstract void dispose()
Indicates that theWSEndpoint
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 futureWSEndpoint.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 ofBoundEndpoint
that are associated with this endpoint.- Returns:
- always return the same set.
-
getComponentRegistry
@NotNull public abstract Set<EndpointComponent> getComponentRegistry()
Deprecated.Gets the list ofEndpointComponent
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()
Description copied from interface:ComponentRegistry
Returns the set ofComponent
s registered with this object- Specified by:
getComponents
in interfaceComponentRegistry
- Returns:
- set of registered components
-
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.
-
getSEIModel
@Nullable public abstract SEIModel getSEIModel()
Gets theSEIModel
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 configurationThis method works like the following:
ServiceDefinition
is modeleed from the given SEI type.Invoker
that always servesimplementationObject
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 usingInstanceResolver.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 containerbinding
- JAX-WS implementation ofBinding
. This object can be created byBindingID.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
- Theprimary
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 becomeSDDocument
s. Can be null.resolver
- Optional resolver used to de-reference resources referenced from WSDL. Must be null if theurl
is null.isTransportSynchronous
- If the caller knows that the returnedWSEndpoint
is going to be used by a synchronous-only transport, then it may pass intrue
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 fromServerTubeAssemblerContext.isSynchronous()
.- Returns:
- newly constructed
WSEndpoint
. - Throws:
jakarta.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 assumesisTransportSynchronous==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 ascreate(Class, boolean, Invoker, QName, QName, Container, WSBinding, SDDocumentSource, Collection, EntityResolver)
except that this version takes an url of thejax-ws-catalog.xml
.- Parameters:
catalogUrl
- if not null, anEntityResolver
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 jakarta.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 versionaddress
- endpoint addresswsdlAddress
- wsdl addressreferenceParameters
- 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 jakarta.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.
-
-