| java.lang.Object
 com.sun.xml.ws.api.server.WSEndpoint
| WSEndpoint | | abstract public class WSEndpoint (Code) | | 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
PipeHead s, where many copies can be created
for each endpoint.
Each
PipeHead is thread-unsafe, and request needs to be
serialized. A
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
PipeHead s thread-unsafe allow the JAX-WS RI internal to
tie thread-local resources to
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
Packet 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 the
WSEndpoint.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
PipeHead.process(PacketWebServiceContextDelegateTransportBackChannel) .
author:
Kohsuke Kawaguchi |
| Inner Class :public interface CompletionCallback | |
| Inner Class :public interface PipeHead | |
| Method Summary | |
| public static 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
This method works like the following:
-
ServiceDefinition is modeleed from the given SEI type.
-
Invoker that always serves implementationObject will be used.
Parameters:
implType - Endpoint class(not SEI). | | public static 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)
| | public static 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
WSEndpoint.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 public Codec | createCodec()
Gets the Endpoint's codec that is used to encode/decode
Message s. | | abstract public PipeHead | createPipeHead()
Creates a new
PipeHead to process
incoming requests.
This is not a cheap operation. | | abstract public void | dispose()
Indicates that the
WSEndpoint is about to be turned off,
and will no longer serve any packet anymore. | | abstract public WSBinding | getBinding()
Represents the binding for which this
WSEndpoint is created for. | | abstract public Set<EndpointComponent> | getComponentRegistry()
Gets the list of
EndpointComponent that are associated
with this endpoint. | | abstract public Container | getContainer()
Gets the
Container object.
The components inside
WSEndpoint uses this reference
to communicate with the hosting environment.
always same object. | | public static QName | getDefaultPortName(QName serviceName, Class endpointClass)
| | public static QName | getDefaultServiceName(Class endpointClass)
| | abstract public Class<T> | getImplementationClass()
Gets the application endpoint
Class that eventually serves the request. | | abstract public 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. | | abstract public QName | getPortName()
Gets the application endpoint's portName. | | abstract public SEIModel | getSEIModel()
Gets the
com.sun.xml.ws.api.model.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.
maybe null. | | abstract public ServiceDefinition | getServiceDefinition()
Gets the description of the service. | | abstract public QName | getServiceName()
Gets the application endpoint's serviceName. | | final public void | schedule(Packet request, CompletionCallback callback)
This method takes a
Packet that represents
a request, run it through a
Tube 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 through
CompletionCallback .
This takes care of pooling of
Tube lines and reuses
tubeline for requests. | | abstract public void | schedule(Packet request, CompletionCallback callback, FiberContextSwitchInterceptor interceptor)
Schedule invocation of web service asynchronously. | | abstract public void | setExecutor(Executor exec)
Set this
Executor to run asynchronous requests using this executor. |
| create | | public static 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)(Code) | | Creates an endpoint from deployment or programmatic configuration
This method works like the following:
-
ServiceDefinition is modeleed from the given SEI type.
-
Invoker that always serves implementationObject will be used.
Parameters:
implType - Endpoint class(not SEI). Enpoint class must have @WebService or @WebServiceProviderannotation.
Parameters:
processHandlerAnnotation - Flag to control processing of @HandlerChain on Impl classif true, processes @HandlerChain on Implif false, DD might have set HandlerChain no need to parse.
Parameters:
invoker - Pass an object to invoke the actual endpoint object. If it is null, a defaultinvoker is created using InstanceResolver.createDefault. Appserverscould create its own invoker to do additional functions like transactions,invoking the endpoint through proxy etc.
Parameters:
serviceName - Optional service name(may be from DD) to override the one given by theimplementation class. If it is null, it will be derived from annotations.
Parameters:
portName - Optional port name(may be from DD) to override the one given by theimplementation class. If it is null, it will be derived from annotations.
Parameters:
container - Allows technologies that are built on top of JAX-WS(such as WSIT) needs tonegotiate private contracts between them and the container
Parameters:
binding - JAX-WS implementation of Binding. This object can be created byBindingID.createBinding. Usually the binding can be got fromDD, javax.xml.ws.BindingType.TODO: DD has a configuration for MTOM threshold.Maybe we need something more generic so that other technologieslike 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.
Parameters:
primaryWsdl - The ServiceDefinition.getPrimary 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?
Parameters:
metadata - Other documents that become SDDocuments. Can be null.
Parameters:
resolver - Optional resolver used to de-reference resources referenced fromWSDL. Must be null if the url is null.
Parameters:
isTransportSynchronous - If the caller knows that the returned WSEndpoint is going to beused by a synchronous-only transport, then it may pass in trueto 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. newly constructed WSEndpoint.
throws:
WebServiceException - if the endpoint set up fails. |
| create | | public static 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)(Code) | | The same as
WSEndpoint.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. |
| createCodec | | abstract public Codec createCodec()(Code) | | Gets the Endpoint's codec that is used to encode/decode
Message s. This is a
copy of the master codec and it shouldn't be shared across two requests running
concurrently(unless it is stateless).
codec to encode/decode |
| createPipeHead | | abstract public PipeHead createPipeHead()(Code) | | Creates a new
PipeHead to process
incoming requests.
This is not a cheap operation. The caller is expected
to reuse the returned
PipeHead . See
WSEndpoint class javadoc for details.
A newly created PipeHead that's ready to serve. |
| dispose | | abstract public void dispose()(Code) | | 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
PipeHead.process methods (by other threads)
and future
PipeHead.process method invocations.
|
| getBinding | | abstract public WSBinding getBinding()(Code) | | Represents the binding for which this
WSEndpoint is created for.
always same object. |
| getComponentRegistry | | abstract public Set<EndpointComponent> getComponentRegistry()(Code) | | 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.
always return the same set. |
| getDefaultPortName | | public static QName getDefaultPortName(QName serviceName, Class endpointClass)(Code) | | Gives the wsdl:service/wsdl:port default name computed from the endpoint implementaiton class
|
| getDefaultServiceName | | public static QName getDefaultServiceName(Class endpointClass)(Code) | | Gives the wsdl:service default name computed from the endpoint implementaiton class
|
| getImplementationClass | | abstract public Class<T> getImplementationClass()(Code) | | Gets the application endpoint
Class that eventually serves the request.
This is the same value given to the
WSEndpoint.create method.
|
| getPort | | abstract public WSDLPort getPort()(Code) | | 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.
Possibly null, but always the same value. |
| getPortName | | abstract public QName getPortName()(Code) | | Gets the application endpoint's portName. It could be got from DD or annotations
same as wsdl:port QName if WSDL exists or generated |
| getSEIModel | | abstract public SEIModel getSEIModel()(Code) | | Gets the
com.sun.xml.ws.api.model.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.
maybe null. See above for more discussion.Always the same value. |
| getServiceDefinition | | abstract public ServiceDefinition getServiceDefinition()(Code) | | 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.
Possibly null, but always the same value. |
| getServiceName | | abstract public QName getServiceName()(Code) | | Gets the application endpoint's serviceName. It could be got from DD or annotations
same as wsdl:service QName if WSDL exists or generated |
| schedule | | final public void schedule(Packet request, CompletionCallback callback)(Code) | | This method takes a
Packet that represents
a request, run it through a
Tube 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 through
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
PipeHead.process .
Before calling this method, set the executor using
WSEndpoint.setExecutor . 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.
See Also: Packet.transportBackChannel
See Also: Packet.webServiceContextDelegate
Parameters:
request - web service request
Parameters:
callback - callback to get response packet |
| schedule | | abstract public void schedule(Packet request, CompletionCallback callback, FiberContextSwitchInterceptor interceptor)(Code) | | Schedule invocation of web service asynchronously.
See Also: WSEndpoint.schedule(Packet,CompletionCallback)
Parameters:
request - web service request
Parameters:
callback - callback to get response packet(exception if there is one)
Parameters:
interceptor - caller's interceptor to impose a context of execution |
|
|