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 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();
 109                 }
 110                 URL targetTypeURL  = loader.getResource(classnameAsResource);
 111                 throw new LinkageError("ClassCastException: attempting to cast" +
 112                        provider.getClass().getClassLoader().getResource(classnameAsResource) +
 113                        "to" + targetTypeURL.toString() );
 114             }
 115             return (Provider) provider;
 116         } catch (WebServiceException ex) {
 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)
 177      * @param implementor A service implementation object to which
 178      *        incoming requests will be dispatched. The corresponding
 179      *        class MUST be annotated with all the necessary Web service
 180      *        annotations.
 181      * @return The newly created endpoint.
 182      */
 183     public abstract Endpoint createEndpoint(String bindingId,
 184             Object implementor);
 185 
 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} properties.  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 }