1/*
2 * Copyright (c) 2009, 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/**
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>{@literal
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>{@literal
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. {@literal @}preDestroy on instances
87  2. Endpoint1.stop()
88  ...
89  3. EndpointN.stop()
90  </pre>
91
92  @author Jitendra Kotamraju
93  @since 1.7, JAX-WS 2.2
94 */
95package javax.xml.ws.spi.http;
96