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
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.
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
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.
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 *
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
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 }
|
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
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.
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
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.
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 *
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
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 }
|