1 /*
2 * Copyright (c) 2005, 2014, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26 package javax.xml.ws.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();
111 }
112 URL targetTypeURL = loader.getResource(classnameAsResource);
113 throw new LinkageError("ClassCastException: attempting to cast" +
114 provider.getClass().getClassLoader().getResource(classnameAsResource) +
115 "to" + targetTypeURL.toString() );
116 }
117 return (Provider) provider;
118 } catch (WebServiceException ex) {
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)
179 * @param implementor A service implementation object to which
180 * incoming requests will be dispatched. The corresponding
181 * class MUST be annotated with all the necessary Web service
182 * annotations.
183 * @return The newly created endpoint.
184 */
185 public abstract Endpoint createEndpoint(String bindingId,
186 Object implementor);
187
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 }