1 /*
   2  * Copyright (c) 2005, 2015, 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 { MESSAGE, PAYLOAD }
  75 
  76     protected Service(java.net.URL wsdlDocumentLocation, QName serviceName) {
  77         delegate = Provider.provider().createServiceDelegate(wsdlDocumentLocation,
  78                 serviceName,
  79                 this.getClass());
  80     }
  81 
  82     protected Service(java.net.URL wsdlDocumentLocation, QName serviceName, WebServiceFeature ... features) {
  83         delegate = Provider.provider().createServiceDelegate(wsdlDocumentLocation,
  84                 serviceName,
  85                 this.getClass(), features);
  86     }
  87 
  88 
  89     /**
  90      * The {@code getPort} method returns a proxy. A service client
  91      * uses this proxy to invoke operations on the target
  92      * service endpoint. The {@code serviceEndpointInterface}
  93      * specifies the service endpoint interface that is supported by
  94      * the created dynamic proxy instance.
  95      *
  96      * @param portName  Qualified name of the service endpoint in
  97      *                  the WSDL service description.
  98      * @param serviceEndpointInterface Service endpoint interface
  99      *                  supported by the dynamic proxy instance.
 100      * @return Object Proxy instance that
 101      *                supports the specified service endpoint
 102      *                interface.
 103      * @throws WebServiceException This exception is thrown in the
 104      *                  following cases:
 105      *                  <UL>
 106      *                  <LI>If there is an error in creation of
 107      *                      the proxy.
 108      *                  <LI>If there is any missing WSDL metadata
 109      *                      as required by this method.
 110      *                  <LI>If an illegal
 111      *                      {@code serviceEndpointInterface}
 112      *                      or {@code portName} is specified.
 113      *                  </UL>
 114      * @see java.lang.reflect.Proxy
 115      * @see java.lang.reflect.InvocationHandler
 116      **/
 117     public <T> T getPort(QName portName,
 118             Class<T> serviceEndpointInterface) {
 119         return delegate.getPort(portName, serviceEndpointInterface);
 120     }
 121 
 122     /**
 123      * The {@code getPort} method returns a proxy. A service client
 124      * uses this proxy to invoke operations on the target
 125      * service endpoint. The {@code serviceEndpointInterface}
 126      * specifies the service endpoint interface that is supported by
 127      * the created dynamic proxy instance.
 128      *
 129      * @param portName  Qualified name of the service endpoint in
 130      *                  the WSDL service description.
 131      * @param serviceEndpointInterface Service endpoint interface
 132      *                  supported by the dynamic proxy instance.
 133      * @param features  A list of WebServiceFeatures to configure on the
 134      *                proxy.  Supported features not in the {@code features
 135      *                } parameter will have their default values.
 136      * @return Object Proxy instance that
 137      *                supports the specified service endpoint
 138      *                interface.
 139      * @throws WebServiceException This exception is thrown in the
 140      *                  following cases:
 141      *                  <UL>
 142      *                  <LI>If there is an error in creation of
 143      *                      the proxy.
 144      *                  <LI>If there is any missing WSDL metadata
 145      *                      as required by this method.
 146      *                  <LI>If an illegal
 147      *                      {@code serviceEndpointInterface}
 148      *                      or {@code portName} is specified.
 149      *                  <LI>If a feature is enabled that is not compatible
 150      *                      with this port or is unsupported.
 151      *                  </UL>
 152      * @see java.lang.reflect.Proxy
 153      * @see java.lang.reflect.InvocationHandler
 154      * @see WebServiceFeature
 155      *
 156      * @since 1.6, JAX-WS 2.1
 157      **/
 158     public <T> T getPort(QName portName,
 159             Class<T> serviceEndpointInterface, WebServiceFeature... features) {
 160         return delegate.getPort(portName, serviceEndpointInterface, features);
 161     }
 162 
 163 
 164     /**
 165      * The {@code getPort} method returns a proxy. The parameter
 166      * {@code serviceEndpointInterface} specifies the service
 167      * endpoint interface that is supported by the returned proxy.
 168      * In the implementation of this method, the JAX-WS
 169      * runtime system takes the responsibility of selecting a protocol
 170      * binding (and a port) and configuring the proxy accordingly.
 171      * The returned proxy should not be reconfigured by the client.
 172      *
 173      * @param serviceEndpointInterface Service endpoint interface.
 174      * @return Object instance that supports the
 175      *                  specified service endpoint interface.
 176      * @throws WebServiceException
 177      *                  <UL>
 178      *                  <LI>If there is an error during creation
 179      *                      of 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      *                      is specified.
 185      *                  </UL>
 186      **/
 187     public <T> T getPort(Class<T> serviceEndpointInterface) {
 188         return delegate.getPort(serviceEndpointInterface);
 189     }
 190 
 191 
 192     /**
 193      * The {@code getPort} method returns a proxy. The parameter
 194      * {@code serviceEndpointInterface} specifies the service
 195      * endpoint interface that is supported by the returned proxy.
 196      * In the implementation of this method, the JAX-WS
 197      * runtime system takes the responsibility of selecting a protocol
 198      * binding (and a port) and configuring the proxy accordingly.
 199      * The returned proxy should not be reconfigured by the client.
 200      *
 201      * @param serviceEndpointInterface Service endpoint interface.
 202      * @param features  A list of WebServiceFeatures to configure on the
 203      *                proxy.  Supported features not in the {@code features
 204      *                } parameter will have their default values.
 205      * @return Object instance that supports the
 206      *                  specified service endpoint interface.
 207      * @throws WebServiceException
 208      *                  <UL>
 209      *                  <LI>If there is an error during creation
 210      *                      of the proxy.
 211      *                  <LI>If there is any missing WSDL metadata
 212      *                      as required by this method.
 213      *                  <LI>If an illegal
 214      *                      {@code serviceEndpointInterface}
 215      *                      is specified.
 216      *                  <LI>If a feature is enabled that is not compatible
 217      *                      with this port or is unsupported.
 218      *                  </UL>
 219      *
 220      * @see WebServiceFeature
 221      *
 222      * @since 1.6, JAX-WS 2.1
 223      **/
 224     public <T> T getPort(Class<T> serviceEndpointInterface,
 225             WebServiceFeature... features) {
 226         return delegate.getPort(serviceEndpointInterface, features);
 227     }
 228 
 229 
 230     /**
 231      * The {@code getPort} method returns a proxy.
 232      * The parameter {@code endpointReference} specifies the
 233      * endpoint that will be invoked by the returned proxy.  If there
 234      * are any reference parameters in the
 235      * {@code endpointReference}, then those reference
 236      * parameters MUST appear as SOAP headers, indicating them to be
 237      * reference parameters, on all messages sent to the endpoint.
 238      * The {@code endpointReference's} address MUST be used
 239      * for invocations on the endpoint.
 240      * The parameter {@code serviceEndpointInterface} specifies
 241      * the service endpoint interface that is supported by the
 242      * returned proxy.
 243      * In the implementation of this method, the JAX-WS
 244      * runtime system takes the responsibility of selecting a protocol
 245      * binding (and a port) and configuring the proxy accordingly from
 246      * the WSDL associated with this {@code Service} instance or
 247      * from the metadata from the {@code endpointReference}.
 248      * If this {@code Service} instance has a WSDL and
 249      * the {@code endpointReference} metadata
 250      * also has a WSDL, then the WSDL from this instance MUST be used.
 251      * If this {@code Service} instance does not have a WSDL and
 252      * the {@code endpointReference} does have a WSDL, then the
 253      * WSDL from the {@code endpointReference} MAY be used.
 254      * The returned proxy should not be reconfigured by the client.
 255      * If this {@code Service} instance has a known proxy
 256      * port that matches the information contained in
 257      * the WSDL,
 258      * then that proxy is returned, otherwise a WebServiceException
 259      * is thrown.
 260      * <p>
 261      * Calling this method has the same behavior as the following
 262      * <pre>
 263      * {@code port = service.getPort(portName, serviceEndpointInterface);}
 264      * </pre>
 265      * where the {@code portName} is retrieved from the
 266      * metadata of the {@code endpointReference} or from the
 267      * {@code serviceEndpointInterface} and the WSDL
 268      * associated with this {@code Service} instance.
 269      *
 270      * @param endpointReference  The {@code EndpointReference}
 271      * for the target service endpoint that will be invoked by the
 272      * returned proxy.
 273      * @param serviceEndpointInterface Service endpoint interface.
 274      * @param features  A list of {@code WebServiceFeatures} to configure on the
 275      *                proxy.  Supported features not in the {@code features
 276      *                } parameter will have their default values.
 277      * @return Object Proxy instance that supports the
 278      *                  specified service endpoint interface.
 279      * @throws WebServiceException
 280      *                  <UL>
 281      *                  <LI>If there is an error during creation
 282      *                      of the proxy.
 283      *                  <LI>If there is any missing WSDL metadata
 284      *                      as required by this method.
 285      *                  <LI>If the {@code endpointReference} metadata does
 286      *                      not match the {@code serviceName} of this
 287      *                      {@code Service} instance.
 288      *                  <LI>If a {@code portName} cannot be extracted
 289      *                      from the WSDL or {@code endpointReference} metadata.
 290      *                  <LI>If an invalid
 291      *                      {@code endpointReference}
 292      *                      is specified.
 293      *                  <LI>If an invalid
 294      *                      {@code serviceEndpointInterface}
 295      *                      is specified.
 296      *                  <LI>If a feature is enabled that is not compatible
 297      *                      with this port or is unsupported.
 298      *                  </UL>
 299      *
 300      * @since 1.6, JAX-WS 2.1
 301      **/
 302     public <T> T getPort(EndpointReference endpointReference,
 303            Class<T> serviceEndpointInterface, WebServiceFeature... features) {
 304         return delegate.getPort(endpointReference, serviceEndpointInterface, features);
 305     }
 306 
 307     /**
 308      * Creates a new port for the service. Ports created in this way contain
 309      * no WSDL port type information and can only be used for creating
 310      * {@code Dispatch}instances.
 311      *
 312      * @param portName  Qualified name for the target service endpoint.
 313      * @param bindingId A String identifier of a binding.
 314      * @param endpointAddress Address of the target service endpoint as a URI.
 315      * @throws WebServiceException If any error in the creation of
 316      * the port.
 317      *
 318      * @see javax.xml.ws.soap.SOAPBinding#SOAP11HTTP_BINDING
 319      * @see javax.xml.ws.soap.SOAPBinding#SOAP12HTTP_BINDING
 320      * @see javax.xml.ws.http.HTTPBinding#HTTP_BINDING
 321      **/
 322     public void addPort(QName portName, String bindingId, String endpointAddress) {
 323         delegate.addPort(portName, bindingId, endpointAddress);
 324     }
 325 
 326 
 327     /**
 328      * Creates a {@code Dispatch} instance for use with objects of
 329      * the client's choosing.
 330      *
 331      * @param portName  Qualified name for the target service endpoint
 332      * @param type The class of object used for messages or message
 333      * payloads. Implementations are required to support
 334      * {@code javax.xml.transform.Source}, {@code javax.xml.soap.SOAPMessage}
 335      * and {@code javax.activation.DataSource}, depending on
 336      * the binding in use.
 337      * @param mode Controls whether the created dispatch instance is message
 338      * or payload oriented, i.e. whether the client will work with complete
 339      * protocol messages or message payloads. E.g. when using the SOAP
 340      * protocol, this parameter controls whether the client will work with
 341      * SOAP messages or the contents of a SOAP body. Mode MUST be MESSAGE
 342      * when type is SOAPMessage.
 343      *
 344      * @return Dispatch instance.
 345      * @throws WebServiceException If any error in the creation of
 346      *                  the {@code Dispatch} object.
 347      *
 348      * @see javax.xml.transform.Source
 349      * @see javax.xml.soap.SOAPMessage
 350      **/
 351     public <T> Dispatch<T> createDispatch(QName portName, Class<T> type, Mode mode) {
 352         return delegate.createDispatch(portName, type, mode);
 353     }
 354 
 355 
 356     /**
 357      * Creates a {@code Dispatch} instance for use with objects of
 358      * the client's choosing.
 359      *
 360      * @param portName  Qualified name for the target service endpoint
 361      * @param type The class of object used for messages or message
 362      * payloads. Implementations are required to support
 363      * {@code javax.xml.transform.Source} and {@code javax.xml.soap.SOAPMessage}.
 364      * @param mode Controls whether the created dispatch instance is message
 365      * or payload oriented, i.e. whether the client will work with complete
 366      * protocol messages or message payloads. E.g. when using the SOAP
 367      * protocol, this parameter controls whether the client will work with
 368      * SOAP messages or the contents of a SOAP body. Mode MUST be {@code MESSAGE}
 369      * when type is {@code SOAPMessage}.
 370      * @param features  A list of {@code WebServiceFeatures} to configure on the
 371      *                proxy.  Supported features not in the {@code features
 372      *                } parameter will have their default values.
 373      *
 374      * @return Dispatch instance.
 375      * @throws WebServiceException If any error in the creation of
 376      *                  the {@code Dispatch} object or if a
 377      *                  feature is enabled that is not compatible with
 378      *                  this port or is unsupported.
 379      *
 380      * @see javax.xml.transform.Source
 381      * @see javax.xml.soap.SOAPMessage
 382      * @see WebServiceFeature
 383      *
 384      * @since 1.6, JAX-WS 2.1
 385      **/
 386     public <T> Dispatch<T> createDispatch(QName portName, Class<T> type,
 387             Service.Mode mode, WebServiceFeature... features) {
 388         return delegate.createDispatch(portName, type, mode, features);
 389     }
 390 
 391 
 392     /**
 393      * Creates a {@code Dispatch} instance for use with objects of
 394      * the client's choosing. If there
 395      * are any reference parameters in the
 396      * {@code endpointReference}, then those reference
 397      * parameters MUST appear as SOAP headers, indicating them to be
 398      * reference parameters, on all messages sent to the endpoint.
 399      * The {@code endpointReference's} address MUST be used
 400      * for invocations on the endpoint.
 401      * In the implementation of this method, the JAX-WS
 402      * runtime system takes the responsibility of selecting a protocol
 403      * binding (and a port) and configuring the dispatch accordingly from
 404      * the WSDL associated with this {@code Service} instance or
 405      * from the metadata from the {@code endpointReference}.
 406      * If this {@code Service} instance has a WSDL and
 407      * the {@code endpointReference}
 408      * also has a WSDL in its metadata, then the WSDL from this instance MUST be used.
 409      * If this {@code Service} instance does not have a WSDL and
 410      * the {@code endpointReference} does have a WSDL, then the
 411      * WSDL from the {@code endpointReference} MAY be used.
 412      * An implementation MUST be able to retrieve the {@code portName} from the
 413      * {@code endpointReference} metadata.
 414      * <p>
 415      * This method behaves the same as calling
 416      * <pre>
 417      * {@code dispatch = service.createDispatch(portName, type, mode, features);}
 418      * </pre>
 419      * where the {@code portName} is retrieved from the
 420      * WSDL or {@code EndpointReference} metadata.
 421      *
 422      * @param endpointReference  The {@code EndpointReference}
 423      * for the target service endpoint that will be invoked by the
 424      * returned {@code Dispatch} object.
 425      * @param type The class of object used to messages or message
 426      * payloads. Implementations are required to support
 427      * {@code javax.xml.transform.Source} and {@code javax.xml.soap.SOAPMessage}.
 428      * @param mode Controls whether the created dispatch instance is message
 429      * or payload oriented, i.e. whether the client will work with complete
 430      * protocol messages or message payloads. E.g. when using the SOAP
 431      * protocol, this parameter controls whether the client will work with
 432      * SOAP messages or the contents of a SOAP body. Mode MUST be {@code MESSAGE}
 433      * when type is {@code SOAPMessage}.
 434      * @param features  An array of {@code WebServiceFeatures} to configure on the
 435      *                proxy.  Supported features not in the {@code features
 436      *                } parameter will have their default values.
 437      *
 438      * @return Dispatch instance
 439      * @throws WebServiceException
 440      *                  <UL>
 441      *                    <LI>If there is any missing WSDL metadata
 442      *                      as required by this method.
 443      *                    <li>If the {@code endpointReference} metadata does
 444      *                      not match the {@code serviceName} or {@code portName}
 445      *                      of a WSDL associated
 446      *                      with this {@code Service} instance.
 447      *                    <li>If the {@code portName} cannot be determined
 448      *                    from the {@code EndpointReference} metadata.
 449      *                    <li>If any error in the creation of
 450      *                     the {@code Dispatch} object.
 451      *                    <li>If a feature is enabled that is not
 452      *                    compatible with this port or is unsupported.
 453      *                  </UL>
 454      *
 455      * @see javax.xml.transform.Source
 456      * @see javax.xml.soap.SOAPMessage
 457      * @see WebServiceFeature
 458      *
 459      * @since 1.6, JAX-WS 2.1
 460      **/
 461     public <T> Dispatch<T> createDispatch(EndpointReference endpointReference,
 462             Class<T> type, Service.Mode mode,
 463             WebServiceFeature... features) {
 464         return delegate.createDispatch(endpointReference, type, mode, features);
 465     }
 466 
 467     /**
 468      * Creates a {@code Dispatch} instance for use with JAXB
 469      * generated objects.
 470      *
 471      * @param portName  Qualified name for the target service endpoint
 472      * @param context The JAXB context used to marshall and unmarshall
 473      * messages or message payloads.
 474      * @param mode Controls whether the created dispatch instance is message
 475      * or payload oriented, i.e. whether the client will work with complete
 476      * protocol messages or message payloads. E.g. when using the SOAP
 477      * protocol, this parameter controls whether the client will work with
 478      * SOAP messages or the contents of a SOAP body.
 479      *
 480      * @return Dispatch instance.
 481      * @throws WebServiceException If any error in the creation of
 482      *                  the {@code Dispatch} object.
 483      *
 484      * @see javax.xml.bind.JAXBContext
 485      **/
 486     public Dispatch<Object> createDispatch(QName portName, JAXBContext context,
 487             Mode mode) {
 488         return delegate.createDispatch(portName, context,  mode);
 489     }
 490 
 491 
 492     /**
 493      * Creates a {@code Dispatch} instance for use with JAXB
 494      * generated objects.
 495      *
 496      * @param portName  Qualified name for the target service endpoint
 497      * @param context The JAXB context used to marshall and unmarshall
 498      * messages or message payloads.
 499      * @param mode Controls whether the created dispatch instance is message
 500      * or payload oriented, i.e. whether the client will work with complete
 501      * protocol messages or message payloads. E.g. when using the SOAP
 502      * protocol, this parameter controls whether the client will work with
 503      * SOAP messages or the contents of a SOAP body.
 504      * @param features  A list of {@code WebServiceFeatures} to configure on the
 505      *                proxy.  Supported features not in the {@code features
 506      *                } parameter will have their default values.
 507      *
 508      * @return Dispatch instance.
 509      * @throws WebServiceException If any error in the creation of
 510      *                  the {@code Dispatch} object or if a
 511      *                  feature is enabled that is not compatible with
 512      *                  this port or is unsupported.
 513      *
 514      * @see javax.xml.bind.JAXBContext
 515      * @see WebServiceFeature
 516      *
 517      * @since 1.6, JAX-WS 2.1
 518      **/
 519     public Dispatch<Object> createDispatch(QName portName,
 520             JAXBContext context, Service.Mode mode, WebServiceFeature... features) {
 521         return delegate.createDispatch(portName, context, mode, features);
 522     }
 523 
 524 
 525     /**
 526      * Creates a {@code Dispatch} instance for use with JAXB
 527      * generated objects. If there
 528      * are any reference parameters in the
 529      * {@code endpointReference}, then those reference
 530      * parameters MUST appear as SOAP headers, indicating them to be
 531      * reference parameters, on all messages sent to the endpoint.
 532      * The {@code endpointReference's} address MUST be used
 533      * for invocations on the endpoint.
 534      * In the implementation of this method, the JAX-WS
 535      * runtime system takes the responsibility of selecting a protocol
 536      * binding (and a port) and configuring the dispatch accordingly from
 537      * the WSDL associated with this {@code Service} instance or
 538      * from the metadata from the {@code endpointReference}.
 539      * If this {@code Service} instance has a WSDL and
 540      * the {@code endpointReference}
 541      * also has a WSDL in its metadata, then the WSDL from this instance
 542      * MUST be used.
 543      * If this {@code Service} instance does not have a WSDL and
 544      * the {@code endpointReference} does have a WSDL, then the
 545      * WSDL from the {@code endpointReference} MAY be used.
 546      * An implementation MUST be able to retrieve the {@code portName} from the
 547      * {@code endpointReference} metadata.
 548      * <p>
 549      * This method behavies the same as calling
 550      * <pre>
 551      * {@code dispatch = service.createDispatch(portName, context, mode, features);}
 552      * </pre>
 553      * where the {@code portName} is retrieved from the
 554      * WSDL or {@code endpointReference} metadata.
 555      *
 556      * @param endpointReference  The {@code EndpointReference}
 557      * for the target service endpoint that will be invoked by the
 558      * returned {@code Dispatch} object.
 559      * @param context The JAXB context used to marshall and unmarshall
 560      * messages or message payloads.
 561      * @param mode Controls whether the created dispatch instance is message
 562      * or payload oriented, i.e. whether the client will work with complete
 563      * protocol messages or message payloads. E.g. when using the SOAP
 564      * protocol, this parameter controls whether the client will work with
 565      * SOAP messages or the contents of a SOAP body.
 566      * @param features  An array of {@code WebServiceFeatures} to configure on the
 567      *                proxy.  Supported features not in the {@code features
 568      *                } parameter will have their default values.
 569      *
 570      * @return Dispatch instance
 571      * @throws WebServiceException
 572      *                  <UL>
 573      *                    <li>If there is any missing WSDL metadata
 574      *                      as required by this method.
 575      *                    <li>If the {@code endpointReference} metadata does
 576      *                    not match the {@code serviceName} or {@code portName}
 577      *                    of a WSDL associated
 578      *                    with this {@code Service} instance.
 579      *                    <li>If the {@code portName} cannot be determined
 580      *                    from the {@code EndpointReference} metadata.
 581      *                    <li>If any error in the creation of
 582      *                    the {@code Dispatch} object.
 583      *                    <li>if a feature is enabled that is not
 584      *                    compatible with this port or is unsupported.
 585      *                  </UL>
 586      *
 587      * @see javax.xml.bind.JAXBContext
 588      * @see WebServiceFeature
 589      *
 590      * @since 1.6, JAX-WS 2.1
 591     **/
 592     public Dispatch<Object> createDispatch(EndpointReference endpointReference,
 593             JAXBContext context, Service.Mode mode,
 594             WebServiceFeature... features) {
 595         return delegate.createDispatch(endpointReference, context, mode, features);
 596     }
 597 
 598     /**
 599      * Gets the name of this service.
 600      * @return Qualified name of this service
 601      **/
 602     public QName getServiceName() {
 603         return delegate.getServiceName();
 604     }
 605 
 606     /**
 607      * Returns an {@code Iterator} for the list of
 608      * {@code QName}s of service endpoints grouped by this
 609      * service
 610      *
 611      * @return Returns {@code java.util.Iterator} with elements
 612      *         of type {@code javax.xml.namespace.QName}.
 613      * @throws WebServiceException If this Service class does not
 614      *         have access to the required WSDL metadata.
 615      **/
 616     public Iterator<javax.xml.namespace.QName> getPorts() {
 617         return delegate.getPorts();
 618     }
 619 
 620     /**
 621      * Gets the location of the WSDL document for this Service.
 622      *
 623      * @return URL for the location of the WSDL document for
 624      *         this service.
 625      **/
 626     public java.net.URL getWSDLDocumentLocation() {
 627         return delegate.getWSDLDocumentLocation();
 628     }
 629 
 630     /**
 631      * Returns the configured handler resolver.
 632      *
 633      * @return HandlerResolver The {@code HandlerResolver} being
 634      *         used by this {@code Service} instance, or {@code null}
 635      *         if there isn't one.
 636      **/
 637     public HandlerResolver getHandlerResolver() {
 638         return delegate.getHandlerResolver();
 639     }
 640 
 641     /**
 642      * Sets the {@code HandlerResolver} for this {@code Service}
 643      * instance.
 644      * <p>
 645      * The handler resolver, if present, will be called once for each
 646      * proxy or dispatch instance that is created, and the handler chain
 647      * returned by the resolver will be set on the instance.
 648      *
 649      * @param handlerResolver The {@code HandlerResolver} to use
 650      *        for all subsequently created proxy/dispatch objects.
 651      *
 652      * @see javax.xml.ws.handler.HandlerResolver
 653      **/
 654     public void setHandlerResolver(HandlerResolver handlerResolver) {
 655         delegate.setHandlerResolver(handlerResolver);
 656     }
 657 
 658     /**
 659      * Returns the executor for this {@code Service}instance.
 660      *
 661      * The executor is used for all asynchronous invocations that
 662      * require callbacks.
 663      *
 664      * @return The {@code java.util.concurrent.Executor} to be
 665      *         used to invoke a callback.
 666      *
 667      * @see java.util.concurrent.Executor
 668      **/
 669     public java.util.concurrent.Executor getExecutor() {
 670         return delegate.getExecutor();
 671     }
 672 
 673     /**
 674      * Sets the executor for this {@code Service} instance.
 675      *
 676      * The executor is used for all asynchronous invocations that
 677      * require callbacks.
 678      *
 679      * @param executor The {@code java.util.concurrent.Executor}
 680      *        to be used to invoke a callback.
 681      *
 682      * @throws SecurityException If the instance does not support
 683      *         setting an executor for security reasons (e.g. the
 684      *         necessary permissions are missing).
 685      *
 686      * @see java.util.concurrent.Executor
 687      **/
 688     public void setExecutor(java.util.concurrent.Executor executor) {
 689         delegate.setExecutor(executor);
 690     }
 691 
 692     /**
 693      * Creates a {@code Service} instance.
 694      *
 695      * The specified WSDL document location and service qualified name MUST
 696      * uniquely identify a {@code wsdl:service} element.
 697      *
 698      * @param wsdlDocumentLocation {@code URL} for the WSDL document location
 699      *                             for the service
 700      * @param serviceName {@code QName} for the service
 701      * @throws WebServiceException If any error in creation of the
 702      *                    specified service.
 703      **/
 704     public static Service create(
 705             java.net.URL wsdlDocumentLocation,
 706             QName serviceName) {
 707         return new Service(wsdlDocumentLocation, serviceName);
 708     }
 709 
 710     /**
 711      * Creates a {@code Service} instance. The created instance is
 712      * configured with the web service features.
 713      *
 714      * The specified WSDL document location and service qualified name MUST
 715      * uniquely identify a {@code wsdl:service} element.
 716      *
 717      * @param wsdlDocumentLocation {@code URL} for the WSDL document location
 718      *                             for the service
 719      * @param serviceName {@code QName} for the service
 720      * @param features Web Service features that must be configured on
 721      *        the service. If the provider doesn't understand a feature,
 722      *        it must throw a WebServiceException.
 723      * @throws WebServiceException If any error in creation of the
 724      *                    specified service.
 725      * @since 1.7, JAX-WS 2.2
 726      **/
 727     public static Service create(
 728             java.net.URL wsdlDocumentLocation,
 729             QName serviceName, WebServiceFeature ... features) {
 730         return new Service(wsdlDocumentLocation, serviceName, features);
 731     }
 732 
 733     /**
 734      * Creates a {@code Service} instance.
 735      *
 736      * @param serviceName {@code QName} for the service
 737      * @throws WebServiceException If any error in creation of the
 738      *                    specified service
 739      */
 740     public static Service create(QName serviceName) {
 741         return new Service(null, serviceName);
 742     }
 743 
 744     /**
 745      * Creates a {@code Service} instance. The created instance is
 746      * configured with the web service features.
 747      *
 748      * @param serviceName {@code QName} for the service
 749      * @param features Web Service features that must be configured on
 750      *        the service. If the provider doesn't understand a feature,
 751      *        it must throw a WebServiceException.
 752      * @throws WebServiceException If any error in creation of the
 753      *                    specified service
 754      *
 755      * @since 1.7, JAX-WS 2.2
 756      */
 757     public static Service create(QName serviceName, WebServiceFeature ... features) {
 758         return new Service(null, serviceName, features);
 759     }
 760 }