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>
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 1.7, JAX-WS 2.2
94 */
95 package javax.xml.ws.spi.http;