1 /*

     2  * Copyright (c) 2009, 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 /**

    27   Provides HTTP SPI that is used for portable deployment of JAX-WS

    28   web services in containers(for e.g. servlet containers). This SPI

    29   is not for end developers but provides a way for the container

    30   developers to deploy JAX-WS services portably.

    31 

    32   <p>

    33   The portable deployment is done as below:

    34   <ol>

    35   <li>Container creates {@link javax.xml.ws.Endpoint} objects for an

    36   application. The necessary information to create Endpoint objects

    37   may be got from web service deployment descriptor files.</li>

    38   <li>Container needs to create {@link javax.xml.ws.spi.http.HttpContext}

    39   objects for the deployment. For example, a HttpContext could be

    40   created using servlet configuration(for e.g url-pattern) for the

    41   web service in servlet container case.</li>

    42   <li>Then publishes all the endpoints using

    43   {@link javax.xml.ws.Endpoint#publish(HttpContext)}. During publish(),

    44   JAX-WS runtime registers a {@link javax.xml.ws.spi.http.HttpHandler}

    45   callback to handle incoming requests or

    46   {@link javax.xml.ws.spi.http.HttpExchange} objects. The HttpExchange

    47   object encapsulates a HTTP request and a response.

    48   </ol>

    49 

    50   <pre>

    51   Container                               JAX-WS runtime

    52   ---------                               --------------

    53   1. Creates Invoker1, ... InvokerN

    54   2. Provider.createEndpoint(...)     --> 3. creates Endpoint1

    55      configures Endpoint1

    56      ...

    57   4. Provider.createEndpoint(...)     --> 5. creates EndpointN

    58      configures EndpointN

    59   6. Creates ApplicationContext

    60   7. creates HttpContext1, ... HttpContextN

    61   8. Endpoint1.publish(HttpContext1)  --> 9. creates HttpHandler1

    62                                           HttpContext1.setHandler(HttpHandler1)

    63      ...

    64  10. EndpointN.publish(HttpContextN)  --> 11. creates HttpHandlerN

    65                                          HttpContextN.setHandler(HttpHandlerN)

    66 

    67   </pre>

    68 

    69   The request processing is done as below(for every request):

    70   <pre>

    71   Container                               JAX-WS runtime

    72   ---------                               --------------

    73   1. Creates a HttpExchange

    74   2. Gets handler from HttpContext

    75   3. HttpHandler.handle(HttpExchange) --> 4. reads request from HttpExchange

    76                                       <-- 5. Calls Invoker

    77   6. Invokes the actual instance

    78                                           7. Writes the response to HttpExchange

    79   </pre>

    80 

    81   <p>

    82   The portable undeployment is done as below:

    83   <pre>

    84   Container

    85   ---------

    86   1. @preDestroy on instances

    87   2. Endpoint1.stop()

    88   ...

    89   3. EndpointN.stop()

    90   </pre>

    91 

    92   @author Jitendra Kotamraju

    93   @since JAX-WS 2.2

    94  */

    95 package javax.xml.ws.spi.http;