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. In the implementation of this method, the JAX-WS
233 runtime system takes the responsibility of selecting a protocol
234 binding (and a port) and configuring the proxy accordingly.
235 The returned proxy should not be reconfigured by the client.
236 *
237 * @param <T> Service endpoint interface.
238 * @param serviceEndpointInterface Service endpoint interface.
239 * @param features A list of WebServiceFeatures to configure on the
240 * proxy. Supported features not in the {@code features
241 * } parameter will have their default values.
242 * @return Object instance that supports the
243 * specified service endpoint interface.
244 * @throws WebServiceException
245 * <UL>
246 * <LI>If there is an error during creation
247 * of the proxy.
248 * <LI>If there is any missing WSDL metadata
249 * as required by this method.
250 * <LI>If an illegal
251 * {@code serviceEndpointInterface}
252 * is specified.
253 * <LI>If a feature is enabled that is not compatible
254 * with this port or is unsupported.
255 * </UL>
256 *
257 * @see WebServiceFeature
258 *
259 * @since 1.6, JAX-WS 2.1
260 **/
261 public <T> T getPort(Class<T> serviceEndpointInterface,
262 WebServiceFeature... features) {
263 return delegate.getPort(serviceEndpointInterface, features);
264 }
265
266
267 /**
268 * The {@code getPort} method returns a proxy.
269 * The parameter {@code endpointReference} specifies the
270 * endpoint that will be invoked by the returned proxy. If there
271 * are any reference parameters in the
272 * {@code endpointReference}, then those reference
273 * parameters MUST appear as SOAP headers, indicating them to be
274 * reference parameters, on all messages sent to the endpoint.
275 * The {@code endpointReference's} address MUST be used
276 * for invocations on the endpoint.
277 * The parameter {@code serviceEndpointInterface} specifies
278 * the service endpoint interface that is supported by the
279 * returned proxy.
280 * In the implementation of this method, the JAX-WS
281 * runtime system takes the responsibility of selecting a protocol
282 * binding (and a port) and configuring the proxy accordingly from
283 * the WSDL associated with this {@code Service} instance or
284 * from the metadata from the {@code endpointReference}.
285 * If this {@code Service} instance has a WSDL and
286 * the {@code endpointReference} metadata
287 * also has a WSDL, then the WSDL from this instance MUST be used.
288 * If this {@code Service} instance does not have a WSDL and
289 * the {@code endpointReference} does have a WSDL, then the
290 * WSDL from the {@code endpointReference} MAY be used.
291 * The returned proxy should not be reconfigured by the client.
292 * If this {@code Service} instance has a known proxy
293 * port that matches the information contained in
294 * the WSDL,
295 * then that proxy is returned, otherwise a WebServiceException
296 * is thrown.
297 * <p>
298 * Calling this method has the same behavior as the following
299 * <pre>
300 * {@code port = service.getPort(portName, serviceEndpointInterface);}
301 * </pre>
302 * where the {@code portName} is retrieved from the
303 * metadata of the {@code endpointReference} or from the
304 * {@code serviceEndpointInterface} and the WSDL
305 * associated with this {@code Service} instance.
306 *
307 * @param <T> Service endpoint interface.
308 * @param endpointReference The {@code EndpointReference}
309 * for the target service endpoint that will be invoked by the
310 * returned proxy.
311 * @param serviceEndpointInterface Service endpoint interface.
312 * @param features A list of {@code WebServiceFeatures} to configure on the
313 * proxy. Supported features not in the {@code features
314 * } parameter will have their default values.
315 * @return Object Proxy instance that supports the
316 * specified service endpoint interface.
317 * @throws WebServiceException
318 * <UL>
319 * <LI>If there is an error during creation
320 * of the proxy.
321 * <LI>If there is any missing WSDL metadata
322 * as required by this method.
323 * <LI>If the {@code endpointReference} metadata does
324 * not match the {@code serviceName} of this
325 * {@code Service} instance.
326 * <LI>If a {@code portName} cannot be extracted
327 * from the WSDL or {@code endpointReference} metadata.
328 * <LI>If an invalid
329 * {@code endpointReference}
330 * is specified.
331 * <LI>If an invalid
332 * {@code serviceEndpointInterface}
333 * is specified.
334 * <LI>If a feature is enabled that is not compatible
335 * with this port or is unsupported.
336 * </UL>
337 *
338 * @since 1.6, JAX-WS 2.1
339 **/
340 public <T> T getPort(EndpointReference endpointReference,
341 Class<T> serviceEndpointInterface, WebServiceFeature... features) {
342 return delegate.getPort(endpointReference, serviceEndpointInterface, features);
343 }
344
345 /**
346 * Creates a new port for the service. Ports created in this way contain
347 * no WSDL port type information and can only be used for creating
348 * {@code Dispatch}instances.
349 *
350 * @param portName Qualified name for the target service endpoint.
351 * @param bindingId A String identifier of a binding.
352 * @param endpointAddress Address of the target service endpoint as a URI.
353 * @throws WebServiceException If any error in the creation of
354 * the port.
355 *
356 * @see javax.xml.ws.soap.SOAPBinding#SOAP11HTTP_BINDING
357 * @see javax.xml.ws.soap.SOAPBinding#SOAP12HTTP_BINDING
358 * @see javax.xml.ws.http.HTTPBinding#HTTP_BINDING
359 **/
360 public void addPort(QName portName, String bindingId, String endpointAddress) {
361 delegate.addPort(portName, bindingId, endpointAddress);
362 }
363
364
365 /**
366 * Creates a {@code Dispatch} instance for use with objects of
367 * the client's choosing.
368 *
369 * @param <T> The type of the message or payload
370 * @param portName Qualified name for the target service endpoint
371 * @param type The class of object used for messages or message
372 * payloads. Implementations are required to support
373 * {@code javax.xml.transform.Source}, {@code javax.xml.soap.SOAPMessage}
374 * and {@code javax.activation.DataSource}, depending on
375 * the binding in use.
376 * @param mode Controls whether the created dispatch instance is message
377 * or payload oriented, i.e. whether the client will work with complete
378 * protocol messages or message payloads. E.g. when using the SOAP
379 * protocol, this parameter controls whether the client will work with
380 * SOAP messages or the contents of a SOAP body. Mode MUST be MESSAGE
381 * when type is SOAPMessage.
382 *
383 * @return Dispatch instance.
384 * @throws WebServiceException If any error in the creation of
385 * the {@code Dispatch} object.
386 *
387 * @see javax.xml.transform.Source
388 * @see javax.xml.soap.SOAPMessage
389 **/
390 public <T> Dispatch<T> createDispatch(QName portName, Class<T> type, Mode mode) {
391 return delegate.createDispatch(portName, type, mode);
392 }
393
394
395 /**
396 * Creates a {@code Dispatch} instance for use with objects of
397 * the client's choosing.
398 *
399 * @param <T> The type of the message or payload
400 * @param portName Qualified name for the target service endpoint
401 * @param type The class of object used for messages or message
402 * payloads. Implementations are required to support
403 * {@code javax.xml.transform.Source} and {@code javax.xml.soap.SOAPMessage}.
404 * @param mode Controls whether the created dispatch instance is message
405 * or payload oriented, i.e. whether the client will work with complete
406 * protocol messages or message payloads. E.g. when using the SOAP
407 * protocol, this parameter controls whether the client will work with
408 * SOAP messages or the contents of a SOAP body. Mode MUST be {@code MESSAGE}
409 * when type is {@code SOAPMessage}.
410 * @param features A list of {@code WebServiceFeatures} to configure on the
411 * proxy. Supported features not in the {@code features
412 * } parameter will have their default values.
413 *
414 * @return Dispatch instance.
415 * @throws WebServiceException If any error in the creation of
416 * the {@code Dispatch} object or if a
417 * feature is enabled that is not compatible with
418 * this port or is unsupported.
419 *
420 * @see javax.xml.transform.Source
421 * @see javax.xml.soap.SOAPMessage
422 * @see WebServiceFeature
423 *
424 * @since 1.6, JAX-WS 2.1
425 **/
426 public <T> Dispatch<T> createDispatch(QName portName, Class<T> type,
427 Service.Mode mode, WebServiceFeature... features) {
428 return delegate.createDispatch(portName, type, mode, features);
429 }
430
431
432 /**
433 * Creates a {@code Dispatch} instance for use with objects of
434 * the client's choosing. If there
435 * are any reference parameters in the
436 * {@code endpointReference}, then those reference
437 * parameters MUST appear as SOAP headers, indicating them to be
438 * reference parameters, on all messages sent to the endpoint.
439 * The {@code endpointReference's} address MUST be used
440 * for invocations on the endpoint.
441 * In the implementation of this method, the JAX-WS
442 * runtime system takes the responsibility of selecting a protocol
443 * binding (and a port) and configuring the dispatch accordingly from
444 * the WSDL associated with this {@code Service} instance or
445 * from the metadata from the {@code endpointReference}.
446 * If this {@code Service} instance has a WSDL and
447 * the {@code endpointReference}
448 * also has a WSDL in its metadata, then the WSDL from this instance MUST be used.
449 * If this {@code Service} instance does not have a WSDL and
450 * the {@code endpointReference} does have a WSDL, then the
451 * WSDL from the {@code endpointReference} MAY be used.
452 * An implementation MUST be able to retrieve the {@code portName} from the
453 * {@code endpointReference} metadata.
454 * <p>
455 * This method behaves the same as calling
456 * <pre>
457 * {@code dispatch = service.createDispatch(portName, type, mode, features);}
458 * </pre>
459 * where the {@code portName} is retrieved from the
460 * WSDL or {@code EndpointReference} metadata.
461 *
462 * @param <T> The type of the message or payload
463 * @param endpointReference The {@code EndpointReference}
464 * for the target service endpoint that will be invoked by the
465 * returned {@code Dispatch} object.
466 * @param type The class of object used to messages or message
467 * payloads. Implementations are required to support
468 * {@code javax.xml.transform.Source} and {@code javax.xml.soap.SOAPMessage}.
469 * @param mode Controls whether the created dispatch instance is message
470 * or payload oriented, i.e. whether the client will work with complete
471 * protocol messages or message payloads. E.g. when using the SOAP
472 * protocol, this parameter controls whether the client will work with
473 * SOAP messages or the contents of a SOAP body. Mode MUST be {@code MESSAGE}
474 * when type is {@code SOAPMessage}.
475 * @param features An array of {@code WebServiceFeatures} to configure on the
476 * proxy. Supported features not in the {@code features
477 * } parameter will have their default values.
478 *
479 * @return Dispatch instance
480 * @throws WebServiceException
481 * <UL>
482 * <LI>If there is any missing WSDL metadata
483 * as required by this method.
484 * <li>If the {@code endpointReference} metadata does
485 * not match the {@code serviceName} or {@code portName}
486 * of a WSDL associated
487 * with this {@code Service} instance.
488 * <li>If the {@code portName} cannot be determined
489 * from the {@code EndpointReference} metadata.
490 * <li>If any error in the creation of
491 * the {@code Dispatch} object.
492 * <li>If a feature is enabled that is not
493 * compatible with this port or is unsupported.
494 * </UL>
495 *
496 * @see javax.xml.transform.Source
497 * @see javax.xml.soap.SOAPMessage
498 * @see WebServiceFeature
499 *
500 * @since 1.6, JAX-WS 2.1
501 **/
502 public <T> Dispatch<T> createDispatch(EndpointReference endpointReference,
503 Class<T> type, Service.Mode mode,
504 WebServiceFeature... features) {
505 return delegate.createDispatch(endpointReference, type, mode, features);
506 }
507
508 /**
509 * Creates a {@code Dispatch} instance for use with JAXB
510 * generated objects.
511 *
512 * @param portName Qualified name for the target service endpoint
513 * @param context The JAXB context used to marshall and unmarshall
514 * messages or message payloads.
515 * @param mode Controls whether the created dispatch instance is message
516 * or payload oriented, i.e. whether the client will work with complete
517 * protocol messages or message payloads. E.g. when using the SOAP
518 * protocol, this parameter controls whether the client will work with
519 * SOAP messages or the contents of a SOAP body.
520 *
521 * @return Dispatch instance.
522 * @throws WebServiceException If any error in the creation of
523 * the {@code Dispatch} object.
524 *
525 * @see javax.xml.bind.JAXBContext
526 **/
527 public Dispatch<Object> createDispatch(QName portName, JAXBContext context,
528 Mode mode) {
529 return delegate.createDispatch(portName, context, mode);
530 }
531
532
533 /**
534 * Creates a {@code Dispatch} instance for use with JAXB
535 * generated objects.
536 *
537 * @param portName Qualified name for the target service endpoint
538 * @param context The JAXB context used to marshall and unmarshall
539 * messages or message payloads.
540 * @param mode Controls whether the created dispatch instance is message
541 * or payload oriented, i.e. whether the client will work with complete
542 * protocol messages or message payloads. E.g. when using the SOAP
543 * protocol, this parameter controls whether the client will work with
544 * SOAP messages or the contents of a SOAP body.
545 * @param features A list of {@code WebServiceFeatures} to configure on the
546 * proxy. Supported features not in the {@code features
547 * } parameter will have their default values.
548 *
549 * @return Dispatch instance.
550 * @throws WebServiceException If any error in the creation of
551 * the {@code Dispatch} object or if a
552 * feature is enabled that is not compatible with
553 * this port or is unsupported.
554 *
555 * @see javax.xml.bind.JAXBContext
556 * @see WebServiceFeature
557 *
558 * @since 1.6, JAX-WS 2.1
559 **/
560 public Dispatch<Object> createDispatch(QName portName,
561 JAXBContext context, Service.Mode mode, WebServiceFeature... features) {
562 return delegate.createDispatch(portName, context, mode, features);
563 }
564
565
566 /**
567 * Creates a {@code Dispatch} instance for use with JAXB
568 * generated objects. If there
569 * are any reference parameters in the
570 * {@code endpointReference}, then those reference
571 * parameters MUST appear as SOAP headers, indicating them to be
572 * reference parameters, on all messages sent to the endpoint.
573 * The {@code endpointReference's} address MUST be used
574 * for invocations on the endpoint.
575 * In the implementation of this method, the JAX-WS
576 * runtime system takes the responsibility of selecting a protocol
577 * binding (and a port) and configuring the dispatch accordingly from
578 * the WSDL associated with this {@code Service} instance or
579 * from the metadata from the {@code endpointReference}.
580 * If this {@code Service} instance has a WSDL and
581 * the {@code endpointReference}
582 * also has a WSDL in its metadata, then the WSDL from this instance
583 * MUST be used.
584 * If this {@code Service} instance does not have a WSDL and
585 * the {@code endpointReference} does have a WSDL, then the
586 * WSDL from the {@code endpointReference} MAY be used.
587 * An implementation MUST be able to retrieve the {@code portName} from the
588 * {@code endpointReference} metadata.
589 * <p>
590 * This method behavies the same as calling
591 * <pre>
592 * {@code dispatch = service.createDispatch(portName, context, mode, features);}
593 * </pre>
594 * where the {@code portName} is retrieved from the
595 * WSDL or {@code endpointReference} metadata.
596 *
597 * @param endpointReference The {@code EndpointReference}
598 * for the target service endpoint that will be invoked by the
599 * returned {@code Dispatch} object.
600 * @param context The JAXB context used to marshall and unmarshall
601 * messages or message payloads.
602 * @param mode Controls whether the created dispatch instance is message
603 * or payload oriented, i.e. whether the client will work with complete
604 * protocol messages or message payloads. E.g. when using the SOAP
605 * protocol, this parameter controls whether the client will work with
606 * SOAP messages or the contents of a SOAP body.
607 * @param features An array of {@code WebServiceFeatures} to configure on the
608 * proxy. Supported features not in the {@code features
609 * } parameter will have their default values.
610 *
611 * @return Dispatch instance
612 * @throws WebServiceException
613 * <UL>
614 * <li>If there is any missing WSDL metadata
615 * as required by this method.
616 * <li>If the {@code endpointReference} metadata does
617 * not match the {@code serviceName} or {@code portName}
618 * of a WSDL associated
619 * with this {@code Service} instance.
620 * <li>If the {@code portName} cannot be determined
621 * from the {@code EndpointReference} metadata.
622 * <li>If any error in the creation of
623 * the {@code Dispatch} object.
624 * <li>if a feature is enabled that is not
625 * compatible with this port or is unsupported.
626 * </UL>
627 *
628 * @see javax.xml.bind.JAXBContext
629 * @see WebServiceFeature
630 *
631 * @since 1.6, JAX-WS 2.1
632 **/
633 public Dispatch<Object> createDispatch(EndpointReference endpointReference,
634 JAXBContext context, Service.Mode mode,
635 WebServiceFeature... features) {
636 return delegate.createDispatch(endpointReference, context, mode, features);
637 }
638
639 /**
640 * Gets the name of this service.
641 * @return Qualified name of this service
642 **/
643 public QName getServiceName() {
644 return delegate.getServiceName();
645 }
646
647 /**
648 * Returns an {@code Iterator} for the list of
649 * {@code QName}s of service endpoints grouped by this
650 * service
651 *
652 * @return Returns {@code java.util.Iterator} with elements
653 * of type {@code javax.xml.namespace.QName}.
654 * @throws WebServiceException If this Service class does not
655 * have access to the required WSDL metadata.
656 **/
657 public Iterator<javax.xml.namespace.QName> getPorts() {
658 return delegate.getPorts();
659 }
660
661 /**
662 * Gets the location of the WSDL document for this Service.
663 *
664 * @return URL for the location of the WSDL document for
665 * this service.
666 **/
667 public java.net.URL getWSDLDocumentLocation() {
668 return delegate.getWSDLDocumentLocation();
669 }
670
671 /**
672 * Returns the configured handler resolver.
673 *
674 * @return HandlerResolver The {@code HandlerResolver} being
675 * used by this {@code Service} instance, or {@code null}
676 * if there isn't one.
677 **/
678 public HandlerResolver getHandlerResolver() {
679 return delegate.getHandlerResolver();
680 }
681
682 /**
683 * Sets the {@code HandlerResolver} for this {@code Service}
684 * instance.
685 * <p>
686 * The handler resolver, if present, will be called once for each
687 * proxy or dispatch instance that is created, and the handler chain
688 * returned by the resolver will be set on the instance.
689 *
690 * @param handlerResolver The {@code HandlerResolver} to use
691 * for all subsequently created proxy/dispatch objects.
692 *
693 * @see javax.xml.ws.handler.HandlerResolver
694 **/
695 public void setHandlerResolver(HandlerResolver handlerResolver) {
696 delegate.setHandlerResolver(handlerResolver);
697 }
698
699 /**
700 * Returns the executor for this {@code Service}instance.
701 *
702 * The executor is used for all asynchronous invocations that
703 * require callbacks.
704 *
705 * @return The {@code java.util.concurrent.Executor} to be
706 * used to invoke a callback.
707 *
708 * @see java.util.concurrent.Executor
709 **/
710 public java.util.concurrent.Executor getExecutor() {
711 return delegate.getExecutor();
712 }
713
714 /**
715 * Sets the executor for this {@code Service} instance.
716 *
717 * The executor is used for all asynchronous invocations that
718 * require callbacks.
719 *
720 * @param executor The {@code java.util.concurrent.Executor}
721 * to be used to invoke a callback.
722 *
723 * @throws SecurityException If the instance does not support
724 * setting an executor for security reasons (e.g. the
725 * necessary permissions are missing).
726 *
727 * @see java.util.concurrent.Executor
728 **/
729 public void setExecutor(java.util.concurrent.Executor executor) {
730 delegate.setExecutor(executor);
731 }
732
733 /**
734 * Creates a {@code Service} instance.
735 *
736 * The specified WSDL document location and service qualified name MUST
737 * uniquely identify a {@code wsdl:service} element.
738 *
739 * @param wsdlDocumentLocation {@code URL} for the WSDL document location
740 * for the service
741 * @param serviceName {@code QName} for the service
742 * @return Service instance
743 * @throws WebServiceException If any error in creation of the
744 * specified service.
745 **/
746 public static Service create(
747 java.net.URL wsdlDocumentLocation,
748 QName serviceName) {
749 return new Service(wsdlDocumentLocation, serviceName);
750 }
751
752 /**
753 * Creates a {@code Service} instance. The created instance is
754 * configured with the web service features.
755 *
756 * The specified WSDL document location and service qualified name MUST
757 * uniquely identify a {@code wsdl:service} element.
758 *
759 * @param wsdlDocumentLocation {@code URL} for the WSDL document location
760 * for the service
761 * @param serviceName {@code QName} for the service
762 * @param features Web Service features that must be configured on
763 * the service. If the provider doesn't understand a feature,
764 * it must throw a WebServiceException.
765 * @return Service instance configured with requested web service features
766 * @throws WebServiceException If any error in creation of the
767 * specified service.
768 * @since 1.7, JAX-WS 2.2
769 **/
770 public static Service create(
771 java.net.URL wsdlDocumentLocation,
772 QName serviceName, WebServiceFeature ... features) {
773 return new Service(wsdlDocumentLocation, serviceName, features);
774 }
775
776 /**
777 * Creates a {@code Service} instance.
778 *
779 * @param serviceName {@code QName} for the service
780 * @return Service instance
781 * @throws WebServiceException If any error in creation of the
782 * specified service
783 */
784 public static Service create(QName serviceName) {
785 return new Service(null, serviceName);
786 }
787
788 /**
789 * Creates a {@code Service} instance. The created instance is
790 * configured with the web service features.
791 *
792 * @param serviceName {@code QName} for the service
793 * @param features Web Service features that must be configured on
794 * the service. If the provider doesn't understand a feature,
795 * it must throw a WebServiceException.
796 * @return Service instance configured with requested web service features
797 * @throws WebServiceException If any error in creation of the
798 * specified service
799 *
800 * @since 1.7, JAX-WS 2.2
801 */
802 public static Service create(QName serviceName, WebServiceFeature ... features) {
803 return new Service(null, serviceName, features);
804 }
805 }