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<String,Object> 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 }