javax.xml.ws

## Class Service

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

-     public class Service
      extends Object

  `Service` objects provide the client view of a Web service.

  `Service` acts as a factory of the following:

  - Proxies for a target service endpoint.
  - Instances of `Dispatch` for dynamic message-oriented invocation of a remote operation.

  The ports available on a service can be enumerated using the `getPorts` method. Alternatively, you can pass a service endpoint interface to the unary `getPort` method and let the runtime select a compatible port.

  Handler chains for all the objects created by a `Service` can be set by means of a `HandlerResolver`.

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

  Since:
    JAX-WS 2.0
  See Also:
    `Provider`, `HandlerResolver`, `Executor`

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `Service.Mode` The orientation of a dynamic client or service.

  - ### Constructor Summary

    Constructors
    Modifier | Constructor and Description
    --- | ---
    `protected` | `Service(URL wsdlDocumentLocation, QName serviceName)`
    `protected` | `Service(URL wsdlDocumentLocation, QName serviceName, WebServiceFeature... features)`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addPort(QName portName, String bindingId, String endpointAddress)` Creates a new port for the service.
    `static Service` | `create(QName serviceName)` Creates a `Service` instance.
    `static Service` | `create(QName serviceName, WebServiceFeature... features)` Creates a `Service` instance.
    `static Service` | `create(URL wsdlDocumentLocation, QName serviceName)` Creates a `Service` instance.
    `static Service` | `create(URL wsdlDocumentLocation, QName serviceName, WebServiceFeature... features)` Creates a `Service` instance.
    `<T> Dispatch<T>` | `createDispatch(EndpointReference endpointReference, Class<T> type, Service.Mode mode, WebServiceFeature... features)` Creates a `Dispatch` instance for use with objects of the client's choosing.
    `Dispatch<Object>` | `createDispatch(EndpointReference endpointReference, JAXBContext context, Service.Mode mode, WebServiceFeature... features)` Creates a `Dispatch` instance for use with JAXB generated objects.
    `<T> Dispatch<T>` | `createDispatch(QName portName, Class<T> type, Service.Mode mode)` Creates a `Dispatch` instance for use with objects of the client's choosing.
    `<T> Dispatch<T>` | `createDispatch(QName portName, Class<T> type, Service.Mode mode, WebServiceFeature... features)` Creates a `Dispatch` instance for use with objects of the client's choosing.
    `Dispatch<Object>` | `createDispatch(QName portName, JAXBContext context, Service.Mode mode)` Creates a `Dispatch` instance for use with JAXB generated objects.
    `Dispatch<Object>` | `createDispatch(QName portName, JAXBContext context, Service.Mode mode, WebServiceFeature... features)` Creates a `Dispatch` instance for use with JAXB generated objects.
    `Executor` | `getExecutor()` Returns the executor for this `Service`instance.
    `HandlerResolver` | `getHandlerResolver()` Returns the configured handler resolver.
    `<T> T` | `getPort(Class<T> serviceEndpointInterface)` The `getPort` method returns a proxy.
    `<T> T` | `getPort(Class<T> serviceEndpointInterface, WebServiceFeature... features)` The `getPort` method returns a proxy.
    `<T> T` | `getPort(EndpointReference endpointReference, Class<T> serviceEndpointInterface, WebServiceFeature... features)` The `getPort` method returns a proxy.
    `<T> T` | `getPort(QName portName, Class<T> serviceEndpointInterface)` The `getPort` method returns a proxy.
    `<T> T` | `getPort(QName portName, Class<T> serviceEndpointInterface, WebServiceFeature... features)` The `getPort` method returns a proxy.
    `Iterator<QName>` | `getPorts()` Returns an `Iterator` for the list of `QName`s of service endpoints grouped by this service
    `QName` | `getServiceName()` Gets the name of this service.
    `URL` | `getWSDLDocumentLocation()` Gets the location of the WSDL document for this Service.
    `void` | `setExecutor(Executor executor)` Sets the executor for this `Service` instance.
    `void` | `setHandlerResolver(HandlerResolver handlerResolver)` Sets the `HandlerResolver` for this `Service` instance.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Constructor Detail

    - #### Service

          protected Service(URL wsdlDocumentLocation,
                 QName serviceName)

    - #### Service

          protected Service(URL wsdlDocumentLocation,
                 QName serviceName,
                 WebServiceFeature... features)

  - ### Method Detail

    - #### getPort

          public <T> T getPort(QName portName,
                      Class<T> serviceEndpointInterface)

      The `getPort` method returns a proxy. A service client uses this proxy to invoke operations on the target service endpoint. The `serviceEndpointInterface` specifies the service endpoint interface that is supported by the created dynamic proxy instance.
      Parameters:
        `portName` - Qualified name of the service endpoint in the WSDL service description.
        `serviceEndpointInterface` - Service endpoint interface supported by the dynamic proxy instance.
      Returns:
        Object Proxy instance that supports the specified service endpoint interface.
      Throws:
        `WebServiceException` - This exception is thrown in the following cases:
        - If there is an error in creation of the proxy.
        - If there is any missing WSDL metadata as required by this method.
        - If an illegal `serviceEndpointInterface` or `portName` is specified.
      See Also:
        `Proxy`, `InvocationHandler`

    - #### getPort

          public <T> T getPort(QName portName,
                      Class<T> serviceEndpointInterface,
                      WebServiceFeature... features)

      The `getPort` method returns a proxy. A service client uses this proxy to invoke operations on the target service endpoint. The `serviceEndpointInterface` specifies the service endpoint interface that is supported by the created dynamic proxy instance.
      Parameters:
        `portName` - Qualified name of the service endpoint in the WSDL service description.
        `serviceEndpointInterface` - Service endpoint interface supported by the dynamic proxy instance.
        `features` - A list of WebServiceFeatures to configure on the proxy. Supported features not in the `features` parameter will have their default values.
      Returns:
        Object Proxy instance that supports the specified service endpoint interface.
      Throws:
        `WebServiceException` - This exception is thrown in the following cases:
        - If there is an error in creation of the proxy.
        - If there is any missing WSDL metadata as required by this method.
        - If an illegal `serviceEndpointInterface` or `portName` is specified.
        - If a feature is enabled that is not compatible with this port or is unsupported.
      Since:
        JAX-WS 2.1
      See Also:
        `Proxy`, `InvocationHandler`, `WebServiceFeature`

    - #### getPort

          public <T> T getPort(Class<T> serviceEndpointInterface)

      The `getPort` method returns a proxy. The parameter `serviceEndpointInterface` specifies the service endpoint interface that is supported by the returned proxy. In the implementation of this method, the JAX-WS runtime system takes the responsibility of selecting a protocol binding (and a port) and configuring the proxy accordingly. The returned proxy should not be reconfigured by the client.
      Parameters:
        `serviceEndpointInterface` - Service endpoint interface.
      Returns:
        Object instance that supports the specified service endpoint interface.
      Throws:
        `WebServiceException` -
        - If there is an error during creation of the proxy.
        - If there is any missing WSDL metadata as required by this method.
        - If an illegal `serviceEndpointInterface` is specified.

    - #### getPort

          public <T> T getPort(Class<T> serviceEndpointInterface,
                      WebServiceFeature... features)

      The `getPort` method returns a proxy. The parameter `serviceEndpointInterface` specifies the service endpoint interface that is supported by the returned proxy. In the implementation of this method, the JAX-WS runtime system takes the responsibility of selecting a protocol binding (and a port) and configuring the proxy accordingly. The returned proxy should not be reconfigured by the client.
      Parameters:
        `serviceEndpointInterface` - Service endpoint interface.
        `features` - A list of WebServiceFeatures to configure on the proxy. Supported features not in the `features` parameter will have their default values.
      Returns:
        Object instance that supports the specified service endpoint interface.
      Throws:
        `WebServiceException` -
        - If there is an error during creation of the proxy.
        - If there is any missing WSDL metadata as required by this method.
        - If an illegal `serviceEndpointInterface` is specified.
        - If a feature is enabled that is not compatible with this port or is unsupported.
      Since:
        JAX-WS 2.1
      See Also:
        `WebServiceFeature`

    - #### getPort

          public <T> T getPort(EndpointReference endpointReference,
                      Class<T> serviceEndpointInterface,
                      WebServiceFeature... features)

      The `getPort` method returns a proxy. The parameter `endpointReference` specifies the endpoint that will be invoked by the returned proxy. If there are any reference parameters in the `endpointReference`, then those reference parameters MUST appear as SOAP headers, indicating them to be reference parameters, on all messages sent to the endpoint. The `endpointReference's` address MUST be used for invocations on the endpoint. The parameter `serviceEndpointInterface` specifies the service endpoint interface that is supported by the returned proxy. In the implementation of this method, the JAX-WS runtime system takes the responsibility of selecting a protocol binding (and a port) and configuring the proxy accordingly from the WSDL associated with this `Service` instance or from the metadata from the `endpointReference`. If this `Service` instance has a WSDL and the `endpointReference` metadata also has a WSDL, then the WSDL from this instance MUST be used. If this `Service` instance does not have a WSDL and the `endpointReference` does have a WSDL, then the WSDL from the `endpointReference` MAY be used. The returned proxy should not be reconfigured by the client. If this `Service` instance has a known proxy port that matches the information contained in the WSDL, then that proxy is returned, otherwise a WebServiceException is thrown.

      Calling this method has the same behavior as the following

           port = service.getPort(portName, serviceEndpointInterface);

      where the `portName` is retrieved from the metadata of the `endpointReference` or from the `serviceEndpointInterface` and the WSDL associated with this `Service` instance.
      Parameters:
        `endpointReference` - The `EndpointReference` for the target service endpoint that will be invoked by the returned proxy.
        `serviceEndpointInterface` - Service endpoint interface.
        `features` - A list of `WebServiceFeatures` to configure on the proxy. Supported features not in the `features` parameter will have their default values.
      Returns:
        Object Proxy instance that supports the specified service endpoint interface.
      Throws:
        `WebServiceException` -
        - If there is an error during creation of the proxy.
        - If there is any missing WSDL metadata as required by this method.
        - If the `endpointReference` metadata does not match the `serviceName` of this `Service` instance.
        - If a `portName` cannot be extracted from the WSDL or `endpointReference` metadata.
        - If an invalid `endpointReference` is specified.
        - If an invalid `serviceEndpointInterface` is specified.
        - If a feature is enabled that is not compatible with this port or is unsupported.
      Since:
        JAX-WS 2.1

    - #### addPort

          public void addPort(QName portName,
                     String bindingId,
                     String endpointAddress)

      Creates a new port for the service. Ports created in this way contain no WSDL port type information and can only be used for creating `Dispatch`instances.
      Parameters:
        `portName` - Qualified name for the target service endpoint.
        `bindingId` - A String identifier of a binding.
        `endpointAddress` - Address of the target service endpoint as a URI.
      Throws:
        `WebServiceException` - If any error in the creation of the port.
      See Also:
        `SOAPBinding.SOAP11HTTP_BINDING`, `SOAPBinding.SOAP12HTTP_BINDING`, `HTTPBinding.HTTP_BINDING`

    - #### createDispatch

          public <T> Dispatch<T> createDispatch(QName portName,
                                       Class<T> type,
                                       Service.Mode mode)

      Creates a `Dispatch` instance for use with objects of the client's choosing.
      Parameters:
        `portName` - Qualified name for the target service endpoint
        `type` - The class of object used for messages or message payloads. Implementations are required to support `javax.xml.transform.Source`, `javax.xml.soap.SOAPMessage` and `javax.activation.DataSource`, depending on the binding in use.
        `mode` - Controls whether the created dispatch instance is message or payload oriented, i.e. whether the client will work with complete protocol messages or message payloads. E.g. when using the SOAP protocol, this parameter controls whether the client will work with SOAP messages or the contents of a SOAP body. Mode MUST be MESSAGE when type is SOAPMessage.
      Returns:
        Dispatch instance.
      Throws:
        `WebServiceException` - If any error in the creation of the `Dispatch` object.
      See Also:
        `Source`, `SOAPMessage`

    - #### createDispatch

          public <T> Dispatch<T> createDispatch(QName portName,
                                       Class<T> type,
                                       Service.Mode mode,
                                       WebServiceFeature... features)

      Creates a `Dispatch` instance for use with objects of the client's choosing.
      Parameters:
        `portName` - Qualified name for the target service endpoint
        `type` - The class of object used for messages or message payloads. Implementations are required to support `javax.xml.transform.Source` and `javax.xml.soap.SOAPMessage`.
        `mode` - Controls whether the created dispatch instance is message or payload oriented, i.e. whether the client will work with complete protocol messages or message payloads. E.g. when using the SOAP protocol, this parameter controls whether the client will work with SOAP messages or the contents of a SOAP body. Mode MUST be `MESSAGE` when type is `SOAPMessage`.
        `features` - A list of `WebServiceFeatures` to configure on the proxy. Supported features not in the `features` parameter will have their default values.
      Returns:
        Dispatch instance.
      Throws:
        `WebServiceException` - If any error in the creation of the `Dispatch` object or if a feature is enabled that is not compatible with this port or is unsupported.
      Since:
        JAX-WS 2.1
      See Also:
        `Source`, `SOAPMessage`, `WebServiceFeature`

    - #### createDispatch

          public <T> Dispatch<T> createDispatch(EndpointReference endpointReference,
                                       Class<T> type,
                                       Service.Mode mode,
                                       WebServiceFeature... features)

      Creates a `Dispatch` instance for use with objects of the client's choosing. If there are any reference parameters in the `endpointReference`, then those reference parameters MUST appear as SOAP headers, indicating them to be reference parameters, on all messages sent to the endpoint. The `endpointReference's` address MUST be used for invocations on the endpoint. In the implementation of this method, the JAX-WS runtime system takes the responsibility of selecting a protocol binding (and a port) and configuring the dispatch accordingly from the WSDL associated with this `Service` instance or from the metadata from the `endpointReference`. If this `Service` instance has a WSDL and the `endpointReference` also has a WSDL in its metadata, then the WSDL from this instance MUST be used. If this `Service` instance does not have a WSDL and the `endpointReference` does have a WSDL, then the WSDL from the `endpointReference` MAY be used. An implementation MUST be able to retrieve the `portName` from the `endpointReference` metadata.

      This method behaves the same as calling

           dispatch = service.createDispatch(portName, type, mode, features);

      where the `portName` is retrieved from the WSDL or `EndpointReference` metadata.
      Parameters:
        `endpointReference` - The `EndpointReference` for the target service endpoint that will be invoked by the returned `Dispatch` object.
        `type` - The class of object used to messages or message payloads. Implementations are required to support `javax.xml.transform.Source` and `javax.xml.soap.SOAPMessage`.
        `mode` - Controls whether the created dispatch instance is message or payload oriented, i.e. whether the client will work with complete protocol messages or message payloads. E.g. when using the SOAP protocol, this parameter controls whether the client will work with SOAP messages or the contents of a SOAP body. Mode MUST be `MESSAGE` when type is `SOAPMessage`.
        `features` - An array of `WebServiceFeatures` to configure on the proxy. Supported features not in the `features` parameter will have their default values.
      Returns:
        Dispatch instance
      Throws:
        `WebServiceException` -
        - If there is any missing WSDL metadata as required by this method.
        - If the `endpointReference` metadata does not match the `serviceName` or `portName` of a WSDL associated with this `Service` instance.
        - If the `portName` cannot be determined from the `EndpointReference` metadata.
        - If any error in the creation of the `Dispatch` object.
        - If a feature is enabled that is not compatible with this port or is unsupported.
      Since:
        JAX-WS 2.1
      See Also:
        `Source`, `SOAPMessage`, `WebServiceFeature`

    - #### createDispatch

          public Dispatch<Object> createDispatch(QName portName,
                                        JAXBContext context,
                                        Service.Mode mode)

      Creates a `Dispatch` instance for use with JAXB generated objects.
      Parameters:
        `portName` - Qualified name for the target service endpoint
        `context` - The JAXB context used to marshall and unmarshall messages or message payloads.
        `mode` - Controls whether the created dispatch instance is message or payload oriented, i.e. whether the client will work with complete protocol messages or message payloads. E.g. when using the SOAP protocol, this parameter controls whether the client will work with SOAP messages or the contents of a SOAP body.
      Returns:
        Dispatch instance.
      Throws:
        `WebServiceException` - If any error in the creation of the `Dispatch` object.
      See Also:
        `JAXBContext`

    - #### createDispatch

          public Dispatch<Object> createDispatch(QName portName,
                                        JAXBContext context,
                                        Service.Mode mode,
                                        WebServiceFeature... features)

      Creates a `Dispatch` instance for use with JAXB generated objects.
      Parameters:
        `portName` - Qualified name for the target service endpoint
        `context` - The JAXB context used to marshall and unmarshall messages or message payloads.
        `mode` - Controls whether the created dispatch instance is message or payload oriented, i.e. whether the client will work with complete protocol messages or message payloads. E.g. when using the SOAP protocol, this parameter controls whether the client will work with SOAP messages or the contents of a SOAP body.
        `features` - A list of `WebServiceFeatures` to configure on the proxy. Supported features not in the `features` parameter will have their default values.
      Returns:
        Dispatch instance.
      Throws:
        `WebServiceException` - If any error in the creation of the `Dispatch` object or if a feature is enabled that is not compatible with this port or is unsupported.
      Since:
        JAX-WS 2.1
      See Also:
        `JAXBContext`, `WebServiceFeature`

    - #### createDispatch

          public Dispatch<Object> createDispatch(EndpointReference endpointReference,
                                        JAXBContext context,
                                        Service.Mode mode,
                                        WebServiceFeature... features)

      Creates a `Dispatch` instance for use with JAXB generated objects. If there are any reference parameters in the `endpointReference`, then those reference parameters MUST appear as SOAP headers, indicating them to be reference parameters, on all messages sent to the endpoint. The `endpointReference's` address MUST be used for invocations on the endpoint. In the implementation of this method, the JAX-WS runtime system takes the responsibility of selecting a protocol binding (and a port) and configuring the dispatch accordingly from the WSDL associated with this `Service` instance or from the metadata from the `endpointReference`. If this `Service` instance has a WSDL and the `endpointReference` also has a WSDL in its metadata, then the WSDL from this instance MUST be used. If this `Service` instance does not have a WSDL and the `endpointReference` does have a WSDL, then the WSDL from the `endpointReference` MAY be used. An implementation MUST be able to retrieve the `portName` from the `endpointReference` metadata.

      This method behavies the same as calling

           dispatch = service.createDispatch(portName, context, mode, features);

      where the `portName` is retrieved from the WSDL or `endpointReference` metadata.
      Parameters:
        `endpointReference` - The `EndpointReference` for the target service endpoint that will be invoked by the returned `Dispatch` object.
        `context` - The JAXB context used to marshall and unmarshall messages or message payloads.
        `mode` - Controls whether the created dispatch instance is message or payload oriented, i.e. whether the client will work with complete protocol messages or message payloads. E.g. when using the SOAP protocol, this parameter controls whether the client will work with SOAP messages or the contents of a SOAP body.
        `features` - An array of `WebServiceFeatures` to configure on the proxy. Supported features not in the `features` parameter will have their default values.
      Returns:
        Dispatch instance
      Throws:
        `WebServiceException` -
        - If there is any missing WSDL metadata as required by this method.
        - If the `endpointReference` metadata does not match the `serviceName` or `portName` of a WSDL associated with this `Service` instance.
        - If the `portName` cannot be determined from the `EndpointReference` metadata.
        - If any error in the creation of the `Dispatch` object.
        - if a feature is enabled that is not compatible with this port or is unsupported.
      Since:
        JAX-WS 2.1
      See Also:
        `JAXBContext`, `WebServiceFeature`

    - #### getServiceName

          public QName getServiceName()

      Gets the name of this service.
      Returns:
        Qualified name of this service

    - #### getPorts

          public Iterator<QName> getPorts()

      Returns an `Iterator` for the list of `QName`s of service endpoints grouped by this service
      Returns:
        Returns `java.util.Iterator` with elements of type `javax.xml.namespace.QName`.
      Throws:
        `WebServiceException` - If this Service class does not have access to the required WSDL metadata.

    - #### getWSDLDocumentLocation

          public URL getWSDLDocumentLocation()

      Gets the location of the WSDL document for this Service.
      Returns:
        URL for the location of the WSDL document for this service.

    - #### getHandlerResolver

          public HandlerResolver getHandlerResolver()

      Returns the configured handler resolver.
      Returns:
        HandlerResolver The `HandlerResolver` being used by this `Service` instance, or `null` if there isn't one.

    - #### setHandlerResolver

          public void setHandlerResolver(HandlerResolver handlerResolver)

      Sets the `HandlerResolver` for this `Service` instance.

      The handler resolver, if present, will be called once for each proxy or dispatch instance that is created, and the handler chain returned by the resolver will be set on the instance.

      Parameters:
        `handlerResolver` - The `HandlerResolver` to use for all subsequently created proxy/dispatch objects.
      See Also:
        `HandlerResolver`

    - #### getExecutor

          public Executor getExecutor()

      Returns the executor for this `Service`instance. The executor is used for all asynchronous invocations that require callbacks.
      Returns:
        The `java.util.concurrent.Executor` to be used to invoke a callback.
      See Also:
        `Executor`

    - #### setExecutor

          public void setExecutor(Executor executor)

      Sets the executor for this `Service` instance. The executor is used for all asynchronous invocations that require callbacks.
      Parameters:
        `executor` - The `java.util.concurrent.Executor` to be used to invoke a callback.
      Throws:
        `SecurityException` - If the instance does not support setting an executor for security reasons (e.g. the necessary permissions are missing).
      See Also:
        `Executor`

    - #### create

          public static Service create(URL wsdlDocumentLocation,
                       QName serviceName)

      Creates a `Service` instance. The specified WSDL document location and service qualified name MUST uniquely identify a `wsdl:service` element.
      Parameters:
        `wsdlDocumentLocation` - `URL` for the WSDL document location for the service
        `serviceName` - `QName` for the service
      Throws:
        `WebServiceException` - If any error in creation of the specified service.

    - #### create

          public static Service create(URL wsdlDocumentLocation,
                       QName serviceName,
                       WebServiceFeature... features)

      Creates a `Service` instance. The created instance is configured with the web service features. The specified WSDL document location and service qualified name MUST uniquely identify a `wsdl:service` element.
      Parameters:
        `wsdlDocumentLocation` - `URL` for the WSDL document location for the service
        `serviceName` - `QName` for the service
        `features` - Web Service features that must be configured on the service. If the provider doesn't understand a feature, it must throw a WebServiceException.
      Throws:
        `WebServiceException` - If any error in creation of the specified service.
      Since:
        JAX-WS 2.2

    - #### create

          public static Service create(QName serviceName)

      Creates a `Service` instance.
      Parameters:
        `serviceName` - `QName` for the service
      Throws:
        `WebServiceException` - If any error in creation of the specified service

    - #### create

          public static Service create(QName serviceName,
                       WebServiceFeature... features)

      Creates a `Service` instance. The created instance is configured with the web service features.
      Parameters:
        `serviceName` - `QName` for the service
        `features` - Web Service features that must be configured on the service. If the provider doesn't understand a feature, it must throw a WebServiceException.
      Throws:
        `WebServiceException` - If any error in creation of the specified service
      Since:
        JAX-WS 2.2

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