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.spi;
27
28 import java.net.URL;
29 import java.util.List;
30 import java.util.Iterator;
31 import java.util.Map;
32 import java.util.ServiceLoader;
33 import javax.xml.namespace.QName;
34 import javax.xml.ws.*;
35 import javax.xml.ws.wsaddressing.W3CEndpointReference;
36
37 import org.w3c.dom.Element;
38
39 /**
40 * Service provider for <code>ServiceDelegate</code> and
41 * <code>Endpoint</code> objects.
42 * <p>
43 *
44 * @since 1.6, JAX-WS 2.0
45 */
46 public abstract class Provider {
47
48 /**
49 * A constant representing the property used to lookup the
50 * name of a <code>Provider</code> implementation
51 * class.
52 */
53 static public final String JAXWSPROVIDER_PROPERTY = "javax.xml.ws.spi.Provider";
54
55 /**
56 * A constant representing the name of the default
57 * <code>Provider</code> implementation class.
58 **/
59 // Using two strings so that package renaming doesn't change it
60 static final String DEFAULT_JAXWSPROVIDER
61 = "com.sun"+".xml.internal.ws.spi.ProviderImpl";
62
63 /**
64 * Creates a new instance of Provider
65 */
66 protected Provider() {
67 }
68
69 /**
70 *
71 * Creates a new provider object.
72 * <p>
73 * The algorithm used to locate the provider subclass to use consists
74 * of the following steps:
75 * <p>
76 * <ul>
77 * <li>
78 * If a resource with the name of
79 * <code>META-INF/services/javax.xml.ws.spi.Provider</code>
80 * exists, then its first line, if present, is used as the UTF-8 encoded
81 * name of the implementation class.
82 * </li>
83 * <li>
84 * If the $java.home/lib/jaxws.properties file exists and it is readable by
85 * the <code>java.util.Properties.load(InputStream)</code> method and it contains
86 * an entry whose key is <code>javax.xml.ws.spi.Provider</code>, then the value of
87 * that entry is used as the name of the implementation class.
88 * </li>
89 * <li>
90 * If a system property with the name <code>javax.xml.ws.spi.Provider</code>
91 * is defined, then its value is used as the name of the implementation class.
92 * </li>
93 * <li>
94 * Finally, a default implementation class name is used.
95 * </li>
96 * </ul>
97 *
98 */
99 public static Provider provider() {
100 try {
101 Object provider = getProviderUsingServiceLoader();
102 if (provider == null) {
103 provider = FactoryFinder.find(JAXWSPROVIDER_PROPERTY, DEFAULT_JAXWSPROVIDER);
104 }
105 if (!(provider instanceof Provider)) {
106 Class pClass = Provider.class;
107 String classnameAsResource = pClass.getName().replace('.', '/') + ".class";
108 ClassLoader loader = pClass.getClassLoader();
109 if(loader == null) {
110 loader = ClassLoader.getSystemClassLoader();
119 throw ex;
120 } catch (Exception ex) {
121 throw new WebServiceException("Unable to createEndpointReference Provider", ex);
122 }
123 }
124
125 private static Provider getProviderUsingServiceLoader() {
126 ServiceLoader<Provider> sl;
127 Iterator<Provider> it;
128 try {
129 sl = ServiceLoader.load(Provider.class);
130 it = (Iterator<Provider>)sl.iterator();
131 } catch (Exception e) {
132 throw new WebServiceException("Cannot invoke java.util.ServiceLoader#iterator()", e);
133 }
134 return ((it != null) && it.hasNext()) ? it.next() : null;
135 }
136
137 /**
138 * Creates a service delegate object.
139 * <p>
140 * @param wsdlDocumentLocation A URL pointing to the WSDL document
141 * for the service, or <code>null</code> if there isn't one.
142 * @param serviceName The qualified name of the service.
143 * @param serviceClass The service class, which MUST be either
144 * <code>javax.xml.ws.Service</code> or a subclass thereof.
145 * @return The newly created service delegate.
146 */
147 public abstract ServiceDelegate createServiceDelegate(
148 java.net.URL wsdlDocumentLocation,
149 QName serviceName, Class<? extends Service> serviceClass);
150
151 /**
152 * Creates a service delegate object.
153 * <p>
154 * @param wsdlDocumentLocation A URL pointing to the WSDL document
155 * for the service, or <code>null</code> if there isn't one.
156 * @param serviceName The qualified name of the service.
157 * @param serviceClass The service class, which MUST be either
158 * <code>javax.xml.ws.Service</code> or a subclass thereof.
159 * @param features Web Service features that must be configured on
160 * the service. If the provider doesn't understand a feature,
161 * it must throw a WebServiceException.
162 * @return The newly created service delegate.
163 *
164 * @since 1.7, JAX-WS 2.2
165 */
166 public ServiceDelegate createServiceDelegate(
167 java.net.URL wsdlDocumentLocation,
168 QName serviceName, Class<? extends Service> serviceClass, WebServiceFeature ... features) {
169 throw new UnsupportedOperationException("JAX-WS 2.2 implementation must override this default behaviour.");
170 }
171
172
173 /**
174 *
175 * Creates an endpoint object with the provided binding and implementation
176 * object.
177 *
178 * @param bindingId A URI specifying the desired binding (e.g. SOAP/HTTP)
188
189 /**
190 * Creates and publishes an endpoint object with the specified
191 * address and implementation object.
192 *
193 * @param address A URI specifying the address and transport/protocol
194 * to use. A http: URI MUST result in the SOAP 1.1/HTTP
195 * binding being used. Implementations may support other
196 * URI schemes.
197 * @param implementor A service implementation object to which
198 * incoming requests will be dispatched. The corresponding
199 * class MUST be annotated with all the necessary Web service
200 * annotations.
201 * @return The newly created endpoint.
202 */
203 public abstract Endpoint createAndPublishEndpoint(String address,
204 Object implementor);
205
206 /**
207 * read an EndpointReference from the infoset contained in
208 * <code>eprInfoset</code>.
209 *
210 * @param eprInfoset infoset for EndpointReference
211 *
212 * @return the <code>EndpointReference</code> unmarshalled from
213 * <code>eprInfoset</code>. This method never returns <code>null</code>.
214 *
215 * @throws WebServiceException If there is an error creating the
216 * <code>EndpointReference</code> from the specified <code>eprInfoset</code>.
217 *
218 * @throws NullPointerException If the <code>null</code>
219 * <code>eprInfoset</code> value is given.
220 *
221 * @since 1.6, JAX-WS 2.1
222 **/
223 public abstract EndpointReference readEndpointReference(javax.xml.transform.Source eprInfoset);
224
225
226 /**
227 * The getPort method returns a proxy. If there
228 * are any reference parameters in the
229 * <code>endpointReference</code>, then those reference
230 * parameters MUST appear as SOAP headers, indicating them to be
231 * reference parameters, on all messages sent to the endpoint.
232 * The parameter <code>serviceEndpointInterface</code> specifies
233 * the service endpoint interface that is supported by the
234 * returned proxy.
235 * The parameter <code>endpointReference</code> specifies the
236 * endpoint that will be invoked by the returned proxy.
237 * In the implementation of this method, the JAX-WS
238 * runtime system takes the responsibility of selecting a protocol
239 * binding (and a port) and configuring the proxy accordingly from
240 * the WSDL metadata of the
241 * <code>serviceEndpointInterface</code> and the <code>EndpointReference</code>.
242 * For this method
243 * to successfully return a proxy, WSDL metadata MUST be available and the
244 * <code>endpointReference</code> MUST contain an implementation understood
245 * <code>serviceName</code> metadata.
246 *
247 *
248 * @param endpointReference the EndpointReference that will
249 * be invoked by the returned proxy.
250 * @param serviceEndpointInterface Service endpoint interface
251 * @param features A list of WebServiceFeatures to configure on the
252 * proxy. Supported features not in the <code>features
253 * </code> parameter will have their default values.
254 * @return Object Proxy instance that supports the
255 * specified service endpoint interface
256 * @throws WebServiceException
257 * <UL>
258 * <LI>If there is an error during creation
259 * of the proxy
260 * <LI>If there is any missing WSDL metadata
261 * as required by this method}
262 * <LI>If this
263 * <code>endpointReference</code>
264 * is illegal
265 * <LI>If an illegal
266 * <code>serviceEndpointInterface</code>
267 * is specified
268 * <LI>If a feature is enabled that is not compatible with
269 * this port or is unsupported.
270 * </UL>
271 *
272 * @see WebServiceFeature
273 *
274 * @since 1.6, JAX-WS 2.1
275 **/
276 public abstract <T> T getPort(EndpointReference endpointReference,
277 Class<T> serviceEndpointInterface,
278 WebServiceFeature... features);
279
280 /**
281 * Factory method to create a <code>W3CEndpointReference</code>.
282 *
283 * <p>
284 * This method can be used to create a <code>W3CEndpointReference</code>
285 * for any endpoint by specifying the <code>address</code> property along
286 * with any other desired properties. This method
287 * can also be used to create a <code>W3CEndpointReference</code> for
288 * an endpoint that is published by the same Java EE application.
289 * To do so the <code>address</code> property can be provided or this
290 * method can automatically determine the <code>address</code> of
291 * an endpoint that is published by the same Java EE application and is
292 * identified by the <code>serviceName</code> and
293 * <code>portName</code> propeties. If the <code>address</code> is
294 * <code>null</code> and the <code>serviceName</code> and
295 * <code>portName</code> do not identify an endpoint published by the
296 * same Java EE application, a
297 * <code>javax.lang.IllegalStateException</code> MUST be thrown.
298 *
299 * @param address Specifies the address of the target endpoint
300 * @param serviceName Qualified name of the service in the WSDL.
301 * @param portName Qualified name of the endpoint in the WSDL.
302 * @param metadata A list of elements that should be added to the
303 * <code>W3CEndpointReference</code> instances <code>wsa:metadata</code>
304 * element.
305 * @param wsdlDocumentLocation URL for the WSDL document location for
306 * the service.
307 * @param referenceParameters Reference parameters to be associated
308 * with the returned <code>EndpointReference</code> instance.
309 *
310 * @return the <code>W3CEndpointReference</code> created from
311 * <code>serviceName</code>, <code>portName</code>,
312 * <code>metadata</code>, <code>wsdlDocumentLocation</code>
313 * and <code>referenceParameters</code>. This method
314 * never returns <code>null</code>.
315 *
316 * @throws java.lang.IllegalStateException
317 * <ul>
318 * <li>If the <code>address</code>, <code>serviceName</code> and
319 * <code>portName</code> are all <code>null</code>.
320 * <li>If the <code>serviceName</code> service is <code>null</code> and the
321 * <code>portName</code> is NOT <code>null</code>.
322 * <li>If the <code>address</code> property is <code>null</code> and
323 * the <code>serviceName</code> and <code>portName</code> do not
324 * specify a valid endpoint published by the same Java EE
325 * application.
326 * <li>If the <code>serviceName</code>is NOT <code>null</code>
327 * and is not present in the specified WSDL.
328 * <li>If the <code>portName</code> port is not <code>null</code> and it
329 * is not present in <code>serviceName</code> service in the WSDL.
330 * <li>If the <code>wsdlDocumentLocation</code> is NOT <code>null</code>
331 * and does not represent a valid WSDL.
332 * </ul>
333 * @throws WebServiceException If an error occurs while creating the
334 * <code>W3CEndpointReference</code>.
335 *
336 * @since 1.6, JAX-WS 2.1
337 */
338 public abstract W3CEndpointReference createW3CEndpointReference(String address, QName serviceName, QName portName,
339 List<Element> metadata, String wsdlDocumentLocation, List<Element> referenceParameters);
340
341
342 /**
343 * Factory method to create a <code>W3CEndpointReference</code>.
344 * Using this method, a <code>W3CEndpointReference</code> instance
345 * can be created with extension elements, and attributes.
346 * <code>Provider</code> implementations must override the default
347 * implementation.
348 *
349 * <p>
350 * This method can be used to create a <code>W3CEndpointReference</code>
351 * for any endpoint by specifying the <code>address</code> property along
352 * with any other desired properties. This method
353 * can also be used to create a <code>W3CEndpointReference</code> for
354 * an endpoint that is published by the same Java EE application.
355 * To do so the <code>address</code> property can be provided or this
356 * method can automatically determine the <code>address</code> of
357 * an endpoint that is published by the same Java EE application and is
358 * identified by the <code>serviceName</code> and
359 * <code>portName</code> propeties. If the <code>address</code> is
360 * <code>null</code> and the <code>serviceName</code> and
361 * <code>portName</code> do not identify an endpoint published by the
362 * same Java EE application, a
363 * <code>javax.lang.IllegalStateException</code> MUST be thrown.
364 *
365 * @param address Specifies the address of the target endpoint
366 * @param interfaceName the <code>wsam:InterfaceName</code> element in the
367 * <code>wsa:Metadata</code> element.
368 * @param serviceName Qualified name of the service in the WSDL.
369 * @param portName Qualified name of the endpoint in the WSDL.
370 * @param metadata A list of elements that should be added to the
371 * <code>W3CEndpointReference</code> instances <code>wsa:metadata</code>
372 * element.
373 * @param wsdlDocumentLocation URL for the WSDL document location for
374 * the service.
375 * @param referenceParameters Reference parameters to be associated
376 * with the returned <code>EndpointReference</code> instance.
377 * @param elements extension elements to be associated
378 * with the returned <code>EndpointReference</code> instance.
379 * @param attributes extension attributes to be associated
380 * with the returned <code>EndpointReference</code> instance.
381 *
382 * @return the <code>W3CEndpointReference</code> created from
383 * <code>serviceName</code>, <code>portName</code>,
384 * <code>metadata</code>, <code>wsdlDocumentLocation</code>
385 * and <code>referenceParameters</code>. This method
386 * never returns <code>null</code>.
387 *
388 * @throws java.lang.IllegalStateException
389 * <ul>
390 * <li>If the <code>address</code>, <code>serviceName</code> and
391 * <code>portName</code> are all <code>null</code>.
392 * <li>If the <code>serviceName</code> service is <code>null</code> and the
393 * <code>portName</code> is NOT <code>null</code>.
394 * <li>If the <code>address</code> property is <code>null</code> and
395 * the <code>serviceName</code> and <code>portName</code> do not
396 * specify a valid endpoint published by the same Java EE
397 * application.
398 * <li>If the <code>serviceName</code>is NOT <code>null</code>
399 * and is not present in the specified WSDL.
400 * <li>If the <code>portName</code> port is not <code>null</code> and it
401 * is not present in <code>serviceName</code> service in the WSDL.
402 * <li>If the <code>wsdlDocumentLocation</code> is NOT <code>null</code>
403 * and does not represent a valid WSDL.
404 * <li>If the <code>wsdlDocumentLocation</code> is NOT <code>null</code> but
405 * wsdli:wsdlLocation's namespace name cannot be got from the available
406 * metadata.
407 * </ul>
408 * @throws WebServiceException If an error occurs while creating the
409 * <code>W3CEndpointReference</code>.
410 * @since 1.7, JAX-WS 2.2
411 */
412 public W3CEndpointReference createW3CEndpointReference(String address,
413 QName interfaceName, QName serviceName, QName portName,
414 List<Element> metadata, String wsdlDocumentLocation, List<Element> referenceParameters,
415 List<Element> elements, Map<QName, String> attributes) {
416 throw new UnsupportedOperationException("JAX-WS 2.2 implementation must override this default behaviour.");
417 }
418
419 /**
420 * Creates and publishes an endpoint object with the specified
421 * address, implementation object and web service features.
422 * <code>Provider</code> implementations must override the
423 * default implementation.
424 *
425 * @param address A URI specifying the address and transport/protocol
426 * to use. A http: URI MUST result in the SOAP 1.1/HTTP
427 * binding being used. Implementations may support other
428 * URI schemes.
429 * @param implementor A service implementation object to which
430 * incoming requests will be dispatched. The corresponding
431 * class MUST be annotated with all the necessary Web service
432 * annotations.
433 * @param features A list of WebServiceFeatures to configure on the
434 * endpoint. Supported features not in the <code>features
435 * </code> parameter will have their default values.
436 * @return The newly created endpoint.
437 * @since 1.7, JAX-WS 2.2
438 */
439 public Endpoint createAndPublishEndpoint(String address,
440 Object implementor, WebServiceFeature ... features) {
441 throw new UnsupportedOperationException("JAX-WS 2.2 implementation must override this default behaviour.");
442 }
443
444 /**
445 * Creates an endpoint object with the provided binding, implementation
446 * object and web service features. <code>Provider</code> implementations
447 * must override the default implementation.
448 *
449 * @param bindingId A URI specifying the desired binding (e.g. SOAP/HTTP)
450 * @param implementor A service implementation object to which
451 * incoming requests will be dispatched. The corresponding
452 * class MUST be annotated with all the necessary Web service
453 * annotations.
454 * @param features A list of WebServiceFeatures to configure on the
455 * endpoint. Supported features not in the <code>features
456 * </code> parameter will have their default values.
457 * @return The newly created endpoint.
458 * @since 1.7, JAX-WS 2.2
459 */
460 public Endpoint createEndpoint(String bindingId, Object implementor,
461 WebServiceFeature ... features) {
462 throw new UnsupportedOperationException("JAX-WS 2.2 implementation must override this default behaviour.");
463 }
464
465 /**
466 * Creates an endpoint object with the provided binding, implementation
467 * class, invoker and web service features. Containers typically use
468 * this to create Endpoint objects. <code>Provider</code>
469 * implementations must override the default implementation.
470 *
471 * @param bindingId A URI specifying the desired binding (e.g. SOAP/HTTP).
472 * Can be null.
473 * @param implementorClass A service implementation class that
474 * MUST be annotated with all the necessary Web service
475 * annotations.
476 * @param invoker that does the actual invocation on the service instance.
477 * @param features A list of WebServiceFeatures to configure on the
478 * endpoint. Supported features not in the <code>features
479 * </code> parameter will have their default values.
480 * @return The newly created endpoint.
481 * @since 1.7, JAX-WS 2.2
482 */
483 public Endpoint createEndpoint(String bindingId, Class<?> implementorClass,
484 Invoker invoker, WebServiceFeature ... features) {
485 throw new UnsupportedOperationException("JAX-WS 2.2 implementation must override this default behaviour.");
486 }
487
488 }
|
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.spi;
27
28 import java.net.URL;
29 import java.util.List;
30 import java.util.Iterator;
31 import java.util.Map;
32 import java.util.ServiceLoader;
33 import javax.xml.namespace.QName;
34 import javax.xml.ws.*;
35 import javax.xml.ws.wsaddressing.W3CEndpointReference;
36
37 import org.w3c.dom.Element;
38
39 /**
40 * Service provider for {@code ServiceDelegate} and
41 * {@code Endpoint} objects.
42 *
43 * @since 1.6, JAX-WS 2.0
44 */
45 public abstract class Provider {
46
47 /**
48 * A constant representing the property used to lookup the
49 * name of a {@code Provider} implementation
50 * class.
51 */
52 static public final String JAXWSPROVIDER_PROPERTY = "javax.xml.ws.spi.Provider";
53
54 /**
55 * A constant representing the name of the default
56 * {@code Provider} implementation class.
57 **/
58 // Using two strings so that package renaming doesn't change it
59 static final String DEFAULT_JAXWSPROVIDER
60 = "com.sun"+".xml.internal.ws.spi.ProviderImpl";
61
62 /**
63 * Creates a new instance of Provider
64 */
65 protected Provider() {
66 }
67
68 /**
69 *
70 * Creates a new provider object.
71 * <p>
72 * The algorithm used to locate the provider subclass to use consists
73 * of the following steps:
74 * <ul>
75 * <li>
76 * If a resource with the name of
77 * {@code META-INF/services/javax.xml.ws.spi.Provider}
78 * exists, then its first line, if present, is used as the UTF-8 encoded
79 * name of the implementation class.
80 * </li>
81 * <li>
82 * If the $java.home/lib/jaxws.properties file exists and it is readable by
83 * the {@code java.util.Properties.load(InputStream)} method and it contains
84 * an entry whose key is {@code javax.xml.ws.spi.Provider}, then the value of
85 * that entry is used as the name of the implementation class.
86 * </li>
87 * <li>
88 * If a system property with the name {@code javax.xml.ws.spi.Provider}
89 * is defined, then its value is used as the name of the implementation class.
90 * </li>
91 * <li>
92 * Finally, a default implementation class name is used.
93 * </li>
94 * </ul>
95 *
96 */
97 public static Provider provider() {
98 try {
99 Object provider = getProviderUsingServiceLoader();
100 if (provider == null) {
101 provider = FactoryFinder.find(JAXWSPROVIDER_PROPERTY, DEFAULT_JAXWSPROVIDER);
102 }
103 if (!(provider instanceof Provider)) {
104 Class pClass = Provider.class;
105 String classnameAsResource = pClass.getName().replace('.', '/') + ".class";
106 ClassLoader loader = pClass.getClassLoader();
107 if(loader == null) {
108 loader = ClassLoader.getSystemClassLoader();
117 throw ex;
118 } catch (Exception ex) {
119 throw new WebServiceException("Unable to createEndpointReference Provider", ex);
120 }
121 }
122
123 private static Provider getProviderUsingServiceLoader() {
124 ServiceLoader<Provider> sl;
125 Iterator<Provider> it;
126 try {
127 sl = ServiceLoader.load(Provider.class);
128 it = (Iterator<Provider>)sl.iterator();
129 } catch (Exception e) {
130 throw new WebServiceException("Cannot invoke java.util.ServiceLoader#iterator()", e);
131 }
132 return ((it != null) && it.hasNext()) ? it.next() : null;
133 }
134
135 /**
136 * Creates a service delegate object.
137 *
138 * @param wsdlDocumentLocation A URL pointing to the WSDL document
139 * for the service, or {@code null} if there isn't one.
140 * @param serviceName The qualified name of the service.
141 * @param serviceClass The service class, which MUST be either
142 * {@code javax.xml.ws.Service} or a subclass thereof.
143 * @return The newly created service delegate.
144 */
145 public abstract ServiceDelegate createServiceDelegate(
146 java.net.URL wsdlDocumentLocation,
147 QName serviceName, Class<? extends Service> serviceClass);
148
149 /**
150 * Creates a service delegate object.
151 *
152 * @param wsdlDocumentLocation A URL pointing to the WSDL document
153 * for the service, or {@code null} if there isn't one.
154 * @param serviceName The qualified name of the service.
155 * @param serviceClass The service class, which MUST be either
156 * {@code javax.xml.ws.Service} or a subclass thereof.
157 * @param features Web Service features that must be configured on
158 * the service. If the provider doesn't understand a feature,
159 * it must throw a WebServiceException.
160 * @return The newly created service delegate.
161 *
162 * @since 1.7, JAX-WS 2.2
163 */
164 public ServiceDelegate createServiceDelegate(
165 java.net.URL wsdlDocumentLocation,
166 QName serviceName, Class<? extends Service> serviceClass, WebServiceFeature ... features) {
167 throw new UnsupportedOperationException("JAX-WS 2.2 implementation must override this default behaviour.");
168 }
169
170
171 /**
172 *
173 * Creates an endpoint object with the provided binding and implementation
174 * object.
175 *
176 * @param bindingId A URI specifying the desired binding (e.g. SOAP/HTTP)
186
187 /**
188 * Creates and publishes an endpoint object with the specified
189 * address and implementation object.
190 *
191 * @param address A URI specifying the address and transport/protocol
192 * to use. A http: URI MUST result in the SOAP 1.1/HTTP
193 * binding being used. Implementations may support other
194 * URI schemes.
195 * @param implementor A service implementation object to which
196 * incoming requests will be dispatched. The corresponding
197 * class MUST be annotated with all the necessary Web service
198 * annotations.
199 * @return The newly created endpoint.
200 */
201 public abstract Endpoint createAndPublishEndpoint(String address,
202 Object implementor);
203
204 /**
205 * read an EndpointReference from the infoset contained in
206 * {@code eprInfoset}.
207 *
208 * @param eprInfoset infoset for EndpointReference
209 *
210 * @return the {@code EndpointReference} unmarshalled from
211 * {@code eprInfoset}. This method never returns {@code null}.
212 *
213 * @throws WebServiceException If there is an error creating the
214 * {@code EndpointReference} from the specified {@code eprInfoset}.
215 *
216 * @throws NullPointerException If the {@code null}
217 * {@code eprInfoset} value is given.
218 *
219 * @since 1.6, JAX-WS 2.1
220 **/
221 public abstract EndpointReference readEndpointReference(javax.xml.transform.Source eprInfoset);
222
223
224 /**
225 * The getPort method returns a proxy. If there
226 * are any reference parameters in the
227 * {@code endpointReference}, then those reference
228 * parameters MUST appear as SOAP headers, indicating them to be
229 * reference parameters, on all messages sent to the endpoint.
230 * The parameter {@code serviceEndpointInterface} specifies
231 * the service endpoint interface that is supported by the
232 * returned proxy.
233 * The parameter {@code endpointReference} specifies the
234 * endpoint that will be invoked by the returned proxy.
235 * In the implementation of this method, the JAX-WS
236 * runtime system takes the responsibility of selecting a protocol
237 * binding (and a port) and configuring the proxy accordingly from
238 * the WSDL metadata of the
239 * {@code serviceEndpointInterface} and the {@code EndpointReference}.
240 * For this method
241 * to successfully return a proxy, WSDL metadata MUST be available and the
242 * {@code endpointReference} MUST contain an implementation understood
243 * {@code serviceName} metadata.
244 *
245 *
246 * @param endpointReference the EndpointReference that will
247 * be invoked by the returned proxy.
248 * @param serviceEndpointInterface Service endpoint interface
249 * @param features A list of WebServiceFeatures to configure on the
250 * proxy. Supported features not in the {@code features
251 * } parameter will have their default values.
252 * @return Object Proxy instance that supports the
253 * specified service endpoint interface
254 * @throws WebServiceException
255 * <UL>
256 * <LI>If there is an error during creation
257 * of the proxy
258 * <LI>If there is any missing WSDL metadata
259 * as required by this method}
260 * <LI>If this
261 * {@code endpointReference}
262 * is illegal
263 * <LI>If an illegal
264 * {@code serviceEndpointInterface}
265 * is specified
266 * <LI>If a feature is enabled that is not compatible with
267 * this port or is unsupported.
268 * </UL>
269 *
270 * @see WebServiceFeature
271 *
272 * @since 1.6, JAX-WS 2.1
273 **/
274 public abstract <T> T getPort(EndpointReference endpointReference,
275 Class<T> serviceEndpointInterface,
276 WebServiceFeature... features);
277
278 /**
279 * Factory method to create a {@code W3CEndpointReference}.
280 *
281 * <p>
282 * This method can be used to create a {@code W3CEndpointReference}
283 * for any endpoint by specifying the {@code address} property along
284 * with any other desired properties. This method
285 * can also be used to create a {@code W3CEndpointReference} for
286 * an endpoint that is published by the same Java EE application.
287 * To do so the {@code address} property can be provided or this
288 * method can automatically determine the {@code address} of
289 * an endpoint that is published by the same Java EE application and is
290 * identified by the {@code serviceName} and
291 * {@code portName} propeties. If the {@code address} is
292 * {@code null} and the {@code serviceName} and
293 * {@code portName} do not identify an endpoint published by the
294 * same Java EE application, a
295 * {@code javax.lang.IllegalStateException} MUST be thrown.
296 *
297 * @param address Specifies the address of the target endpoint
298 * @param serviceName Qualified name of the service in the WSDL.
299 * @param portName Qualified name of the endpoint in the WSDL.
300 * @param metadata A list of elements that should be added to the
301 * {@code W3CEndpointReference} instances {@code wsa:metadata}
302 * element.
303 * @param wsdlDocumentLocation URL for the WSDL document location for
304 * the service.
305 * @param referenceParameters Reference parameters to be associated
306 * with the returned {@code EndpointReference} instance.
307 *
308 * @return the {@code W3CEndpointReference} created from
309 * {@code serviceName}, {@code portName},
310 * {@code metadata}, {@code wsdlDocumentLocation}
311 * and {@code referenceParameters}. This method
312 * never returns {@code null}.
313 *
314 * @throws java.lang.IllegalStateException
315 * <ul>
316 * <li>If the {@code address}, {@code serviceName} and
317 * {@code portName} are all {@code null}.
318 * <li>If the {@code serviceName} service is {@code null} and the
319 * {@code portName} is NOT {@code null}.
320 * <li>If the {@code address} property is {@code null} and
321 * the {@code serviceName} and {@code portName} do not
322 * specify a valid endpoint published by the same Java EE
323 * application.
324 * <li>If the {@code serviceName}is NOT {@code null}
325 * and is not present in the specified WSDL.
326 * <li>If the {@code portName} port is not {@code null} and it
327 * is not present in {@code serviceName} service in the WSDL.
328 * <li>If the {@code wsdlDocumentLocation} is NOT {@code null}
329 * and does not represent a valid WSDL.
330 * </ul>
331 * @throws WebServiceException If an error occurs while creating the
332 * {@code W3CEndpointReference}.
333 *
334 * @since 1.6, JAX-WS 2.1
335 */
336 public abstract W3CEndpointReference createW3CEndpointReference(String address, QName serviceName, QName portName,
337 List<Element> metadata, String wsdlDocumentLocation, List<Element> referenceParameters);
338
339
340 /**
341 * Factory method to create a {@code W3CEndpointReference}.
342 * Using this method, a {@code W3CEndpointReference} instance
343 * can be created with extension elements, and attributes.
344 * {@code Provider} implementations must override the default
345 * implementation.
346 *
347 * <p>
348 * This method can be used to create a {@code W3CEndpointReference}
349 * for any endpoint by specifying the {@code address} property along
350 * with any other desired properties. This method
351 * can also be used to create a {@code W3CEndpointReference} for
352 * an endpoint that is published by the same Java EE application.
353 * To do so the {@code address} property can be provided or this
354 * method can automatically determine the {@code address} of
355 * an endpoint that is published by the same Java EE application and is
356 * identified by the {@code serviceName} and
357 * {@code portName} propeties. If the {@code address} is
358 * {@code null} and the {@code serviceName} and
359 * {@code portName} do not identify an endpoint published by the
360 * same Java EE application, a
361 * {@code javax.lang.IllegalStateException} MUST be thrown.
362 *
363 * @param address Specifies the address of the target endpoint
364 * @param interfaceName the {@code wsam:InterfaceName} element in the
365 * {@code wsa:Metadata} element.
366 * @param serviceName Qualified name of the service in the WSDL.
367 * @param portName Qualified name of the endpoint in the WSDL.
368 * @param metadata A list of elements that should be added to the
369 * {@code W3CEndpointReference} instances {@code wsa:metadata}
370 * element.
371 * @param wsdlDocumentLocation URL for the WSDL document location for
372 * the service.
373 * @param referenceParameters Reference parameters to be associated
374 * with the returned {@code EndpointReference} instance.
375 * @param elements extension elements to be associated
376 * with the returned {@code EndpointReference} instance.
377 * @param attributes extension attributes to be associated
378 * with the returned {@code EndpointReference} instance.
379 *
380 * @return the {@code W3CEndpointReference} created from
381 * {@code serviceName}, {@code portName},
382 * {@code metadata}, {@code wsdlDocumentLocation}
383 * and {@code referenceParameters}. This method
384 * never returns {@code null}.
385 *
386 * @throws java.lang.IllegalStateException
387 * <ul>
388 * <li>If the {@code address}, {@code serviceName} and
389 * {@code portName} are all {@code null}.
390 * <li>If the {@code serviceName} service is {@code null} and the
391 * {@code portName} is NOT {@code null}.
392 * <li>If the {@code address} property is {@code null} and
393 * the {@code serviceName} and {@code portName} do not
394 * specify a valid endpoint published by the same Java EE
395 * application.
396 * <li>If the {@code serviceName}is NOT {@code null}
397 * and is not present in the specified WSDL.
398 * <li>If the {@code portName} port is not {@code null} and it
399 * is not present in {@code serviceName} service in the WSDL.
400 * <li>If the {@code wsdlDocumentLocation} is NOT {@code null}
401 * and does not represent a valid WSDL.
402 * <li>If the {@code wsdlDocumentLocation} is NOT {@code null} but
403 * wsdli:wsdlLocation's namespace name cannot be got from the available
404 * metadata.
405 * </ul>
406 * @throws WebServiceException If an error occurs while creating the
407 * {@code W3CEndpointReference}.
408 * @since 1.7, JAX-WS 2.2
409 */
410 public W3CEndpointReference createW3CEndpointReference(String address,
411 QName interfaceName, QName serviceName, QName portName,
412 List<Element> metadata, String wsdlDocumentLocation, List<Element> referenceParameters,
413 List<Element> elements, Map<QName, String> attributes) {
414 throw new UnsupportedOperationException("JAX-WS 2.2 implementation must override this default behaviour.");
415 }
416
417 /**
418 * Creates and publishes an endpoint object with the specified
419 * address, implementation object and web service features.
420 * {@code Provider} implementations must override the
421 * default implementation.
422 *
423 * @param address A URI specifying the address and transport/protocol
424 * to use. A http: URI MUST result in the SOAP 1.1/HTTP
425 * binding being used. Implementations may support other
426 * URI schemes.
427 * @param implementor A service implementation object to which
428 * incoming requests will be dispatched. The corresponding
429 * class MUST be annotated with all the necessary Web service
430 * annotations.
431 * @param features A list of WebServiceFeatures to configure on the
432 * endpoint. Supported features not in the {@code features}
433 * parameter will have their default values.
434 * @return The newly created endpoint.
435 * @since 1.7, JAX-WS 2.2
436 */
437 public Endpoint createAndPublishEndpoint(String address,
438 Object implementor, WebServiceFeature ... features) {
439 throw new UnsupportedOperationException("JAX-WS 2.2 implementation must override this default behaviour.");
440 }
441
442 /**
443 * Creates an endpoint object with the provided binding, implementation
444 * object and web service features. {@code Provider} implementations
445 * must override the default implementation.
446 *
447 * @param bindingId A URI specifying the desired binding (e.g. SOAP/HTTP)
448 * @param implementor A service implementation object to which
449 * incoming requests will be dispatched. The corresponding
450 * class MUST be annotated with all the necessary Web service
451 * annotations.
452 * @param features A list of WebServiceFeatures to configure on the
453 * endpoint. Supported features not in the {@code features}
454 * parameter will have their default values.
455 * @return The newly created endpoint.
456 * @since 1.7, JAX-WS 2.2
457 */
458 public Endpoint createEndpoint(String bindingId, Object implementor,
459 WebServiceFeature ... features) {
460 throw new UnsupportedOperationException("JAX-WS 2.2 implementation must override this default behaviour.");
461 }
462
463 /**
464 * Creates an endpoint object with the provided binding, implementation
465 * class, invoker and web service features. Containers typically use
466 * this to create Endpoint objects. {@code Provider}
467 * implementations must override the default implementation.
468 *
469 * @param bindingId A URI specifying the desired binding (e.g. SOAP/HTTP).
470 * Can be null.
471 * @param implementorClass A service implementation class that
472 * MUST be annotated with all the necessary Web service
473 * annotations.
474 * @param invoker that does the actual invocation on the service instance.
475 * @param features A list of WebServiceFeatures to configure on the
476 * endpoint. Supported features not in the {@code features
477 * } parameter will have their default values.
478 * @return The newly created endpoint.
479 * @since 1.7, JAX-WS 2.2
480 */
481 public Endpoint createEndpoint(String bindingId, Class<?> implementorClass,
482 Invoker invoker, WebServiceFeature ... features) {
483 throw new UnsupportedOperationException("JAX-WS 2.2 implementation must override this default behaviour.");
484 }
485
486 }
|