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