< prev index next >

jaxws/src/java.xml.ws/share/classes/javax/xml/ws/Endpoint.java

Print this page


   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


  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     /**


 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      *        } 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}
 267      *          is being used and the application doesn't have the
 268      *          {@code WebServicePermission("publishEndpoint")} 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      *


 389      *
 390      * The executor is used to dispatch an incoming request to
 391      * the implementor object.
 392      *
 393      * If this {@code Endpoint} is published using the
 394      * {@code publish(Object)} 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}
 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} 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} 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} associated with
 428      * this {@code Endpoint} instance.
 429      * <p>


 433      *
 434      * @param referenceParameters Reference parameters to be associated with the
 435      * returned {@code EndpointReference} instance.
 436      * @return EndpointReference of this {@code Endpoint} instance.
 437      * If the returned {@code EndpointReference} is of type
 438      * {@code W3CEndpointReference} then it MUST contain the
 439      * the specified {@code referenceParameters}.
 440 
 441      * @throws WebServiceException If any error in the creation of
 442      * the {@code EndpointReference} or if the {@code Endpoint} is
 443      * not in the published state.
 444      * @throws UnsupportedOperationException If this {@code BindingProvider}
 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} associated with
 456      * this {@code Endpoint} 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} instance.
 461      * @return EndpointReference of type {@code clazz} of this
 462      * {@code Endpoint} instance.
 463      * If the returned {@code EndpointReference} is of type
 464      * {@code W3CEndpointReference} then it MUST contain the
 465      * the specified {@code referenceParameters}.
 466 
 467      * @throws WebServiceException If any error in the creation of
 468      * the {@code EndpointReference} or if the {@code Endpoint} is
 469      * not in the published state or if the {@code clazz} is not a supported
 470      * {@code EndpointReference} type.
 471      * @throws UnsupportedOperationException If this {@code BindingProvider}
 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}, 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 }
   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


  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      * Creates an endpoint with the specified implementor object. If there is
  86      * a binding specified via a BindingType annotation then it MUST be used else
  87      * a default of SOAP 1.1 / HTTP binding MUST be used.
  88      * <p>
  89      * The newly created endpoint may be published by calling
  90      * one of the {@link javax.xml.ws.Endpoint#publish(String)} and
  91      * {@link javax.xml.ws.Endpoint#publish(Object)} methods.
  92      *
  93      *
  94      * @param implementor The endpoint implementor.
  95      *
  96      * @return The newly created endpoint.
  97      *
  98      **/
  99     public static Endpoint create(Object implementor) {
 100         return create(null, implementor);
 101     }
 102 
 103     /**


 254      * @param address A URI specifying the address and transport/protocol
 255      *        to use. A http: URI MUST result in the SOAP 1.1/HTTP
 256      *        binding being used. Implementations may support other
 257      *        URI schemes.
 258      * @param implementor The endpoint implementor.
 259      * @param features A list of WebServiceFeature to configure on the
 260      *        endpoint. Supported features not in the {@code features
 261      *        } parameter will have their default values.
 262      * @return The newly created endpoint.
 263      *
 264      * @throws java.lang.SecurityException
 265      *          If a {@code java.lang.SecurityManger}
 266      *          is being used and the application doesn't have the
 267      *          {@code WebServicePermission("publishEndpoint")} permission.
 268      * @since 1.7, JAX-WS 2.2
 269      */
 270     public static Endpoint publish(String address, Object implementor, WebServiceFeature ... features) {
 271         return Provider.provider().createAndPublishEndpoint(address, implementor, features);
 272     }
 273 

 274     /**
 275      * Publishes this endpoint at the provided server context.
 276      * A server context encapsulates the server infrastructure
 277      * and addressing information for a particular transport.
 278      * For a call to this method to succeed, the server context
 279      * passed as an argument to it MUST be compatible with the
 280      * endpoint's binding.
 281      *
 282      * @param serverContext An object representing a server
 283      *           context to be used for publishing the endpoint.
 284      *
 285      * @throws java.lang.IllegalArgumentException
 286      *              If the provided server context is not
 287      *              supported by the implementation or turns
 288      *              out to be unusable in conjunction with the
 289      *              endpoint's binding.
 290      *
 291      * @throws java.lang.IllegalStateException
 292      *         If the endpoint has been published already or it has been stopped.
 293      *


 387      *
 388      * The executor is used to dispatch an incoming request to
 389      * the implementor object.
 390      *
 391      * If this {@code Endpoint} is published using the
 392      * {@code publish(Object)} method and the specified server
 393      * context defines its own threading behavior, the executor
 394      * may be ignored.
 395      *
 396      * @param executor The {@code java.util.concurrent.Executor}
 397      *        to be used to dispatch a request.
 398      *
 399      * @throws SecurityException  If the instance does not support
 400      *         setting an executor for security reasons (e.g. the
 401      *         necessary permissions are missing).
 402      *
 403      * @see java.util.concurrent.Executor
 404      **/
 405     public abstract void setExecutor(java.util.concurrent.Executor executor);
 406 

 407     /**
 408      * Returns the property bag for this {@code Endpoint} instance.
 409      *
 410      * @return Map&lt;String,Object&gt; The property bag
 411      *         associated with this instance.
 412      **/
 413     public abstract Map<String,Object> getProperties();
 414 
 415     /**
 416      * Sets the property bag for this {@code Endpoint} instance.
 417      *
 418      * @param properties The property bag associated with
 419      *        this instance.
 420      **/
 421     public abstract void setProperties(Map<String,Object> properties);
 422 
 423     /**
 424      * Returns the {@code EndpointReference} associated with
 425      * this {@code Endpoint} instance.
 426      * <p>


 430      *
 431      * @param referenceParameters Reference parameters to be associated with the
 432      * returned {@code EndpointReference} instance.
 433      * @return EndpointReference of this {@code Endpoint} instance.
 434      * If the returned {@code EndpointReference} is of type
 435      * {@code W3CEndpointReference} then it MUST contain the
 436      * the specified {@code referenceParameters}.
 437 
 438      * @throws WebServiceException If any error in the creation of
 439      * the {@code EndpointReference} or if the {@code Endpoint} is
 440      * not in the published state.
 441      * @throws UnsupportedOperationException If this {@code BindingProvider}
 442      * uses the XML/HTTP binding.
 443      *
 444      * @see W3CEndpointReference
 445      *
 446      * @since 1.6, JAX-WS 2.1
 447      **/
 448     public abstract EndpointReference getEndpointReference(Element... referenceParameters);
 449 

 450     /**
 451      * Returns the {@code EndpointReference} associated with
 452      * this {@code Endpoint} instance.
 453      *
 454      * @param <T> The type of EndpointReference.
 455      * @param clazz Specifies the type of EndpointReference  that MUST be returned.
 456      * @param referenceParameters Reference parameters to be associated with the
 457      * returned {@code EndpointReference} instance.
 458      * @return EndpointReference of type {@code clazz} of this
 459      * {@code Endpoint} instance.
 460      * If the returned {@code EndpointReference} is of type
 461      * {@code W3CEndpointReference} then it MUST contain the
 462      * the specified {@code referenceParameters}.
 463 
 464      * @throws WebServiceException If any error in the creation of
 465      * the {@code EndpointReference} or if the {@code Endpoint} is
 466      * not in the published state or if the {@code clazz} is not a supported
 467      * {@code EndpointReference} type.
 468      * @throws UnsupportedOperationException If this {@code BindingProvider}
 469      * uses the XML/HTTP binding.
 470      *
 471      *
 472      * @since 1.6, JAX-WS 2.1
 473      **/
 474     public abstract <T extends EndpointReference> T getEndpointReference(Class<T> clazz,
 475             Element... referenceParameters);
 476 
 477     /**
 478      * By setting a {@code EndpointContext}, JAX-WS runtime knows about
 479      * addresses of other endpoints in an application. If multiple endpoints
 480      * share different ports of a WSDL, then the multiple port addresses
 481      * are patched when the WSDL is accessed.
 482      *
 483      * <p>
 484      * This needs to be set before publishing the endpoints.
 485      *
 486      * @param ctxt that is shared for multiple endpoints
 487      * @throws java.lang.IllegalStateException
 488      *        If the endpoint has been published already or it has been stopped.
 489      *
 490      * @since 1.7, JAX-WS 2.2
 491      */
 492     public void setEndpointContext(EndpointContext ctxt) {
 493         throw new UnsupportedOperationException("JAX-WS 2.2 implementation must override this default behaviour.");
 494     }
 495 }
< prev index next >