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