JAX-WS
v2.1

javax.xml.ws
Class Endpoint

java.lang.Object
  extended by javax.xml.ws.Endpoint

public abstract class Endpoint
extends java.lang.Object

A Web service endpoint.

Endpoints are created using the static methods defined in this class. An endpoint is always tied to one Binding and one implementor, both set at endpoint creation time.

An endpoint is either in a published or an unpublished state. The publish methods can be used to start publishing an endpoint, at which point it starts accepting incoming requests. Conversely, the stop method can be used to stop accepting incoming requests and take the endpoint down. Once stopped, an endpoint cannot be published again.

An Executor may be set on the endpoint in order to gain better control over the threads used to dispatch incoming requests. For instance, thread pooling with certain parameters can be enabled by creating a ThreadPoolExecutor and registering it with the endpoint.

Handler chains can be set using the contained Binding.

An endpoint may have a list of metadata documents, such as WSDL and XMLSchema documents, bound to it. At publishing time, the JAX-WS implementation will try to reuse as much of that metadata as possible instead of generating new ones based on the annotations present on the implementor.

Since:
JAX-WS 2.0
See Also:
Binding, BindingType, SOAPBinding, Executor

Field Summary
static java.lang.String WSDL_PORT
          Standard property: name of WSDL port.
static java.lang.String WSDL_SERVICE
          Standard property: name of WSDL service.
 
Constructor Summary
Endpoint()
           
 
Method Summary
static Endpoint create(java.lang.Object implementor)
          Creates an endpoint with the specified implementor object.
static Endpoint create(java.lang.String bindingId, java.lang.Object implementor)
          Creates an endpoint with the specified binding type and implementor object.
abstract  Binding getBinding()
          Returns the binding for this endpoint.
abstract
<T extends EndpointReference>
T
getEndpointReference(java.lang.Class<T> clazz, org.w3c.dom.Element... referenceParameters)
          Returns the EndpointReference associated with this Endpoint instance.
abstract  EndpointReference getEndpointReference(org.w3c.dom.Element... referenceParameters)
          Returns the EndpointReference associated with this Endpoint instance.
abstract  java.util.concurrent.Executor getExecutor()
          Returns the executor for this Endpointinstance.
abstract  java.lang.Object getImplementor()
          Returns the implementation object for this endpoint.
abstract  java.util.List<javax.xml.transform.Source> getMetadata()
          Returns a list of metadata documents for the service.
abstract  java.util.Map<java.lang.String,java.lang.Object> getProperties()
          Returns the property bag for this Endpoint instance.
abstract  boolean isPublished()
          Returns true if the endpoint is in the published state.
abstract  void publish(java.lang.Object serverContext)
          Publishes this endpoint at the provided server context.
abstract  void publish(java.lang.String address)
          Publishes this endpoint at the given address.
static Endpoint publish(java.lang.String address, java.lang.Object implementor)
          Creates and publishes an endpoint for the specified implementor object at the given address.
abstract  void setExecutor(java.util.concurrent.Executor executor)
          Sets the executor for this Endpoint instance.
abstract  void setMetadata(java.util.List<javax.xml.transform.Source> metadata)
          Sets the metadata for this endpoint.
abstract  void setProperties(java.util.Map<java.lang.String,java.lang.Object> properties)
          Sets the property bag for this Endpoint instance.
abstract  void stop()
          Stops publishing this endpoint.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

WSDL_SERVICE

public static final java.lang.String WSDL_SERVICE
Standard property: name of WSDL service.

Type: javax.xml.namespace.QName

See Also:
Constant Field Values

WSDL_PORT

public static final java.lang.String WSDL_PORT
Standard property: name of WSDL port.

Type: javax.xml.namespace.QName

See Also:
Constant Field Values
Constructor Detail

Endpoint

public Endpoint()
Method Detail

create

public static Endpoint create(java.lang.Object implementor)
Creates an endpoint with the specified implementor object. If there is a binding specified via a BindingType annotation then it MUST be used else a default of SOAP 1.1 / HTTP binding MUST be used.

The newly created endpoint may be published by calling one of the publish(String) and publish(Object) methods.

Parameters:
implementor - The endpoint implementor.
Returns:
The newly created endpoint.

create

public static Endpoint create(java.lang.String bindingId,
                              java.lang.Object implementor)
Creates an endpoint with the specified binding type and implementor object.

The newly created endpoint may be published by calling one of the publish(String) and publish(Object) methods.

Parameters:
bindingId - A URI specifying the binding to use. If the bindingID is null and no binding is specified via a BindingType annotation then a default SOAP 1.1 / HTTP binding MUST be used.
implementor - The endpoint implementor.
Returns:
The newly created endpoint.

getBinding

public abstract Binding getBinding()
Returns the binding for this endpoint.

Returns:
The binding for this endpoint

getImplementor

public abstract java.lang.Object getImplementor()
Returns the implementation object for this endpoint.

Returns:
The implementor for this endpoint

publish

public abstract void publish(java.lang.String address)
Publishes this endpoint at the given address. The necessary server infrastructure will be created and configured by the JAX-WS implementation using some default configuration. In order to get more control over the server configuration, please use the publish(Object) method instead.

Parameters:
address - A URI specifying the address to use. The address MUST be compatible with the binding specified at the time the endpoint was created.
Throws:
java.lang.IllegalArgumentException - If the provided address URI is not usable in conjunction with the endpoint's binding.
java.lang.IllegalStateException - If the endpoint has been published already or it has been stopped.

publish

public static Endpoint publish(java.lang.String address,
                               java.lang.Object implementor)
Creates and publishes an endpoint for the specified implementor object at the given address.

The necessary server infrastructure will be created and configured by the JAX-WS implementation using some default configuration. In order to get more control over the server configuration, please use the create(String,Object) and publish(Object) methods instead.

Parameters:
address - A URI specifying the address and transport/protocol to use. A http: URI MUST result in the SOAP 1.1/HTTP binding being used. Implementations may support other URI schemes.
implementor - The endpoint implementor.
Returns:
The newly created endpoint.

publish

public abstract void publish(java.lang.Object serverContext)
Publishes this endpoint at the provided server context. A server context encapsulates the server infrastructure and addressing information for a particular transport. For a call to this method to succeed, the server context passed as an argument to it MUST be compatible with the endpoint's binding.

Parameters:
serverContext - An object representing a server context to be used for publishing the endpoint.
Throws:
java.lang.IllegalArgumentException - If the provided server context is not supported by the implementation or turns out to be unusable in conjunction with the endpoint's binding.
java.lang.IllegalStateException - If the endpoint has been published already or it has been stopped.

stop

public abstract void stop()
Stops publishing this endpoint. If the endpoint is not in a published state, this method has no effect.


isPublished

public abstract boolean isPublished()
Returns true if the endpoint is in the published state.

Returns:
true if the endpoint is in the published state.

getMetadata

public abstract java.util.List<javax.xml.transform.Source> getMetadata()
Returns a list of metadata documents for the service.

Returns:
List<javax.xml.transform.Source> A list of metadata documents for the service

setMetadata

public abstract void setMetadata(java.util.List<javax.xml.transform.Source> metadata)
Sets the metadata for this endpoint.

Parameters:
metadata - A list of XML document sources containing metadata information for the endpoint (e.g. WSDL or XML Schema documents)
Throws:
java.lang.IllegalStateException - If the endpoint has already been published.

getExecutor

public abstract java.util.concurrent.Executor getExecutor()
Returns the executor for this Endpointinstance. The executor is used to dispatch an incoming request to the implementor object.

Returns:
The java.util.concurrent.Executor to be used to dispatch a request.
See Also:
Executor

setExecutor

public abstract void setExecutor(java.util.concurrent.Executor executor)
Sets the executor for this Endpoint instance. The executor is used to dispatch an incoming request to the implementor object. If this Endpoint is published using the publish(Object) method and the specified server context defines its own threading behavior, the executor may be ignored.

Parameters:
executor - The java.util.concurrent.Executor to be used to dispatch a request.
Throws:
java.lang.SecurityException - If the instance does not support setting an executor for security reasons (e.g. the necessary permissions are missing).
See Also:
Executor

getProperties

public abstract java.util.Map<java.lang.String,java.lang.Object> getProperties()
Returns the property bag for this Endpoint instance.

Returns:
Map<String,Object> The property bag associated with this instance.

setProperties

public abstract void setProperties(java.util.Map<java.lang.String,java.lang.Object> properties)
Sets the property bag for this Endpoint instance.

Parameters:
properties - The property bag associated with this instance.

getEndpointReference

public abstract EndpointReference getEndpointReference(org.w3c.dom.Element... referenceParameters)
Returns the EndpointReference associated with this Endpoint instance.

If the Binding for this bindingProvider is either SOAP1.1/HTTP or SOAP1.2/HTTP, then a W3CEndpointReference MUST be returned. If the returned EndpointReference is a W3CEndpointReference it MUST contain the wsaw:ServiceName element and the wsaw:EndpointName attribute on the wsaw:ServiceName. It SHOULD contain the embedded WSDL in the wsa:Metadata element if there is an associated WSDL. The wsaw:InterfaceName MAY also be present.
See WS-Addressing - WSDL 1.0.

Parameters:
referenceParameters - Reference parameters to be associated with the returned EndpointReference instance.
Returns:
EndpointReference of this Endpoint instance. If the returned EndpointReference is of type W3CEndpointReference then it MUST contain the the specified referenceParameters.
Throws:
WebServiceException - If any error in the creation of the EndpointReference or if the Endpoint is not in the published state.
java.lang.UnsupportedOperationException - If this BindingProvider uses the XML/HTTP binding.
Since:
JAX-WS 2.1
See Also:
W3CEndpointReference

getEndpointReference

public abstract <T extends EndpointReference> T getEndpointReference(java.lang.Class<T> clazz,
                                                                     org.w3c.dom.Element... referenceParameters)
Returns the EndpointReference associated with this Endpoint instance.

If the returned EndpointReference is a W3CEndpointReference it MUST contain the wsaw:ServiceName element and the wsaw:EndpointName attribute on the wsaw:ServiceName. It SHOULD contain the embedded WSDL in the wsa:Metadata element if there is an associated WSDL. The wsaw:InterfaceName MAY also be present.
See WS-Addressing - WSDL 1.0.

Parameters:
clazz - Specifies the type of EndpointReference that MUST be returned.
referenceParameters - Reference parameters to be associated with the returned EndpointReference instance.
Returns:
EndpointReference of type clazz of this Endpoint instance. If the returned EndpointReference is of type W3CEndpointReference then it MUST contain the the specified referenceParameters.
Throws:
WebServiceException - If any error in the creation of the EndpointReference or if the Endpoint is not in the published state or if the clazz is not a supported EndpointReference type.
java.lang.UnsupportedOperationException - If this BindingProvider uses the XML/HTTP binding.
Since:
JAX-WS 2.1

JAX-WS
v2.1


Comments to: jsr224-spec-comments@sun.com
More information at: http://java.sun.com/xml/jax-ws

Copyright © 2007 by Sun Microsystems, Inc., 4150 Network Circle,
Santa Clara, California 95054, U.S.A. All Rights Reserved.