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 26package javax.xml.ws.spi; 27 28import java.util.List; 29import java.util.Map; 30import javax.xml.namespace.QName; 31import javax.xml.ws.*; 32import javax.xml.ws.wsaddressing.W3CEndpointReference; 33 34import 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 */ 42public 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} 440