javax.xml.ws

## Class Endpoint

- java.lang.Object
- - javax.xml.ws.Endpoint

-     public abstract class Endpoint
      extends 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

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static String` | `WSDL_PORT` Standard property: name of WSDL port.
    `static String` | `WSDL_SERVICE` Standard property: name of WSDL service.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `Endpoint()`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `static Endpoint` | `create(Object implementor)` Creates an endpoint with the specified implementor object.
    `static Endpoint` | `create(Object implementor, WebServiceFeature... features)` Creates an endpoint with the specified implementor object and web service features.
    `static Endpoint` | `create(String bindingId, Object implementor)` Creates an endpoint with the specified binding type and implementor object.
    `static Endpoint` | `create(String bindingId, Object implementor, WebServiceFeature... features)` Creates an endpoint with the specified binding type, implementor object, and web service features.
    `abstract Binding` | `getBinding()` Returns the binding for this endpoint.
    `abstract <T extends EndpointReference> T` | `getEndpointReference(Class<T> clazz, Element... referenceParameters)` Returns the `EndpointReference` associated with this `Endpoint` instance.
    `abstract EndpointReference` | `getEndpointReference(Element... referenceParameters)` Returns the `EndpointReference` associated with this `Endpoint` instance.
    `abstract Executor` | `getExecutor()` Returns the executor for this `Endpoint`instance.
    `abstract Object` | `getImplementor()` Returns the implementation object for this endpoint.
    `abstract List<Source>` | `getMetadata()` Returns a list of metadata documents for the service.
    `abstract Map<String,Object>` | `getProperties()` Returns the property bag for this `Endpoint` instance.
    `abstract boolean` | `isPublished()` Returns true if the endpoint is in the published state.
    `void` | `publish(HttpContext serverContext)` Publishes this endpoint at the provided server context.
    `abstract void` | `publish(Object serverContext)` Publishes this endpoint at the provided server context.
    `abstract void` | `publish(String address)` Publishes this endpoint at the given address.
    `static Endpoint` | `publish(String address, Object implementor)` Creates and publishes an endpoint for the specified implementor object at the given address.
    `static Endpoint` | `publish(String address, Object implementor, WebServiceFeature... features)` Creates and publishes an endpoint for the specified implementor object at the given address.
    `void` | `setEndpointContext(EndpointContext ctxt)` By settng a `EndpointContext`, JAX-WS runtime knows about addresses of other endpoints in an application.
    `abstract void` | `setExecutor(Executor executor)` Sets the executor for this `Endpoint` instance.
    `abstract void` | `setMetadata(List<Source> metadata)` Sets the metadata for this endpoint.
    `abstract void` | `setProperties(Map<String,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 String WSDL_SERVICE

      Standard property: name of WSDL service.

      Type: javax.xml.namespace.QName

      See Also:
        Constant Field Values

    - #### WSDL_PORT

          public static final 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(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(Object implementor,
                        WebServiceFeature... features)

      Creates an endpoint with the specified implementor object and web service features. 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.
        `features` - A list of WebServiceFeature to configure on the endpoint. Supported features not in the `features` parameter will have their default values.
      Returns:
        The newly created endpoint.
      Since:
        JAX-WS 2.2

    - #### create

          public static Endpoint create(String bindingId,
                        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.

    - #### create

          public static Endpoint create(String bindingId,
                        Object implementor,
                        WebServiceFeature... features)

      Creates an endpoint with the specified binding type, implementor object, and web service features.

      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.
        `features` - A list of WebServiceFeature to configure on the endpoint. Supported features not in the `features` parameter will have their default values.
      Returns:
        The newly created endpoint.
      Since:
        JAX-WS 2.2

    - #### getBinding

          public abstract Binding getBinding()

      Returns the binding for this endpoint.
      Returns:
        The binding for this endpoint

    - #### getImplementor

          public abstract Object getImplementor()

      Returns the implementation object for this endpoint.
      Returns:
        The implementor for this endpoint

    - #### publish

          public abstract void publish(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:
        `IllegalArgumentException` - If the provided address URI is not usable in conjunction with the endpoint's binding.
        `IllegalStateException` - If the endpoint has been published already or it has been stopped.
        `SecurityException` - If a `java.lang.SecurityManger` is being used and the application doesn't have the `WebServicePermission("publishEndpoint")` permission.

    - #### publish

          public static Endpoint publish(String address,
                         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.
      Throws:
        `SecurityException` - If a `java.lang.SecurityManger` is being used and the application doesn't have the `WebServicePermission("publishEndpoint")` permission.

    - #### publish

          public static Endpoint publish(String address,
                         Object implementor,
                         WebServiceFeature... features)

      Creates and publishes an endpoint for the specified implementor object at the given address. The created endpoint is configured with the web service features.

      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.
        `features` - A list of WebServiceFeature to configure on the endpoint. Supported features not in the `features` parameter will have their default values.
      Returns:
        The newly created endpoint.
      Throws:
        `SecurityException` - If a `java.lang.SecurityManger` is being used and the application doesn't have the `WebServicePermission("publishEndpoint")` permission.
      Since:
        JAX-WS 2.2

    - #### publish

          public abstract void publish(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:
        `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.
        `IllegalStateException` - If the endpoint has been published already or it has been stopped.
        `SecurityException` - If a `java.lang.SecurityManger` is being used and the application doesn't have the `WebServicePermission("publishEndpoint")` permission.

    - #### publish

          public void publish(HttpContext 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.

      This is meant for container developers to publish the the endpoints portably and not intended for the end developers.

      Parameters:
        `serverContext` - An object representing a server context to be used for publishing the endpoint.
      Throws:
        `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.
        `IllegalStateException` - If the endpoint has been published already or it has been stopped.
        `SecurityException` - If a `java.lang.SecurityManger` is being used and the application doesn't have the `WebServicePermission("publishEndpoint")` permission.
      Since:
        JAX-WS 2.2

    - #### 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 List<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(List<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:
        `IllegalStateException` - If the endpoint has already been published.

    - #### getExecutor

          public abstract Executor getExecutor()

      Returns the executor for this `Endpoint`instance. 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(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:
        `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 Map<String,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(Map<String,Object> properties)

      Sets the property bag for this `Endpoint` instance.
      Parameters:
        `properties` - The property bag associated with this instance.

    - #### getEndpointReference

          public abstract EndpointReference getEndpointReference(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.

      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.
        `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(Class<T> clazz,
                                                             Element... referenceParameters)

      Returns the `EndpointReference` associated with this `Endpoint` instance.
      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.
        `UnsupportedOperationException` - If this `BindingProvider` uses the XML/HTTP binding.
      Since:
        JAX-WS 2.1

    - #### setEndpointContext

          public void setEndpointContext(EndpointContext ctxt)

      By settng a `EndpointContext`, JAX-WS runtime knows about addresses of other endpoints in an application. If multiple endpoints share different ports of a WSDL, then the multiple port addresses are patched when the WSDL is accessed.

      This needs to be set before publishing the endpoints.

      Parameters:
        `ctxt` - that is shared for multiple endpoints
      Throws:
        `IllegalStateException` - If the endpoint has been published already or it has been stopped.
      Since:
        JAX-WS 2.2

Copyright © 1996-2013, Oracle and/or its affiliates. All Rights Reserved. Use is subject to license terms.