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 }
--- EOF ---