1 /*
   2  * Copyright (c) 2005, 2017, Oracle and/or its affiliates. All rights reserved.
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * This code is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License version 2 only, as
   7  * published by the Free Software Foundation.  Oracle designates this
   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Oracle in the LICENSE file that accompanied this code.
  10  *
  11  * This code is distributed in the hope that it will be useful, but WITHOUT
  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  *
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 
  26 package javax.xml.ws;
  27 
  28 import javax.xml.namespace.QName;
  29 import java.util.Iterator;
  30 import javax.xml.ws.handler.HandlerResolver;
  31 import javax.xml.bind.JAXBContext;
  32 import javax.xml.ws.spi.ServiceDelegate;
  33 import javax.xml.ws.spi.Provider;
  34 
  35 /**
  36  * {@code Service} objects provide the client view of a Web service.
  37  * <p>{@code Service} acts as a factory of the following:
  38  * <ul>
  39  * <li>Proxies for a target service endpoint.</li>
  40  * <li>Instances of {@link javax.xml.ws.Dispatch} for
  41  *     dynamic message-oriented invocation of a remote
  42  *     operation.
  43  * </li>
  44  * </ul>
  45  *
  46  * <p>The ports available on a service can be enumerated using the
  47  * {@code getPorts} method. Alternatively, you can pass a
  48  * service endpoint interface to the unary {@code getPort} method
  49  * and let the runtime select a compatible port.
  50  *
  51  * <p>Handler chains for all the objects created by a {@code Service}
  52  * can be set by means of a {@code HandlerResolver}.
  53  *
  54  * <p>An {@code Executor} may be set on the service in order
  55  * to gain better control over the threads used to dispatch asynchronous
  56  * callbacks. For instance, thread pooling with certain parameters
  57  * can be enabled by creating a {@code ThreadPoolExecutor} and
  58  * registering it with the service.
  59  *
  60  * @since 1.6, JAX-WS 2.0
  61  *
  62  * @see javax.xml.ws.spi.Provider
  63  * @see javax.xml.ws.handler.HandlerResolver
  64  * @see java.util.concurrent.Executor
  65  **/
  66 public class Service {
  67 
  68     private ServiceDelegate delegate;
  69     /**
  70      * The orientation of a dynamic client or service. {@code MESSAGE} provides
  71      * access to entire protocol message, {@code PAYLOAD} to protocol message
  72      * payload only.
  73      **/
  74     public enum Mode {
  75 
  76         /**
  77          * Message mode.
  78          */
  79         MESSAGE,
  80 
  81         /**
  82          * Payload mode.
  83          */
  84         PAYLOAD }
  85 
  86     /**
  87      * Creates a {@code Service}.
  88      *
  89      * The specified WSDL document location and service qualified name MUST
  90      * uniquely identify a {@code wsdl:service} element.
  91      *
  92      * @param wsdlDocumentLocation {@code URL} for the WSDL document location
  93      *                             for the service
  94      * @param serviceName {@code QName} for the service
  95      */
  96     protected Service(java.net.URL wsdlDocumentLocation, QName serviceName) {
  97         delegate = Provider.provider().createServiceDelegate(wsdlDocumentLocation,
  98                 serviceName,
  99                 this.getClass());
 100     }
 101 
 102     /**
 103      * Creates a {@code Service}. The created instance is
 104      * configured with the web service features.
 105      *
 106      * The specified WSDL document location and service qualified name MUST
 107      * uniquely identify a {@code wsdl:service} element.
 108      *
 109      * @param wsdlDocumentLocation {@code URL} for the WSDL document location
 110      *                             for the service
 111      * @param serviceName {@code QName} for the service
 112      * @param features Web Service features that must be configured on
 113      *        the service. If the provider doesn't understand a feature,
 114      *        it must throw a WebServiceException.
 115      */
 116     protected Service(java.net.URL wsdlDocumentLocation, QName serviceName, WebServiceFeature ... features) {
 117         delegate = Provider.provider().createServiceDelegate(wsdlDocumentLocation,
 118                 serviceName,
 119                 this.getClass(), features);
 120     }
 121 
 122 
 123     /**
 124      * The {@code getPort} method returns a proxy. A service client
 125      * uses this proxy to invoke operations on the target
 126      * service endpoint. The {@code serviceEndpointInterface}
 127      * specifies the service endpoint interface that is supported by
 128      * the created dynamic proxy instance.
 129      *
 130      * @param <T> Service endpoint interface.
 131      * @param portName  Qualified name of the service endpoint in
 132      *                  the WSDL service description.
 133      * @param serviceEndpointInterface Service endpoint interface
 134      *                  supported by the dynamic proxy instance.
 135      * @return Object Proxy instance that
 136      *                supports the specified service endpoint
 137      *                interface.
 138      * @throws WebServiceException This exception is thrown in the
 139      *                  following cases:
 140      *                  <UL>
 141      *                  <LI>If there is an error in creation of
 142      *                      the proxy.
 143      *                  <LI>If there is any missing WSDL metadata
 144      *                      as required by this method.
 145      *                  <LI>If an illegal
 146      *                      {@code serviceEndpointInterface}
 147      *                      or {@code portName} is specified.
 148      *                  </UL>
 149      * @see java.lang.reflect.Proxy
 150      * @see java.lang.reflect.InvocationHandler
 151      **/
 152     public <T> T getPort(QName portName,
 153             Class<T> serviceEndpointInterface) {
 154         return delegate.getPort(portName, serviceEndpointInterface);
 155     }
 156 
 157     /**
 158      * The {@code getPort} method returns a proxy. A service client
 159      * uses this proxy to invoke operations on the target
 160      * service endpoint. The {@code serviceEndpointInterface}
 161      * specifies the service endpoint interface that is supported by
 162      * the created dynamic proxy instance.
 163      *
 164      * @param <T> Service endpoint interface.
 165      * @param portName  Qualified name of the service endpoint in
 166      *                  the WSDL service description.
 167      * @param serviceEndpointInterface Service endpoint interface
 168      *                  supported by the dynamic proxy instance.
 169      * @param features  A list of WebServiceFeatures to configure on the
 170      *                proxy.  Supported features not in the {@code features
 171      *                } parameter will have their default values.
 172      * @return Object Proxy instance that
 173      *                supports the specified service endpoint
 174      *                interface.
 175      * @throws WebServiceException This exception is thrown in the
 176      *                  following cases:
 177      *                  <UL>
 178      *                  <LI>If there is an error in creation of
 179      *                      the proxy.
 180      *                  <LI>If there is any missing WSDL metadata
 181      *                      as required by this method.
 182      *                  <LI>If an illegal
 183      *                      {@code serviceEndpointInterface}
 184      *                      or {@code portName} is specified.
 185      *                  <LI>If a feature is enabled that is not compatible
 186      *                      with this port or is unsupported.
 187      *                  </UL>
 188      * @see java.lang.reflect.Proxy
 189      * @see java.lang.reflect.InvocationHandler
 190      * @see WebServiceFeature
 191      *
 192      * @since 1.6, JAX-WS 2.1
 193      **/
 194     public <T> T getPort(QName portName,
 195             Class<T> serviceEndpointInterface, WebServiceFeature... features) {
 196         return delegate.getPort(portName, serviceEndpointInterface, features);
 197     }
 198 
 199 
 200     /**
 201      * The {@code getPort} method returns a proxy. The parameter
 202      * {@code serviceEndpointInterface} specifies the service
 203      * endpoint interface that is supported by the returned proxy.
 204      * In the implementation of this method, the JAX-WS
 205      * runtime system takes the responsibility of selecting a protocol
 206      * binding (and a port) and configuring the proxy accordingly.
 207      * The returned proxy should not be reconfigured by the client.
 208      *
 209      * @param <T> Service endpoint interface.
 210      * @param serviceEndpointInterface Service endpoint interface.
 211      * @return Object instance that supports the
 212      *                  specified service endpoint interface.
 213      * @throws WebServiceException
 214      *                  <UL>
 215      *                  <LI>If there is an error during creation
 216      *                      of the proxy.
 217      *                  <LI>If there is any missing WSDL metadata
 218      *                      as required by this method.
 219      *                  <LI>If an illegal
 220      *                      {@code serviceEndpointInterface}
 221      *                      is specified.
 222      *                  </UL>
 223      **/
 224     public <T> T getPort(Class<T> serviceEndpointInterface) {
 225         return delegate.getPort(serviceEndpointInterface);
 226     }
 227 
 228 
 229     /**
 230      * The {@code getPort} method returns a proxy. The parameter
 231      * {@code serviceEndpointInterface} specifies the service
 232      * endpoint interface that is supported by the returned proxy.
 233      * In the implementation of this method, the JAX-WS
 234      * runtime system takes the responsibility of selecting a protocol
 235      * binding (and a port) and configuring the proxy accordingly.
 236      * The returned proxy should not be reconfigured by the client.
 237      *
 238      * @param <T> Service endpoint interface.
 239      * @param serviceEndpointInterface Service endpoint interface.
 240      * @param features  A list of WebServiceFeatures to configure on the
 241      *                proxy.  Supported features not in the {@code features
 242      *                } parameter will have their default values.
 243      * @return Object instance that supports the
 244      *                  specified service endpoint interface.
 245      * @throws WebServiceException
 246      *                  <UL>
 247      *                  <LI>If there is an error during creation
 248      *                      of the proxy.
 249      *                  <LI>If there is any missing WSDL metadata
 250      *                      as required by this method.
 251      *                  <LI>If an illegal
 252      *                      {@code serviceEndpointInterface}
 253      *                      is specified.
 254      *                  <LI>If a feature is enabled that is not compatible
 255      *                      with this port or is unsupported.
 256      *                  </UL>
 257      *
 258      * @see WebServiceFeature
 259      *
 260      * @since 1.6, JAX-WS 2.1
 261      **/
 262     public <T> T getPort(Class<T> serviceEndpointInterface,
 263             WebServiceFeature... features) {
 264         return delegate.getPort(serviceEndpointInterface, features);
 265     }
 266 
 267 
 268     /**
 269      * The {@code getPort} method returns a proxy.
 270      * The parameter {@code endpointReference} specifies the
 271      * endpoint that will be invoked by the returned proxy.  If there
 272      * are any reference parameters in the
 273      * {@code endpointReference}, then those reference
 274      * parameters MUST appear as SOAP headers, indicating them to be
 275      * reference parameters, on all messages sent to the endpoint.
 276      * The {@code endpointReference's} address MUST be used
 277      * for invocations on the endpoint.
 278      * The parameter {@code serviceEndpointInterface} specifies
 279      * the service endpoint interface that is supported by the
 280      * returned proxy.
 281      * In the implementation of this method, the JAX-WS
 282      * runtime system takes the responsibility of selecting a protocol
 283      * binding (and a port) and configuring the proxy accordingly from
 284      * the WSDL associated with this {@code Service} instance or
 285      * from the metadata from the {@code endpointReference}.
 286      * If this {@code Service} instance has a WSDL and
 287      * the {@code endpointReference} metadata
 288      * also has a WSDL, then the WSDL from this instance MUST be used.
 289      * If this {@code Service} instance does not have a WSDL and
 290      * the {@code endpointReference} does have a WSDL, then the
 291      * WSDL from the {@code endpointReference} MAY be used.
 292      * The returned proxy should not be reconfigured by the client.
 293      * If this {@code Service} instance has a known proxy
 294      * port that matches the information contained in
 295      * the WSDL,
 296      * then that proxy is returned, otherwise a WebServiceException
 297      * is thrown.
 298      * <p>
 299      * Calling this method has the same behavior as the following
 300      * <pre>
 301      * {@code port = service.getPort(portName, serviceEndpointInterface);}
 302      * </pre>
 303      * where the {@code portName} is retrieved from the
 304      * metadata of the {@code endpointReference} or from the
 305      * {@code serviceEndpointInterface} and the WSDL
 306      * associated with this {@code Service} instance.
 307      *
 308      * @param <T> Service endpoint interface.
 309      * @param endpointReference  The {@code EndpointReference}
 310      * for the target service endpoint that will be invoked by the
 311      * returned proxy.
 312      * @param serviceEndpointInterface Service endpoint interface.
 313      * @param features  A list of {@code WebServiceFeatures} to configure on the
 314      *                proxy.  Supported features not in the {@code features
 315      *                } parameter will have their default values.
 316      * @return Object Proxy instance that supports the
 317      *                  specified service endpoint interface.
 318      * @throws WebServiceException
 319      *                  <UL>
 320      *                  <LI>If there is an error during creation
 321      *                      of the proxy.
 322      *                  <LI>If there is any missing WSDL metadata
 323      *                      as required by this method.
 324      *                  <LI>If the {@code endpointReference} metadata does
 325      *                      not match the {@code serviceName} of this
 326      *                      {@code Service} instance.
 327      *                  <LI>If a {@code portName} cannot be extracted
 328      *                      from the WSDL or {@code endpointReference} metadata.
 329      *                  <LI>If an invalid
 330      *                      {@code endpointReference}
 331      *                      is specified.
 332      *                  <LI>If an invalid
 333      *                      {@code serviceEndpointInterface}
 334      *                      is specified.
 335      *                  <LI>If a feature is enabled that is not compatible
 336      *                      with this port or is unsupported.
 337      *                  </UL>
 338      *
 339      * @since 1.6, JAX-WS 2.1
 340      **/
 341     public <T> T getPort(EndpointReference endpointReference,
 342            Class<T> serviceEndpointInterface, WebServiceFeature... features) {
 343         return delegate.getPort(endpointReference, serviceEndpointInterface, features);
 344     }
 345 
 346     /**
 347      * Creates a new port for the service. Ports created in this way contain
 348      * no WSDL port type information and can only be used for creating
 349      * {@code Dispatch}instances.
 350      *
 351      * @param portName  Qualified name for the target service endpoint.
 352      * @param bindingId A String identifier of a binding.
 353      * @param endpointAddress Address of the target service endpoint as a URI.
 354      * @throws WebServiceException If any error in the creation of
 355      * the port.
 356      *
 357      * @see javax.xml.ws.soap.SOAPBinding#SOAP11HTTP_BINDING
 358      * @see javax.xml.ws.soap.SOAPBinding#SOAP12HTTP_BINDING
 359      * @see javax.xml.ws.http.HTTPBinding#HTTP_BINDING
 360      **/
 361     public void addPort(QName portName, String bindingId, String endpointAddress) {
 362         delegate.addPort(portName, bindingId, endpointAddress);
 363     }
 364 
 365 
 366     /**
 367      * Creates a {@code Dispatch} instance for use with objects of
 368      * the client's choosing.
 369      *
 370      * @param <T> The type of the message or payload
 371      * @param portName  Qualified name for the target service endpoint
 372      * @param type The class of object used for messages or message
 373      * payloads. Implementations are required to support
 374      * {@code javax.xml.transform.Source}, {@code javax.xml.soap.SOAPMessage}
 375      * and {@code javax.activation.DataSource}, depending on
 376      * the binding in use.
 377      * @param mode Controls whether the created dispatch instance is message
 378      * or payload oriented, i.e. whether the client will work with complete
 379      * protocol messages or message payloads. E.g. when using the SOAP
 380      * protocol, this parameter controls whether the client will work with
 381      * SOAP messages or the contents of a SOAP body. Mode MUST be MESSAGE
 382      * when type is SOAPMessage.
 383      *
 384      * @return Dispatch instance.
 385      * @throws WebServiceException If any error in the creation of
 386      *                  the {@code Dispatch} object.
 387      *
 388      * @see javax.xml.transform.Source
 389      * @see javax.xml.soap.SOAPMessage
 390      **/
 391     public <T> Dispatch<T> createDispatch(QName portName, Class<T> type, Mode mode) {
 392         return delegate.createDispatch(portName, type, mode);
 393     }
 394 
 395 
 396     /**
 397      * Creates a {@code Dispatch} instance for use with objects of
 398      * the client's choosing.
 399      *
 400      * @param <T> The type of the message or payload
 401      * @param portName  Qualified name for the target service endpoint
 402      * @param type The class of object used for messages or message
 403      * payloads. Implementations are required to support
 404      * {@code javax.xml.transform.Source} and {@code javax.xml.soap.SOAPMessage}.
 405      * @param mode Controls whether the created dispatch instance is message
 406      * or payload oriented, i.e. whether the client will work with complete
 407      * protocol messages or message payloads. E.g. when using the SOAP
 408      * protocol, this parameter controls whether the client will work with
 409      * SOAP messages or the contents of a SOAP body. Mode MUST be {@code MESSAGE}
 410      * when type is {@code SOAPMessage}.
 411      * @param features  A list of {@code WebServiceFeatures} to configure on the
 412      *                proxy.  Supported features not in the {@code features
 413      *                } parameter will have their default values.
 414      *
 415      * @return Dispatch instance.
 416      * @throws WebServiceException If any error in the creation of
 417      *                  the {@code Dispatch} object or if a
 418      *                  feature is enabled that is not compatible with
 419      *                  this port or is unsupported.
 420      *
 421      * @see javax.xml.transform.Source
 422      * @see javax.xml.soap.SOAPMessage
 423      * @see WebServiceFeature
 424      *
 425      * @since 1.6, JAX-WS 2.1
 426      **/
 427     public <T> Dispatch<T> createDispatch(QName portName, Class<T> type,
 428             Service.Mode mode, WebServiceFeature... features) {
 429         return delegate.createDispatch(portName, type, mode, features);
 430     }
 431 
 432 
 433     /**
 434      * Creates a {@code Dispatch} instance for use with objects of
 435      * the client's choosing. If there
 436      * are any reference parameters in the
 437      * {@code endpointReference}, then those reference
 438      * parameters MUST appear as SOAP headers, indicating them to be
 439      * reference parameters, on all messages sent to the endpoint.
 440      * The {@code endpointReference's} address MUST be used
 441      * for invocations on the endpoint.
 442      * In the implementation of this method, the JAX-WS
 443      * runtime system takes the responsibility of selecting a protocol
 444      * binding (and a port) and configuring the dispatch accordingly from
 445      * the WSDL associated with this {@code Service} instance or
 446      * from the metadata from the {@code endpointReference}.
 447      * If this {@code Service} instance has a WSDL and
 448      * the {@code endpointReference}
 449      * also has a WSDL in its metadata, then the WSDL from this instance MUST be used.
 450      * If this {@code Service} instance does not have a WSDL and
 451      * the {@code endpointReference} does have a WSDL, then the
 452      * WSDL from the {@code endpointReference} MAY be used.
 453      * An implementation MUST be able to retrieve the {@code portName} from the
 454      * {@code endpointReference} metadata.
 455      * <p>
 456      * This method behaves the same as calling
 457      * <pre>
 458      * {@code dispatch = service.createDispatch(portName, type, mode, features);}
 459      * </pre>
 460      * where the {@code portName} is retrieved from the
 461      * WSDL or {@code EndpointReference} metadata.
 462      *
 463      * @param <T> The type of the message or payload
 464      * @param endpointReference  The {@code EndpointReference}
 465      * for the target service endpoint that will be invoked by the
 466      * returned {@code Dispatch} object.
 467      * @param type The class of object used to messages or message
 468      * payloads. Implementations are required to support
 469      * {@code javax.xml.transform.Source} and {@code javax.xml.soap.SOAPMessage}.
 470      * @param mode Controls whether the created dispatch instance is message
 471      * or payload oriented, i.e. whether the client will work with complete
 472      * protocol messages or message payloads. E.g. when using the SOAP
 473      * protocol, this parameter controls whether the client will work with
 474      * SOAP messages or the contents of a SOAP body. Mode MUST be {@code MESSAGE}
 475      * when type is {@code SOAPMessage}.
 476      * @param features  An array of {@code WebServiceFeatures} to configure on the
 477      *                proxy.  Supported features not in the {@code features
 478      *                } parameter will have their default values.
 479      *
 480      * @return Dispatch instance
 481      * @throws WebServiceException
 482      *                  <UL>
 483      *                    <LI>If there is any missing WSDL metadata
 484      *                      as required by this method.
 485      *                    <li>If the {@code endpointReference} metadata does
 486      *                      not match the {@code serviceName} or {@code portName}
 487      *                      of a WSDL associated
 488      *                      with this {@code Service} instance.
 489      *                    <li>If the {@code portName} cannot be determined
 490      *                    from the {@code EndpointReference} metadata.
 491      *                    <li>If any error in the creation of
 492      *                     the {@code Dispatch} object.
 493      *                    <li>If a feature is enabled that is not
 494      *                    compatible with this port or is unsupported.
 495      *                  </UL>
 496      *
 497      * @see javax.xml.transform.Source
 498      * @see javax.xml.soap.SOAPMessage
 499      * @see WebServiceFeature
 500      *
 501      * @since 1.6, JAX-WS 2.1
 502      **/
 503     public <T> Dispatch<T> createDispatch(EndpointReference endpointReference,
 504             Class<T> type, Service.Mode mode,
 505             WebServiceFeature... features) {
 506         return delegate.createDispatch(endpointReference, type, mode, features);
 507     }
 508 
 509     /**
 510      * Creates a {@code Dispatch} instance for use with JAXB
 511      * generated objects.
 512      *
 513      * @param portName  Qualified name for the target service endpoint
 514      * @param context The JAXB context used to marshall and unmarshall
 515      * messages or message payloads.
 516      * @param mode Controls whether the created dispatch instance is message
 517      * or payload oriented, i.e. whether the client will work with complete
 518      * protocol messages or message payloads. E.g. when using the SOAP
 519      * protocol, this parameter controls whether the client will work with
 520      * SOAP messages or the contents of a SOAP body.
 521      *
 522      * @return Dispatch instance.
 523      * @throws WebServiceException If any error in the creation of
 524      *                  the {@code Dispatch} object.
 525      *
 526      * @see javax.xml.bind.JAXBContext
 527      **/
 528     public Dispatch<Object> createDispatch(QName portName, JAXBContext context,
 529             Mode mode) {
 530         return delegate.createDispatch(portName, context,  mode);
 531     }
 532 
 533 
 534     /**
 535      * Creates a {@code Dispatch} instance for use with JAXB
 536      * generated objects.
 537      *
 538      * @param portName  Qualified name for the target service endpoint
 539      * @param context The JAXB context used to marshall and unmarshall
 540      * messages or message payloads.
 541      * @param mode Controls whether the created dispatch instance is message
 542      * or payload oriented, i.e. whether the client will work with complete
 543      * protocol messages or message payloads. E.g. when using the SOAP
 544      * protocol, this parameter controls whether the client will work with
 545      * SOAP messages or the contents of a SOAP body.
 546      * @param features  A list of {@code WebServiceFeatures} to configure on the
 547      *                proxy.  Supported features not in the {@code features
 548      *                } parameter will have their default values.
 549      *
 550      * @return Dispatch instance.
 551      * @throws WebServiceException If any error in the creation of
 552      *                  the {@code Dispatch} object or if a
 553      *                  feature is enabled that is not compatible with
 554      *                  this port or is unsupported.
 555      *
 556      * @see javax.xml.bind.JAXBContext
 557      * @see WebServiceFeature
 558      *
 559      * @since 1.6, JAX-WS 2.1
 560      **/
 561     public Dispatch<Object> createDispatch(QName portName,
 562             JAXBContext context, Service.Mode mode, WebServiceFeature... features) {
 563         return delegate.createDispatch(portName, context, mode, features);
 564     }
 565 
 566 
 567     /**
 568      * Creates a {@code Dispatch} instance for use with JAXB
 569      * generated objects. If there
 570      * are any reference parameters in the
 571      * {@code endpointReference}, then those reference
 572      * parameters MUST appear as SOAP headers, indicating them to be
 573      * reference parameters, on all messages sent to the endpoint.
 574      * The {@code endpointReference's} address MUST be used
 575      * for invocations on the endpoint.
 576      * In the implementation of this method, the JAX-WS
 577      * runtime system takes the responsibility of selecting a protocol
 578      * binding (and a port) and configuring the dispatch accordingly from
 579      * the WSDL associated with this {@code Service} instance or
 580      * from the metadata from the {@code endpointReference}.
 581      * If this {@code Service} instance has a WSDL and
 582      * the {@code endpointReference}
 583      * also has a WSDL in its metadata, then the WSDL from this instance
 584      * MUST be used.
 585      * If this {@code Service} instance does not have a WSDL and
 586      * the {@code endpointReference} does have a WSDL, then the
 587      * WSDL from the {@code endpointReference} MAY be used.
 588      * An implementation MUST be able to retrieve the {@code portName} from the
 589      * {@code endpointReference} metadata.
 590      * <p>
 591      * This method behavies the same as calling
 592      * <pre>
 593      * {@code dispatch = service.createDispatch(portName, context, mode, features);}
 594      * </pre>
 595      * where the {@code portName} is retrieved from the
 596      * WSDL or {@code endpointReference} metadata.
 597      *
 598      * @param endpointReference  The {@code EndpointReference}
 599      * for the target service endpoint that will be invoked by the
 600      * returned {@code Dispatch} object.
 601      * @param context The JAXB context used to marshall and unmarshall
 602      * messages or message payloads.
 603      * @param mode Controls whether the created dispatch instance is message
 604      * or payload oriented, i.e. whether the client will work with complete
 605      * protocol messages or message payloads. E.g. when using the SOAP
 606      * protocol, this parameter controls whether the client will work with
 607      * SOAP messages or the contents of a SOAP body.
 608      * @param features  An array of {@code WebServiceFeatures} to configure on the
 609      *                proxy.  Supported features not in the {@code features
 610      *                } parameter will have their default values.
 611      *
 612      * @return Dispatch instance
 613      * @throws WebServiceException
 614      *                  <UL>
 615      *                    <li>If there is any missing WSDL metadata
 616      *                      as required by this method.
 617      *                    <li>If the {@code endpointReference} metadata does
 618      *                    not match the {@code serviceName} or {@code portName}
 619      *                    of a WSDL associated
 620      *                    with this {@code Service} instance.
 621      *                    <li>If the {@code portName} cannot be determined
 622      *                    from the {@code EndpointReference} metadata.
 623      *                    <li>If any error in the creation of
 624      *                    the {@code Dispatch} object.
 625      *                    <li>if a feature is enabled that is not
 626      *                    compatible with this port or is unsupported.
 627      *                  </UL>
 628      *
 629      * @see javax.xml.bind.JAXBContext
 630      * @see WebServiceFeature
 631      *
 632      * @since 1.6, JAX-WS 2.1
 633     **/
 634     public Dispatch<Object> createDispatch(EndpointReference endpointReference,
 635             JAXBContext context, Service.Mode mode,
 636             WebServiceFeature... features) {
 637         return delegate.createDispatch(endpointReference, context, mode, features);
 638     }
 639 
 640     /**
 641      * Gets the name of this service.
 642      * @return Qualified name of this service
 643      **/
 644     public QName getServiceName() {
 645         return delegate.getServiceName();
 646     }
 647 
 648     /**
 649      * Returns an {@code Iterator} for the list of
 650      * {@code QName}s of service endpoints grouped by this
 651      * service
 652      *
 653      * @return Returns {@code java.util.Iterator} with elements
 654      *         of type {@code javax.xml.namespace.QName}.
 655      * @throws WebServiceException If this Service class does not
 656      *         have access to the required WSDL metadata.
 657      **/
 658     public Iterator<javax.xml.namespace.QName> getPorts() {
 659         return delegate.getPorts();
 660     }
 661 
 662     /**
 663      * Gets the location of the WSDL document for this Service.
 664      *
 665      * @return URL for the location of the WSDL document for
 666      *         this service.
 667      **/
 668     public java.net.URL getWSDLDocumentLocation() {
 669         return delegate.getWSDLDocumentLocation();
 670     }
 671 
 672     /**
 673      * Returns the configured handler resolver.
 674      *
 675      * @return HandlerResolver The {@code HandlerResolver} being
 676      *         used by this {@code Service} instance, or {@code null}
 677      *         if there isn't one.
 678      **/
 679     public HandlerResolver getHandlerResolver() {
 680         return delegate.getHandlerResolver();
 681     }
 682 
 683     /**
 684      * Sets the {@code HandlerResolver} for this {@code Service}
 685      * instance.
 686      * <p>
 687      * The handler resolver, if present, will be called once for each
 688      * proxy or dispatch instance that is created, and the handler chain
 689      * returned by the resolver will be set on the instance.
 690      *
 691      * @param handlerResolver The {@code HandlerResolver} to use
 692      *        for all subsequently created proxy/dispatch objects.
 693      *
 694      * @see javax.xml.ws.handler.HandlerResolver
 695      **/
 696     public void setHandlerResolver(HandlerResolver handlerResolver) {
 697         delegate.setHandlerResolver(handlerResolver);
 698     }
 699 
 700     /**
 701      * Returns the executor for this {@code Service}instance.
 702      *
 703      * The executor is used for all asynchronous invocations that
 704      * require callbacks.
 705      *
 706      * @return The {@code java.util.concurrent.Executor} to be
 707      *         used to invoke a callback.
 708      *
 709      * @see java.util.concurrent.Executor
 710      **/
 711     public java.util.concurrent.Executor getExecutor() {
 712         return delegate.getExecutor();
 713     }
 714 
 715     /**
 716      * Sets the executor for this {@code Service} instance.
 717      *
 718      * The executor is used for all asynchronous invocations that
 719      * require callbacks.
 720      *
 721      * @param executor The {@code java.util.concurrent.Executor}
 722      *        to be used to invoke a callback.
 723      *
 724      * @throws SecurityException If the instance does not support
 725      *         setting an executor for security reasons (e.g. the
 726      *         necessary permissions are missing).
 727      *
 728      * @see java.util.concurrent.Executor
 729      **/
 730     public void setExecutor(java.util.concurrent.Executor executor) {
 731         delegate.setExecutor(executor);
 732     }
 733 
 734     /**
 735      * Creates a {@code Service} instance.
 736      *
 737      * The specified WSDL document location and service qualified name MUST
 738      * uniquely identify a {@code wsdl:service} element.
 739      *
 740      * @param wsdlDocumentLocation {@code URL} for the WSDL document location
 741      *                             for the service
 742      * @param serviceName {@code QName} for the service
 743      * @return Service instance
 744      * @throws WebServiceException If any error in creation of the
 745      *                    specified service.
 746      **/
 747     public static Service create(
 748             java.net.URL wsdlDocumentLocation,
 749             QName serviceName) {
 750         return new Service(wsdlDocumentLocation, serviceName);
 751     }
 752 
 753     /**
 754      * Creates a {@code Service} instance. The created instance is
 755      * configured with the web service features.
 756      *
 757      * The specified WSDL document location and service qualified name MUST
 758      * uniquely identify a {@code wsdl:service} element.
 759      *
 760      * @param wsdlDocumentLocation {@code URL} for the WSDL document location
 761      *                             for the service
 762      * @param serviceName {@code QName} for the service
 763      * @param features Web Service features that must be configured on
 764      *        the service. If the provider doesn't understand a feature,
 765      *        it must throw a WebServiceException.
 766      * @return Service instance configured with requested web service features
 767      * @throws WebServiceException If any error in creation of the
 768      *                    specified service.
 769      * @since 1.7, JAX-WS 2.2
 770      **/
 771     public static Service create(
 772             java.net.URL wsdlDocumentLocation,
 773             QName serviceName, WebServiceFeature ... features) {
 774         return new Service(wsdlDocumentLocation, serviceName, features);
 775     }
 776 
 777     /**
 778      * Creates a {@code Service} instance.
 779      *
 780      * @param serviceName {@code QName} for the service
 781      * @return Service instance
 782      * @throws WebServiceException If any error in creation of the
 783      *                    specified service
 784      */
 785     public static Service create(QName serviceName) {
 786         return new Service(null, serviceName);
 787     }
 788 
 789     /**
 790      * Creates a {@code Service} instance. The created instance is
 791      * configured with the web service features.
 792      *
 793      * @param serviceName {@code QName} for the service
 794      * @param features Web Service features that must be configured on
 795      *        the service. If the provider doesn't understand a feature,
 796      *        it must throw a WebServiceException.
 797      * @return Service instance configured with requested web service features
 798      * @throws WebServiceException If any error in creation of the
 799      *                    specified service
 800      *
 801      * @since 1.7, JAX-WS 2.2
 802      */
 803     public static Service create(QName serviceName, WebServiceFeature ... features) {
 804         return new Service(null, serviceName, features);
 805     }
 806 }
--- EOF ---