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