java/9 : java.xml.ws/javax/xml/ws/spi/ServiceDelegate.java

ServiceDelegate
https://openjdk.java.net/
GPLv2 + Classpath Exception
/*
 * Copyright (c) 2005, 2017, Oracle and/or its affiliates. All rights reserved.
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
 *
 * This code is free software; you can redistribute it and/or modify it
 * under the terms of the GNU General Public License version 2 only, as
 * published by the Free Software Foundation.  Oracle designates this
 * particular file as subject to the "Classpath" exception as provided
 * by Oracle in the LICENSE file that accompanied this code.
 *
 * This code is distributed in the hope that it will be useful, but WITHOUT
 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
 * version 2 for more details (a copy is included in the LICENSE file that
 * accompanied this code).
 *
 * You should have received a copy of the GNU General Public License version
 * 2 along with this work; if not, write to the Free Software Foundation,
 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
 *
 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
 * or visit www.oracle.com if you need additional information or have any
 * questions.
 */

package javax.xml.ws.spi;

import java.util.Iterator;
import javax.xml.namespace.QName;
import javax.xml.ws.Dispatch;
import javax.xml.ws.Service;
import javax.xml.ws.handler.HandlerResolver;
import javax.xml.ws.WebServiceFeature;
import javax.xml.bind.JAXBContext;
import javax.xml.ws.EndpointReference;
import javax.xml.ws.WebServiceException;


Service delegates are used internally by Service objects to allow pluggability of JAX-WS implementations.  Every Service object has its own delegate, created using the Provider.createServiceDelegate method. A Service object delegates all of its instance methods to its delegate. 
See Also: Service
Provider
Since: 1.6, JAX-WS 2.0/**
 * Service delegates are used internally by {@code Service} objects
 * to allow pluggability of JAX-WS implementations.
 * <p>
 * Every {@code Service} object has its own delegate, created using
 * the {@link javax.xml.ws.spi.Provider#createServiceDelegate} method. A {@code Service}
 * object delegates all of its instance methods to its delegate.
 *
 * @see javax.xml.ws.Service
 * @see javax.xml.ws.spi.Provider
 *
 * @since 1.6, JAX-WS 2.0
 */
public abstract class ServiceDelegate {

    Default constructor.
/**
     * Default constructor.
     */
    protected ServiceDelegate() {
    }

    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. 
Params: portName –  Qualified name of the service endpoint in
                 the WSDL service description
serviceEndpointInterface – Service endpoint interface
                 supported by the dynamic proxy
Type parameters: <T> – 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
Returns: Object Proxy instance that
               supports the specified service endpoint
               interface/**
     * The {@code getPort} method returns a proxy. A service client
     * uses this proxy to invoke operations on the target
     * service endpoint. The {@code serviceEndpointInterface}
     * specifies the service endpoint interface that is supported by
     * the created dynamic proxy instance.
     *
     * @param <T> Service endpoint interface
     * @param portName  Qualified name of the service endpoint in
     *                  the WSDL service description
     * @param serviceEndpointInterface Service endpoint interface
     *                  supported by the dynamic proxy
     * @return Object Proxy instance that
     *                supports the specified service endpoint
     *                interface
     * @throws WebServiceException This exception is thrown in the
     *                  following cases:
     *                  <UL>
     *                  <LI>If there is an error in creation of
     *                      the proxy
     *                  <LI>If there is any missing WSDL metadata
     *                      as required by this method
     *                  <LI>If an illegal
     *                      {@code serviceEndpointInterface}
     *                      or {@code portName} is specified
     *                  </UL>
     * @see java.lang.reflect.Proxy
     * @see java.lang.reflect.InvocationHandler
     **/
    public abstract <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. 
Params: portName –  Qualified name of the service endpoint in
                 the WSDL service description
serviceEndpointInterface – Service endpoint interface
                 supported by the dynamic proxy or instance
features –  A list of WebServiceFeatures to configure on the proxy. Supported features not in the features
                parameter will have their default values.
Type parameters: <T> – 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.
                 
See Also: Proxy
InvocationHandler
WebServiceFeature
Returns: Object Proxy instance that
               supports the specified service endpoint
               interface
Since: 1.6, JAX-WS 2.1/**
     * The {@code getPort} method returns a proxy. A service client
     * uses this proxy to invoke operations on the target
     * service endpoint. The {@code serviceEndpointInterface}
     * specifies the service endpoint interface that is supported by
     * the created dynamic proxy instance.
     *
     * @param <T> Service endpoint interface
     * @param portName  Qualified name of the service endpoint in
     *                  the WSDL service description
     * @param serviceEndpointInterface Service endpoint interface
     *                  supported by the dynamic proxy or instance
     * @param features  A list of WebServiceFeatures to configure on the
     *                proxy.  Supported features not in the {@code features
     *                } parameter will have their default values.
     * @return Object Proxy instance that
     *                supports the specified service endpoint
     *                interface
     * @throws WebServiceException This exception is thrown in the
     *                  following cases:
     *                  <UL>
     *                  <LI>If there is an error in creation of
     *                      the proxy
     *                  <LI>If there is any missing WSDL metadata
     *                      as required by this method
     *                  <LI>If an illegal
     *                      {@code serviceEndpointInterface}
     *                      or {@code portName} is specified
     *                  <LI>If a feature is enabled that is not compatible
     *                      with this port or is unsupported.
     *                  </UL>
     * @see java.lang.reflect.Proxy
     * @see java.lang.reflect.InvocationHandler
     * @see WebServiceFeature
     *
     * @since 1.6, JAX-WS 2.1
     **/
    public abstract <T> T getPort(QName portName,
            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. 
Params: 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.
Type parameters: <T> – 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.
                 
Returns: Object Proxy instance that supports the
                 specified service endpoint interface.
Since: 1.6, JAX-WS 2.1/**
     * The {@code getPort} method returns a proxy.
     * The parameter {@code endpointReference} specifies the
     * endpoint that will be invoked by the returned proxy.  If there
     * are any reference parameters in the
     * {@code endpointReference}, then those reference
     * parameters MUST appear as SOAP headers, indicating them to be
     * reference parameters, on all messages sent to the endpoint.
     * The {@code endpointReference's} address MUST be used
     * for invocations on the endpoint.
     * The parameter {@code 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 {@code Service} instance or
     * from the metadata from the {@code endpointReference}.
     * If this {@code Service} instance has a WSDL and
     * the {@code endpointReference} metadata
     * also has a WSDL, then the WSDL from this instance MUST be used.
     * If this {@code Service} instance does not have a WSDL and
     * the {@code endpointReference} does have a WSDL, then the
     * WSDL from the {@code endpointReference} MAY be used.
     * The returned proxy should not be reconfigured by the client.
     * If this {@code 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.
     * <p>
     * Calling this method has the same behavior as the following
     * <pre>
     * {@code port = service.getPort(portName, serviceEndpointInterface);}
     * </pre>
     * where the {@code portName} is retrieved from the
     * metadata of the {@code endpointReference} or from the
     * {@code serviceEndpointInterface} and the WSDL
     * associated with this {@code Service} instance.
     *
     * @param <T> Service endpoint interface.
     * @param endpointReference  The {@code EndpointReference}
     * for the target service endpoint that will be invoked by the
     * returned proxy.
     * @param serviceEndpointInterface Service endpoint interface.
     * @param features  A list of {@code WebServiceFeatures} to configure on the
     *                proxy.  Supported features not in the {@code features
     *                } parameter will have their default values.
     * @return Object Proxy instance that supports the
     *                  specified service endpoint interface.
     * @throws WebServiceException
     *                  <UL>
     *                  <LI>If there is an error during creation
     *                      of the proxy.
     *                  <LI>If there is any missing WSDL metadata
     *                      as required by this method.
     *                  <LI>If the {@code endpointReference} metadata does
     *                      not match the {@code serviceName} of this
     *                      {@code Service} instance.
     *                  <LI>If a {@code portName} cannot be extracted
     *                      from the WSDL or {@code endpointReference} metadata.
     *                  <LI>If an invalid
     *                      {@code endpointReference}
     *                      is specified.
     *                  <LI>If an invalid
     *                      {@code serviceEndpointInterface}
     *                      is specified.
     *                  <LI>If a feature is enabled that is not compatible
     *                      with this port or is unsupported.
     *                  </UL>
     *
     * @since 1.6, JAX-WS 2.1
     **/
    public abstract <T> T getPort(EndpointReference endpointReference,
           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. 
Params: serviceEndpointInterface – Service endpoint interface
Type parameters: <T> – 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 
Returns: Object instance that supports the
                 specified service endpoint interface/**
     * The {@code getPort} method returns a proxy. The parameter
     * {@code 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.
     *
     * @param <T> Service endpoint interface
     * @param serviceEndpointInterface Service endpoint interface
     * @return Object instance that supports the
     *                  specified service endpoint interface
     * @throws WebServiceException
     *                  <UL>
     *                  <LI>If there is an error during creation
     *                      of the proxy
     *                  <LI>If there is any missing WSDL metadata
     *                      as required by this method
     *                  <LI>If an illegal
     *                      {@code serviceEndpointInterface}
     *                      is specified
     *                  </UL>
     **/
    public abstract <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. 
Params: serviceEndpointInterface – Service endpoint interface
features –  An array of WebServiceFeatures to configure on the proxy. Supported features not in the features
                parameter will have their default values.
Type parameters: <T> – 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.
                 
See Also: WebServiceFeature
Returns: Object instance that supports the
                 specified service endpoint interface
Since: 1.6, JAX-WS 2.1/**
     * The {@code getPort} method returns a proxy. The parameter
     * {@code 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.
     *
     * @param <T> Service endpoint interface
     * @param serviceEndpointInterface Service endpoint interface
     * @param features  An array of {@code WebServiceFeatures} to configure on the
     *                proxy.  Supported features not in the {@code features
     *                } parameter will have their default values.
     * @return Object instance that supports the
     *                  specified service endpoint interface
     * @throws WebServiceException
     *                  <UL>
     *                  <LI>If there is an error during creation
     *                      of the proxy
     *                  <LI>If there is any missing WSDL metadata
     *                      as required by this method
     *                  <LI>If an illegal
     *                      {@code serviceEndpointInterface}
     *                      is specified
     *                  <LI>If a feature is enabled that is not compatible
     *                      with this port or is unsupported.
     *                  </UL>
     *
     * @see WebServiceFeature
     *
     * @since 1.6, JAX-WS 2.1
     **/
    public abstract <T> T getPort(Class<T> serviceEndpointInterface,
            WebServiceFeature... features);


    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 Dispatchinstances. 
Params: portName –  Qualified name for the target service endpoint
bindingId – A URI 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/**
     * 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
     * {@code Dispatch}instances.
     *
     * @param portName  Qualified name for the target service endpoint
     * @param bindingId A URI identifier of a binding.
     * @param endpointAddress Address of the target service endpoint as a URI
     * @throws WebServiceException If any error in the creation of
     * the port
     *
     * @see javax.xml.ws.soap.SOAPBinding#SOAP11HTTP_BINDING
     * @see javax.xml.ws.soap.SOAPBinding#SOAP12HTTP_BINDING
     * @see javax.xml.ws.http.HTTPBinding#HTTP_BINDING
     **/
    public abstract void addPort(QName portName, String bindingId,
            String endpointAddress);



    Creates a Dispatch instance for use with objects of the user's choosing. 
Params: 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 user will work with complete protocol messages or message payloads. E.g. when using the SOAP protocol, this parameter controls whether the user will work with SOAP messages or the contents of a SOAP body. Mode MUST be MESSAGE when type is SOAPMessage.
Type parameters: <T> – type used for messages or message payloads. Implementations are required to support javax.xml.transform.Source and javax.xml.soap.SOAPMessage.
Throws: WebServiceException – If any error in the creation of the Dispatch object
See Also: Source
SOAPMessage
Returns: Dispatch instance/**
     * Creates a {@code Dispatch} instance for use with objects of
     * the user's choosing.
     *
     * @param <T> type used for messages or message payloads. Implementations are required to
     * support {@code javax.xml.transform.Source} and {@code javax.xml.soap.SOAPMessage}.
     * @param portName  Qualified name for the target service endpoint
     * @param type The class of object used for messages or message
     * payloads. Implementations are required to support
     * {@code javax.xml.transform.Source} and {@code javax.xml.soap.SOAPMessage}.
     * @param mode Controls whether the created dispatch instance is message
     * or payload oriented, i.e. whether the user will work with complete
     * protocol messages or message payloads. E.g. when using the SOAP
     * protocol, this parameter controls whether the user will work with
     * SOAP messages or the contents of a SOAP body. Mode MUST be {@code MESSAGE}
     * when type is {@code SOAPMessage}.
     *
     * @return Dispatch instance
     * @throws WebServiceException If any error in the creation of
     *                  the {@code Dispatch} object
     * @see javax.xml.transform.Source
     * @see javax.xml.soap.SOAPMessage
     **/
    public abstract <T> Dispatch<T> createDispatch(QName portName, Class<T> type,
            Service.Mode mode);

    Creates a Dispatch instance for use with objects of the user's choosing. 
Params: 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 user will work with complete protocol messages or message payloads. E.g. when using the SOAP protocol, this parameter controls whether the user 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.
Type parameters: <T> – type used for messages or message payloads. Implementations are required to support javax.xml.transform.Source and javax.xml.soap.SOAPMessage.
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.
See Also: Source
SOAPMessage
WebServiceFeature
Returns: Dispatch instance
Since: 1.6, JAX-WS 2.1/**
     * Creates a {@code Dispatch} instance for use with objects of
     * the user's choosing.
     *
     * @param <T> type used for messages or message payloads. Implementations are required to
     * support {@code javax.xml.transform.Source} and {@code javax.xml.soap.SOAPMessage}.
     * @param portName  Qualified name for the target service endpoint
     * @param type The class of object used for messages or message
     * payloads. Implementations are required to support
     * {@code javax.xml.transform.Source} and {@code javax.xml.soap.SOAPMessage}.
     * @param mode Controls whether the created dispatch instance is message
     * or payload oriented, i.e. whether the user will work with complete
     * protocol messages or message payloads. E.g. when using the SOAP
     * protocol, this parameter controls whether the user will work with
     * SOAP messages or the contents of a SOAP body. Mode MUST be {@code MESSAGE}
     * when type is {@code SOAPMessage}.
     * @param features  A list of {@code WebServiceFeatures} to configure on the
     *                proxy.  Supported features not in the {@code features
     *                } parameter will have their default values.
     *
     * @return Dispatch instance
     * @throws WebServiceException If any error in the creation of
     *                  the {@code Dispatch} object or if a
     *                  feature is enabled that is not compatible with
     *                  this port or is unsupported.
     *
     * @see javax.xml.transform.Source
     * @see javax.xml.soap.SOAPMessage
     * @see WebServiceFeature
     *
     * @since 1.6, JAX-WS 2.1
     **/
    public abstract <T> Dispatch<T> createDispatch(QName portName, Class<T> type,
            Service.Mode mode, WebServiceFeature... features);

    Creates a Dispatch instance for use with objects of the user'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. 
Params: 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 user will work with complete protocol messages or message payloads. E.g. when using the SOAP protocol, this parameter controls whether the user 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.
Type parameters: <T> – type of object used to messages or message payloads. Implementations are required to support javax.xml.transform.Source and javax.xml.soap.SOAPMessage.
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.
                 
See Also: Source
SOAPMessage
WebServiceFeature
Returns: Dispatch instance
Since: 1.6, JAX-WS 2.1/**
     * Creates a {@code Dispatch} instance for use with objects of
     * the user's choosing. If there
     * are any reference parameters in the
     * {@code endpointReference}, then those reference
     * parameters MUST appear as SOAP headers, indicating them to be
     * reference parameters, on all messages sent to the endpoint.
     * The {@code 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 {@code Service} instance or
     * from the metadata from the {@code endpointReference}.
     * If this {@code Service} instance has a WSDL and
     * the {@code endpointReference}
     * also has a WSDL in its metadata, then the WSDL from this instance MUST be used.
     * If this {@code Service} instance does not have a WSDL and
     * the {@code endpointReference} does have a WSDL, then the
     * WSDL from the {@code endpointReference} MAY be used.
     * An implementation MUST be able to retrieve the {@code portName} from the
     * {@code endpointReference} metadata.
     * <p>
     * This method behaves the same as calling
     * <pre>
     * {@code dispatch = service.createDispatch(portName, type, mode, features);}
     * </pre>
     * where the {@code portName} is retrieved from the
     * WSDL or {@code EndpointReference} metadata.
     *
     * @param <T> type of object used to messages or message
     * payloads. Implementations are required to support
     * {@code javax.xml.transform.Source} and {@code javax.xml.soap.SOAPMessage}.
     * @param endpointReference  The {@code EndpointReference}
     * for the target service endpoint that will be invoked by the
     * returned {@code Dispatch} object.
     * @param type The class of object used to messages or message
     * payloads. Implementations are required to support
     * {@code javax.xml.transform.Source} and {@code javax.xml.soap.SOAPMessage}.
     * @param mode Controls whether the created dispatch instance is message
     * or payload oriented, i.e. whether the user will work with complete
     * protocol messages or message payloads. E.g. when using the SOAP
     * protocol, this parameter controls whether the user will work with
     * SOAP messages or the contents of a SOAP body. Mode MUST be {@code MESSAGE}
     * when type is {@code SOAPMessage}.
     * @param features  An array of {@code WebServiceFeatures} to configure on the
     *                proxy.  Supported features not in the {@code features
     *                } parameter will have their default values.
     *
     * @return Dispatch instance
     * @throws WebServiceException
     *                  <UL>
     *                    <LI>If there is any missing WSDL metadata
     *                      as required by this method.
     *                    <li>If the {@code endpointReference} metadata does
     *                      not match the {@code serviceName} or {@code portName}
     *                      of a WSDL associated
     *                      with this {@code Service} instance.
     *                    <li>If the {@code portName} cannot be determined
     *                    from the {@code EndpointReference} metadata.
     *                    <li>If any error in the creation of
     *                     the {@code Dispatch} object.
     *                    <li>If a feature is enabled that is not
     *                    compatible with this port or is unsupported.
     *                  </UL>
     *
     * @see javax.xml.transform.Source
     * @see javax.xml.soap.SOAPMessage
     * @see WebServiceFeature
     *
     * @since 1.6, JAX-WS 2.1
     **/
    public abstract <T> Dispatch<T> createDispatch(EndpointReference endpointReference,
            Class<T> type, Service.Mode mode,
            WebServiceFeature... features);



    Creates a Dispatch instance for use with JAXB generated objects. 
Params: 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 user will work with complete
protocol messages or message payloads. E.g. when using the SOAP
protocol, this parameter controls whether the user will work with
SOAP messages or the contents of a SOAP body.
Throws: WebServiceException – If any error in the creation of the Dispatch object
See Also: JAXBContext
Returns: Dispatch instance/**
     * Creates a {@code Dispatch} instance for use with JAXB
     * generated objects.
     *
     * @param portName  Qualified name for the target service endpoint
     * @param context The JAXB context used to marshall and unmarshall
     * messages or message payloads.
     * @param mode Controls whether the created dispatch instance is message
     * or payload oriented, i.e. whether the user will work with complete
     * protocol messages or message payloads. E.g. when using the SOAP
     * protocol, this parameter controls whether the user will work with
     * SOAP messages or the contents of a SOAP body.
     *
     * @return Dispatch instance
     * @throws WebServiceException If any error in the creation of
     *                  the {@code Dispatch} object
     *
     * @see javax.xml.bind.JAXBContext
     **/
    public abstract Dispatch<Object> createDispatch(QName portName,
            JAXBContext context, Service.Mode mode);


    Creates a Dispatch instance for use with JAXB generated objects. 
Params: 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 user will work with complete
protocol messages or message payloads. E.g. when using the SOAP
protocol, this parameter controls whether the user 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.
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.
See Also: JAXBContext
WebServiceFeature
Returns: Dispatch instance
Since: 1.6, JAX-WS 2.1/**
     * Creates a {@code Dispatch} instance for use with JAXB
     * generated objects.
     *
     * @param portName  Qualified name for the target service endpoint
     * @param context The JAXB context used to marshall and unmarshall
     * messages or message payloads.
     * @param mode Controls whether the created dispatch instance is message
     * or payload oriented, i.e. whether the user will work with complete
     * protocol messages or message payloads. E.g. when using the SOAP
     * protocol, this parameter controls whether the user will work with
     * SOAP messages or the contents of a SOAP body.
     * @param features  A list of {@code WebServiceFeatures} to configure on the
     *                proxy.  Supported features not in the {@code features
     *                } parameter will have their default values.
     *
     * @return Dispatch instance
     * @throws WebServiceException If any error in the creation of
     *                  the {@code Dispatch} object or if a
     *                  feature is enabled that is not compatible with
     *                  this port or is unsupported.
     *
     * @see javax.xml.bind.JAXBContext
     * @see WebServiceFeature
     *
     * @since 1.6, JAX-WS 2.1
     **/
    public abstract Dispatch<Object> createDispatch(QName portName,
            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. 
Params: 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 user will work with complete
protocol messages or message payloads. E.g. when using the SOAP
protocol, this parameter controls whether the user 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.
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.
                 
See Also: JAXBContext
WebServiceFeature
Returns: Dispatch instance
Since: 1.6, JAX-WS 2.1/**
     * Creates a {@code Dispatch} instance for use with JAXB
     * generated objects. If there
     * are any reference parameters in the
     * {@code endpointReference}, then those reference
     * parameters MUST appear as SOAP headers, indicating them to be
     * reference parameters, on all messages sent to the endpoint.
     * The {@code 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 {@code Service} instance or
     * from the metadata from the {@code endpointReference}.
     * If this {@code Service} instance has a WSDL and
     * the {@code endpointReference}
     * also has a WSDL in its metadata, then the WSDL from this instance
     * MUST be used.
     * If this {@code Service} instance does not have a WSDL and
     * the {@code endpointReference} does have a WSDL, then the
     * WSDL from the {@code endpointReference} MAY be used.
     * An implementation MUST be able to retrieve the {@code portName} from the
     * {@code endpointReference} metadata.
     * <p>
     * This method behavies the same as calling
     * <pre>
     * {@code dispatch = service.createDispatch(portName, context, mode, features);}
     * </pre>
     * where the {@code portName} is retrieved from the
     * WSDL or {@code endpointReference} metadata.
     *
     * @param endpointReference  The {@code EndpointReference}
     * for the target service endpoint that will be invoked by the
     * returned {@code Dispatch} object.
     * @param context The JAXB context used to marshall and unmarshall
     * messages or message payloads.
     * @param mode Controls whether the created dispatch instance is message
     * or payload oriented, i.e. whether the user will work with complete
     * protocol messages or message payloads. E.g. when using the SOAP
     * protocol, this parameter controls whether the user will work with
     * SOAP messages or the contents of a SOAP body.
     * @param features  An array of {@code WebServiceFeatures} to configure on the
     *                proxy.  Supported features not in the {@code features
     *                } parameter will have their default values.
     *
     * @return Dispatch instance
     * @throws WebServiceException
     *                  <UL>
     *                    <li>If there is any missing WSDL metadata
     *                      as required by this method.
     *                    <li>If the {@code endpointReference} metadata does
     *                    not match the {@code serviceName} or {@code portName}
     *                    of a WSDL associated
     *                    with this {@code Service} instance.
     *                    <li>If the {@code portName} cannot be determined
     *                    from the {@code EndpointReference} metadata.
     *                    <li>If any error in the creation of
     *                    the {@code Dispatch} object.
     *                    <li>if a feature is enabled that is not
     *                    compatible with this port or is unsupported.
     *                  </UL>
     *
     * @see javax.xml.bind.JAXBContext
     * @see WebServiceFeature
     *
     * @since 1.6, JAX-WS 2.1
    **/
    public abstract Dispatch<Object> createDispatch(EndpointReference endpointReference,
            JAXBContext context, Service.Mode mode,
            WebServiceFeature... features);


    Gets the name of this service.
Returns: Qualified name of this service/**
     * Gets the name of this service.
     * @return Qualified name of this service
     **/
    public abstract QName getServiceName();

    Returns an Iterator for the list of QNames of service endpoints grouped by this service 
Throws: WebServiceException – If this Service class does not
        have access to the required WSDL metadata
Returns: Returns java.util.Iterator with elements of type javax.xml.namespace.QName/**
     * Returns an {@code Iterator} for the list of
     * {@code QName}s of service endpoints grouped by this
     * service
     *
     * @return Returns {@code java.util.Iterator} with elements
     *         of type {@code javax.xml.namespace.QName}
     * @throws WebServiceException If this Service class does not
     *         have access to the required WSDL metadata
     **/
    public abstract Iterator<javax.xml.namespace.QName> getPorts();

    Gets the location of the WSDL document for this Service.
Returns: URL for the location of the WSDL document for
        this service/**
     * Gets the location of the WSDL document for this Service.
     *
     * @return URL for the location of the WSDL document for
     *         this service
     **/
    public abstract java.net.URL getWSDLDocumentLocation();

    Returns the configured handler resolver.
Returns: HandlerResolver The HandlerResolver being used by this Service instance, or null if there isn't one./**
     * Returns the configured handler resolver.
     *
     * @return HandlerResolver The {@code HandlerResolver} being
     *         used by this {@code Service} instance, or {@code null}
     *         if there isn't one.
     **/
    public abstract HandlerResolver getHandlerResolver();

    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.
Params: handlerResolver – The HandlerResolver to use for all subsequently created proxy/dispatch objects.
See Also: HandlerResolver/**
     * Sets the {@code HandlerResolver} for this {@code Service}
     * instance.
     * <p>
     * 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.
     *
     * @param handlerResolver The {@code HandlerResolver} to use
     *        for all subsequently created proxy/dispatch objects.
     *
     * @see javax.xml.ws.handler.HandlerResolver
     **/
    public abstract void setHandlerResolver(HandlerResolver handlerResolver);

    Returns the executor for this Serviceinstance. The executor is used for all asynchronous invocations that require callbacks. 
See Also: Executor
Returns: The java.util.concurrent.Executor to be used to invoke a callback./**
     * Returns the executor for this {@code Service}instance.
     *
     * The executor is used for all asynchronous invocations that
     * require callbacks.
     *
     * @return The {@code java.util.concurrent.Executor} to be
     *         used to invoke a callback.
     *
     * @see java.util.concurrent.Executor
     **/
    public abstract java.util.concurrent.Executor getExecutor();

    Sets the executor for this Service instance. The executor is used for all asynchronous invocations that require callbacks. 
Params: 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/**
     * Sets the executor for this {@code Service} instance.
     *
     * The executor is used for all asynchronous invocations that
     * require callbacks.
     *
     * @param executor The {@code 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 java.util.concurrent.Executor
     **/
    public abstract void setExecutor(java.util.concurrent.Executor executor);

}
Params:	portName – Qualified name of the service endpoint in the WSDL service description serviceEndpointInterface – Service endpoint interface supported by the dynamic proxy
Type parameters:	<T> – 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
Returns:	Object Proxy instance that supports the specified service endpoint interface
Params:	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.
Type parameters:	<T> – 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.
Returns:	Object Proxy instance that supports the specified service endpoint interface.
Since:	1.6, JAX-WS 2.1
Params:	serviceEndpointInterface – Service endpoint interface
Type parameters:	<T> – 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
Returns:	Object instance that supports the specified service endpoint interface
Params:	portName – Qualified name for the target service endpoint bindingId – A URI 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
Throws:	WebServiceException – If this Service class does not have access to the required WSDL metadata
Returns:	Returns `java.util.Iterator` with elements of type `javax.xml.namespace.QName`
Params:	handlerResolver – The `HandlerResolver` to use for all subsequently created proxy/dispatch objects.
See Also:	HandlerResolver
See Also:	Executor
Returns:	The `java.util.concurrent.Executor` to be used to invoke a callback.
Params:	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
/

java/ 9/ java.xml.ws/javax/xml/ws/spi/ServiceDelegate.java
