1 /*
   2  * Copyright (c) 2005, 2012, 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;
  27 
  28 import java.util.List;
  29 import java.util.Map;
  30 import javax.xml.ws.spi.Provider;
  31 import javax.xml.ws.spi.http.HttpContext;
  32 import javax.xml.ws.wsaddressing.W3CEndpointReference;
  33 import org.w3c.dom.Element;
  34 
  35 
  36 /**
  37  * A Web service endpoint.
  38  *
  39  * <p>Endpoints are created using the static methods defined in this
  40  * class. An endpoint is always tied to one <code>Binding</code>
  41  * and one implementor, both set at endpoint creation time.
  42  *
  43  * <p>An endpoint is either in a published or an unpublished state.
  44  * The <code>publish</code> methods can be used to start publishing
  45  * an endpoint, at which point it starts accepting incoming requests.
  46  * Conversely, the <code>stop</code> method can be used to stop
  47  * accepting incoming requests and take the endpoint down.
  48  * Once stopped, an endpoint cannot be published again.
  49  *
  50  * <p>An <code>Executor</code> may be set on the endpoint in order
  51  * to gain better control over the threads used to dispatch incoming
  52  * requests. For instance, thread pooling with certain parameters
  53  * can be enabled by creating a <code>ThreadPoolExecutor</code> and
  54  * registering it with the endpoint.
  55  *
  56  * <p>Handler chains can be set using the contained <code>Binding</code>.
  57  *
  58  * <p>An endpoint may have a list of metadata documents, such as WSDL
  59  * and XMLSchema documents, bound to it. At publishing time, the
  60  * JAX-WS implementation will try to reuse as much of that metadata
  61  * as possible instead of generating new ones based on the annotations
  62  * present on the implementor.
  63  *
  64  * @since 1.6, JAX-WS 2.0
  65  *
  66  * @see javax.xml.ws.Binding
  67  * @see javax.xml.ws.BindingType
  68  * @see javax.xml.ws.soap.SOAPBinding
  69  * @see java.util.concurrent.Executor
  70  *
  71  **/
  72 public abstract class Endpoint {
  73 
  74     /** Standard property: name of WSDL service.
  75      *  <p>Type: javax.xml.namespace.QName
  76      **/
  77     public static final String WSDL_SERVICE = "javax.xml.ws.wsdl.service";
  78 
  79     /** Standard property: name of WSDL port.
  80      *  <p>Type: javax.xml.namespace.QName
  81      **/
  82     public static final String WSDL_PORT = "javax.xml.ws.wsdl.port";
  83 
  84 
  85     /**
  86      * Creates an endpoint with the specified implementor object. If there is
  87      * a binding specified via a BindingType annotation then it MUST be used else
  88      * a default of SOAP 1.1 / HTTP binding MUST be used.
  89      * <p>
  90      * The newly created endpoint may be published by calling
  91      * one of the {@link javax.xml.ws.Endpoint#publish(String)} and
  92      * {@link javax.xml.ws.Endpoint#publish(Object)} methods.
  93      *
  94      *
  95      * @param implementor The endpoint implementor.
  96      *
  97      * @return The newly created endpoint.
  98      *
  99      **/
 100     public static Endpoint create(Object implementor) {
 101         return create(null, implementor);
 102     }
 103 
 104     /**
 105      * Creates an endpoint with the specified implementor object and web
 106      * service features. If there is a binding specified via a BindingType
 107      * annotation then it MUST be used else a default of SOAP 1.1 / HTTP
 108      * binding MUST be used.
 109      * <p>
 110      * The newly created endpoint may be published by calling
 111      * one of the {@link javax.xml.ws.Endpoint#publish(String)} and
 112      * {@link javax.xml.ws.Endpoint#publish(Object)} methods.
 113      *
 114      *
 115      * @param implementor The endpoint implementor.
 116      * @param features A list of WebServiceFeature to configure on the
 117      *        endpoint. Supported features not in the <code>features
 118      *        </code> parameter will have their default values.
 119      *
 120      *
 121      * @return The newly created endpoint.
 122      * @since 1.7, JAX-WS 2.2
 123      *
 124      */
 125     public static Endpoint create(Object implementor, WebServiceFeature ... features) {
 126         return create(null, implementor, features);
 127     }
 128 
 129     /**
 130      * Creates an endpoint with the specified binding type and
 131      * implementor object.
 132      * <p>
 133      * The newly created endpoint may be published by calling
 134      * one of the {@link javax.xml.ws.Endpoint#publish(String)} and
 135      * {@link javax.xml.ws.Endpoint#publish(Object)} methods.
 136      *
 137      * @param bindingId A URI specifying the binding to use. If the bindingID is
 138      * <code>null</code> and no binding is specified via a BindingType
 139      * annotation then a default SOAP 1.1 / HTTP binding MUST be used.
 140      *
 141      * @param implementor The endpoint implementor.
 142      *
 143      * @return The newly created endpoint.
 144      *
 145      **/
 146     public static Endpoint create(String bindingId, Object implementor) {
 147         return Provider.provider().createEndpoint(bindingId, implementor);
 148     }
 149 
 150     /**
 151      * Creates an endpoint with the specified binding type,
 152      * implementor object, and web service features.
 153      * <p>
 154      * The newly created endpoint may be published by calling
 155      * one of the {@link javax.xml.ws.Endpoint#publish(String)} and
 156      * {@link javax.xml.ws.Endpoint#publish(Object)} methods.
 157      *
 158      * @param bindingId A URI specifying the binding to use. If the bindingID is
 159      * <code>null</code> and no binding is specified via a BindingType
 160      * annotation then a default SOAP 1.1 / HTTP binding MUST be used.
 161      *
 162      * @param implementor The endpoint implementor.
 163      *
 164      * @param features A list of WebServiceFeature to configure on the
 165      *        endpoint. Supported features not in the <code>features
 166      *        </code> parameter will have their default values.
 167      *
 168      * @return The newly created endpoint.
 169      * @since 1.7, JAX-WS 2.2
 170      */
 171     public static Endpoint create(String bindingId, Object implementor, WebServiceFeature ... features) {
 172         return Provider.provider().createEndpoint(bindingId, implementor, features);
 173     }
 174 
 175     /**
 176      * Returns the binding for this endpoint.
 177      *
 178      * @return The binding for this endpoint
 179      **/
 180     public abstract Binding getBinding();
 181 
 182     /**
 183      * Returns the implementation object for this endpoint.
 184      *
 185      * @return The implementor for this endpoint
 186      **/
 187     public abstract Object getImplementor();
 188 
 189     /**
 190      * Publishes this endpoint at the given address.
 191      * The necessary server infrastructure will be created and
 192      * configured by the JAX-WS implementation using some default configuration.
 193      * In order to get more control over the server configuration, please
 194      * use the {@link javax.xml.ws.Endpoint#publish(Object)} method instead.
 195      *
 196      * @param address A URI specifying the address to use. The address
 197      *        MUST be compatible with the binding specified at the
 198      *        time the endpoint was created.
 199      *
 200      * @throws java.lang.IllegalArgumentException
 201      *          If the provided address URI is not usable
 202      *          in conjunction with the endpoint's binding.
 203      *
 204      * @throws java.lang.IllegalStateException
 205      *          If the endpoint has been published already or it has been stopped.
 206      *
 207      * @throws java.lang.SecurityException
 208      *          If a <code>java.lang.SecurityManger</code>
 209      *          is being used and the application doesn't have the
 210      *          <code>WebServicePermission("publishEndpoint")</code> permission.
 211      **/
 212     public abstract void publish(String address);
 213 
 214     /**
 215      * Creates and publishes an endpoint for the specified implementor
 216      * object at the given address.
 217      * <p>
 218      * The necessary server infrastructure will be created and
 219      * configured by the JAX-WS implementation using some default configuration.
 220      *
 221      * In order to get more control over the server configuration, please
 222      * use the {@link javax.xml.ws.Endpoint#create(String,Object)} and
 223      * {@link javax.xml.ws.Endpoint#publish(Object)} methods instead.
 224      *
 225      * @param address A URI specifying the address and transport/protocol
 226      *        to use. A http: URI MUST result in the SOAP 1.1/HTTP
 227      *        binding being used. Implementations may support other
 228      *        URI schemes.
 229      * @param implementor The endpoint implementor.
 230      *
 231      * @return The newly created endpoint.
 232      *
 233      * @throws java.lang.SecurityException
 234      *          If a <code>java.lang.SecurityManger</code>
 235      *          is being used and the application doesn't have the
 236      *          <code>WebServicePermission("publishEndpoint")</code> permission.
 237      *
 238      **/
 239     public static Endpoint publish(String address, Object implementor) {
 240         return Provider.provider().createAndPublishEndpoint(address, implementor);
 241     }
 242 
 243     /**
 244      * Creates and publishes an endpoint for the specified implementor
 245      * object at the given address. The created endpoint is configured
 246      * with the web service features.
 247      * <p>
 248      * The necessary server infrastructure will be created and
 249      * configured by the JAX-WS implementation using some default configuration.
 250      *
 251      * In order to get more control over the server configuration, please
 252      * use the {@link javax.xml.ws.Endpoint#create(String,Object)} and
 253      * {@link javax.xml.ws.Endpoint#publish(Object)} methods instead.
 254      *
 255      * @param address A URI specifying the address and transport/protocol
 256      *        to use. A http: URI MUST result in the SOAP 1.1/HTTP
 257      *        binding being used. Implementations may support other
 258      *        URI schemes.
 259      * @param implementor The endpoint implementor.
 260      * @param features A list of WebServiceFeature to configure on the
 261      *        endpoint. Supported features not in the <code>features
 262      *        </code> parameter will have their default values.
 263      * @return The newly created endpoint.
 264      *
 265      * @throws java.lang.SecurityException
 266      *          If a <code>java.lang.SecurityManger</code>
 267      *          is being used and the application doesn't have the
 268      *          <code>WebServicePermission("publishEndpoint")</code> permission.
 269      * @since 1.7, JAX-WS 2.2
 270      */
 271     public static Endpoint publish(String address, Object implementor, WebServiceFeature ... features) {
 272         return Provider.provider().createAndPublishEndpoint(address, implementor, features);
 273     }
 274 
 275 
 276     /**
 277      * Publishes this endpoint at the provided server context.
 278      * A server context encapsulates the server infrastructure
 279      * and addressing information for a particular transport.
 280      * For a call to this method to succeed, the server context
 281      * passed as an argument to it MUST be compatible with the
 282      * endpoint's binding.
 283      *
 284      * @param serverContext An object representing a server
 285      *           context to be used for publishing the endpoint.
 286      *
 287      * @throws java.lang.IllegalArgumentException
 288      *              If the provided server context is not
 289      *              supported by the implementation or turns
 290      *              out to be unusable in conjunction with the
 291      *              endpoint's binding.
 292      *
 293      * @throws java.lang.IllegalStateException
 294      *         If the endpoint has been published already or it has been stopped.
 295      *
 296      * @throws java.lang.SecurityException
 297      *          If a <code>java.lang.SecurityManger</code>
 298      *          is being used and the application doesn't have the
 299      *          <code>WebServicePermission("publishEndpoint")</code> permission.
 300      **/
 301     public abstract void publish(Object serverContext);
 302 
 303     /**
 304      * Publishes this endpoint at the provided server context.
 305      * A server context encapsulates the server infrastructure
 306      * and addressing information for a particular transport.
 307      * For a call to this method to succeed, the server context
 308      * passed as an argument to it MUST be compatible with the
 309      * endpoint's binding.
 310      *
 311      * <p>
 312      * This is meant for container developers to publish the
 313      * the endpoints portably and not intended for the end
 314      * developers.
 315      *
 316      *
 317      * @param serverContext An object representing a server
 318      *           context to be used for publishing the endpoint.
 319      *
 320      * @throws java.lang.IllegalArgumentException
 321      *              If the provided server context is not
 322      *              supported by the implementation or turns
 323      *              out to be unusable in conjunction with the
 324      *              endpoint's binding.
 325      *
 326      * @throws java.lang.IllegalStateException
 327      *         If the endpoint has been published already or it has been stopped.
 328      *
 329      * @throws java.lang.SecurityException
 330      *          If a <code>java.lang.SecurityManger</code>
 331      *          is being used and the application doesn't have the
 332      *          <code>WebServicePermission("publishEndpoint")</code> permission.
 333      * @since 1.7, JAX-WS 2.2
 334      */
 335     public void publish(HttpContext serverContext) {
 336         throw new UnsupportedOperationException("JAX-WS 2.2 implementation must override this default behaviour.");
 337     }
 338 
 339     /**
 340      * Stops publishing this endpoint.
 341      *
 342      * If the endpoint is not in a published state, this method
 343      * has no effect.
 344      *
 345      **/
 346     public abstract void stop();
 347 
 348     /**
 349      * Returns true if the endpoint is in the published state.
 350      *
 351      * @return <code>true</code> if the endpoint is in the published state.
 352      **/
 353     public abstract boolean isPublished();
 354 
 355     /**
 356      * Returns a list of metadata documents for the service.
 357      *
 358      * @return <code>List&lt;javax.xml.transform.Source&gt;</code> A list of metadata documents for the service
 359      **/
 360     public abstract List<javax.xml.transform.Source> getMetadata();
 361 
 362     /**
 363      * Sets the metadata for this endpoint.
 364      *
 365      * @param metadata A list of XML document sources containing
 366      *           metadata information for the endpoint (e.g.
 367      *           WSDL or XML Schema documents)
 368      *
 369      * @throws java.lang.IllegalStateException  If the endpoint
 370      *         has already been published.
 371      **/
 372     public abstract void setMetadata(List<javax.xml.transform.Source> metadata);
 373 
 374     /**
 375      * Returns the executor for this <code>Endpoint</code>instance.
 376      *
 377      * The executor is used to dispatch an incoming request to
 378      * the implementor object.
 379      *
 380      * @return The <code>java.util.concurrent.Executor</code> to be
 381      *         used to dispatch a request.
 382      *
 383      * @see java.util.concurrent.Executor
 384      **/
 385     public abstract java.util.concurrent.Executor getExecutor();
 386 
 387     /**
 388      * Sets the executor for this <code>Endpoint</code> instance.
 389      *
 390      * The executor is used to dispatch an incoming request to
 391      * the implementor object.
 392      *
 393      * If this <code>Endpoint</code> is published using the
 394      * <code>publish(Object)</code> method and the specified server
 395      * context defines its own threading behavior, the executor
 396      * may be ignored.
 397      *
 398      * @param executor The <code>java.util.concurrent.Executor</code>
 399      *        to be used to dispatch a request.
 400      *
 401      * @throws SecurityException  If the instance does not support
 402      *         setting an executor for security reasons (e.g. the
 403      *         necessary permissions are missing).
 404      *
 405      * @see java.util.concurrent.Executor
 406      **/
 407     public abstract void setExecutor(java.util.concurrent.Executor executor);
 408 
 409 
 410     /**
 411      * Returns the property bag for this <code>Endpoint</code> instance.
 412      *
 413      * @return Map&lt;String,Object&gt; The property bag
 414      *         associated with this instance.
 415      **/
 416     public abstract Map<String,Object> getProperties();
 417 
 418     /**
 419      * Sets the property bag for this <code>Endpoint</code> instance.
 420      *
 421      * @param properties The property bag associated with
 422      *        this instance.
 423      **/
 424     public abstract void setProperties(Map<String,Object> properties);
 425 
 426     /**
 427      * Returns the <code>EndpointReference</code> associated with
 428      * this <code>Endpoint</code> instance.
 429      * <p>
 430      * If the Binding for this <code>bindingProvider</code> is
 431      * either SOAP1.1/HTTP or SOAP1.2/HTTP, then a
 432      * <code>W3CEndpointReference</code> MUST be returned.
 433      *
 434      * @param referenceParameters Reference parameters to be associated with the
 435      * returned <code>EndpointReference</code> instance.
 436      * @return EndpointReference of this <code>Endpoint</code> instance.
 437      * If the returned <code>EndpointReference</code> is of type
 438      * <code>W3CEndpointReference</code> then it MUST contain the
 439      * the specified <code>referenceParameters</code>.
 440 
 441      * @throws WebServiceException If any error in the creation of
 442      * the <code>EndpointReference</code> or if the <code>Endpoint</code> is
 443      * not in the published state.
 444      * @throws UnsupportedOperationException If this <code>BindingProvider</code>
 445      * uses the XML/HTTP binding.
 446      *
 447      * @see W3CEndpointReference
 448      *
 449      * @since 1.6, JAX-WS 2.1
 450      **/
 451     public abstract EndpointReference getEndpointReference(Element... referenceParameters);
 452 
 453 
 454     /**
 455      * Returns the <code>EndpointReference</code> associated with
 456      * this <code>Endpoint</code> instance.
 457      *
 458      * @param clazz Specifies the type of EndpointReference  that MUST be returned.
 459      * @param referenceParameters Reference parameters to be associated with the
 460      * returned <code>EndpointReference</code> instance.
 461      * @return EndpointReference of type <code>clazz</code> of this
 462      * <code>Endpoint</code> instance.
 463      * If the returned <code>EndpointReference</code> is of type
 464      * <code>W3CEndpointReference</code> then it MUST contain the
 465      * the specified <code>referenceParameters</code>.
 466 
 467      * @throws WebServiceException If any error in the creation of
 468      * the <code>EndpointReference</code> or if the <code>Endpoint</code> is
 469      * not in the published state or if the <code>clazz</code> is not a supported
 470      * <code>EndpointReference</code> type.
 471      * @throws UnsupportedOperationException If this <code>BindingProvider</code>
 472      * uses the XML/HTTP binding.
 473      *
 474      *
 475      * @since 1.6, JAX-WS 2.1
 476      **/
 477     public abstract <T extends EndpointReference> T getEndpointReference(Class<T> clazz,
 478             Element... referenceParameters);
 479 
 480     /**
 481      * By settng a <code>EndpointContext</code>, JAX-WS runtime knows about
 482      * addresses of other endpoints in an application. If multiple endpoints
 483      * share different ports of a WSDL, then the multiple port addresses
 484      * are patched when the WSDL is accessed.
 485      *
 486      * <p>
 487      * This needs to be set before publishing the endpoints.
 488      *
 489      * @param ctxt that is shared for multiple endpoints
 490      * @throws java.lang.IllegalStateException
 491      *        If the endpoint has been published already or it has been stopped.
 492      *
 493      * @since 1.7, JAX-WS 2.2
 494      */
 495     public void setEndpointContext(EndpointContext ctxt) {
 496         throw new UnsupportedOperationException("JAX-WS 2.2 implementation must override this default behaviour.");
 497     }
 498 }