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