author | mkos |
Sun, 30 Dec 2012 00:00:00 +0100 | |
changeset 22678 | ac1ea46be942 |
parent 12009 | 4abb694f273a |
child 25840 | c2002453eec3 |
permissions | -rw-r--r-- |
12009 | 1 |
/* |
22678
ac1ea46be942
8029237: Update copyright year to match last edit in jaxws repository for 2012
mkos
parents:
12009
diff
changeset
|
2 |
* Copyright (c) 2005, 2012, Oracle and/or its affiliates. All rights reserved. |
12009 | 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.spi.http; |
|
27 |
||
28 |
import javax.xml.ws.handler.MessageContext; |
|
29 |
import java.io.InputStream; |
|
30 |
import java.io.OutputStream; |
|
31 |
import java.io.IOException; |
|
32 |
import java.net.InetSocketAddress; |
|
33 |
import java.util.List; |
|
34 |
import java.util.Map; |
|
35 |
import java.util.Set; |
|
36 |
import java.security.Principal; |
|
37 |
||
38 |
/** |
|
39 |
* This class encapsulates a HTTP request received and a |
|
40 |
* response to be generated in one exchange. It provides methods |
|
41 |
* for examining the request from the client, and for building and |
|
42 |
* sending the response. |
|
43 |
* <p> |
|
44 |
* A <code>HttpExchange</code> must be closed to free or reuse |
|
45 |
* underlying resources. The effect of failing to close an exchange |
|
46 |
* is undefined. |
|
47 |
* |
|
48 |
* @author Jitendra Kotamraju |
|
49 |
* @since JAX-WS 2.2 |
|
50 |
*/ |
|
51 |
public abstract class HttpExchange { |
|
52 |
||
53 |
/** |
|
54 |
* Standard property: cipher suite value when the request is received |
|
55 |
* over HTTPS |
|
56 |
* <p>Type: String |
|
57 |
*/ |
|
58 |
public static final String REQUEST_CIPHER_SUITE = |
|
59 |
"javax.xml.ws.spi.http.request.cipher.suite"; |
|
60 |
||
61 |
/** |
|
62 |
* Standard property: bit size of the algorithm when the request is |
|
63 |
* received over HTTPS |
|
64 |
* <p>Type: Integer |
|
65 |
*/ |
|
66 |
public static final String REQUEST_KEY_SIZE = |
|
67 |
"javax.xml.ws.spi.http.request.key.size"; |
|
68 |
||
69 |
/** |
|
70 |
* Standard property: A SSL certificate, if any, associated with the request |
|
71 |
* |
|
72 |
* <p>Type: java.security.cert.X509Certificate[] |
|
73 |
* The order of this array is defined as being in ascending order of trust. |
|
74 |
* The first certificate in the chain is the one set by the client, the next |
|
75 |
* is the one used to authenticate the first, and so on. |
|
76 |
*/ |
|
77 |
public static final String REQUEST_X509CERTIFICATE = |
|
78 |
"javax.xml.ws.spi.http.request.cert.X509Certificate"; |
|
79 |
||
80 |
/** |
|
81 |
* Returns an immutable Map containing the HTTP headers that were |
|
82 |
* included with this request. The keys in this Map will be the header |
|
83 |
* names, while the values will be a List of Strings containing each value |
|
84 |
* that was included (either for a header that was listed several times, |
|
85 |
* or one that accepts a comma-delimited list of values on a single line). |
|
86 |
* In either of these cases, the values for the header name will be |
|
87 |
* presented in the order that they were included in the request. |
|
88 |
* <p> |
|
89 |
* The keys in Map are case-insensitive. |
|
90 |
* |
|
91 |
* @return an immutable Map which can be used to access request headers |
|
92 |
*/ |
|
93 |
public abstract Map<String, List<String>> getRequestHeaders(); |
|
94 |
||
95 |
/** |
|
96 |
* Returns the value of the specified request header. If the request |
|
97 |
* did not include a header of the specified name, this method returns |
|
98 |
* null. If there are multiple headers with the same name, this method |
|
99 |
* returns the first header in the request. The header name is |
|
100 |
* case-insensitive. This is a convienence method to get a header |
|
101 |
* (instead of using the {@link #getRequestHeaders}). |
|
102 |
* |
|
103 |
* @param name the name of the request header |
|
104 |
* @return returns the value of the requested header, |
|
105 |
* or null if the request does not have a header of that name |
|
106 |
*/ |
|
107 |
public abstract String getRequestHeader(String name); |
|
108 |
||
109 |
/** |
|
110 |
* Returns a mutable Map into which the HTTP response headers can be stored |
|
111 |
* and which will be transmitted as part of this response. The keys in the |
|
112 |
* Map will be the header names, while the values must be a List of Strings |
|
113 |
* containing each value that should be included multiple times |
|
114 |
* (in the order that they should be included). |
|
115 |
* <p> |
|
116 |
* The keys in Map are case-insensitive. |
|
117 |
* |
|
118 |
* @return a mutable Map which can be used to set response headers. |
|
119 |
*/ |
|
120 |
public abstract Map<String, List<String>> getResponseHeaders(); |
|
121 |
||
122 |
/** |
|
123 |
* Adds a response header with the given name and value. This method |
|
124 |
* allows a response header to have multiple values. This is a |
|
125 |
* convenience method to add a response header(instead of using the |
|
126 |
* {@link #getResponseHeaders()}). |
|
127 |
* |
|
128 |
* @param name the name of the header |
|
129 |
* @param value the additional header value. If it contains octet string, |
|
130 |
* it should be encoded according to |
|
131 |
* RFC 2047 (http://www.ietf.org/rfc/rfc2047.txt) |
|
132 |
* |
|
133 |
* @see #getResponseHeaders |
|
134 |
*/ |
|
135 |
public abstract void addResponseHeader(String name, String value); |
|
136 |
||
137 |
/** |
|
138 |
* Returns the part of the request's URI from the protocol |
|
139 |
* name up to the query string in the first line of the HTTP request. |
|
140 |
* Container doesn't decode this string. |
|
141 |
* |
|
142 |
* @return the request URI |
|
143 |
*/ |
|
144 |
public abstract String getRequestURI(); |
|
145 |
||
146 |
/** |
|
147 |
* Returns the context path of all the endpoints in an application. |
|
148 |
* This path is the portion of the request URI that indicates the |
|
149 |
* context of the request. The context path always comes first in a |
|
150 |
* request URI. The path starts with a "/" character but does not |
|
151 |
* end with a "/" character. If this method returns "", the request |
|
152 |
* is for default context. The container does not decode this string. |
|
153 |
* |
|
154 |
* <p> |
|
155 |
* Context path is used in computing the endpoint address. See |
|
156 |
* {@link HttpContext#getPath} |
|
157 |
* |
|
158 |
* @return context path of all the endpoints in an application |
|
159 |
* @see HttpContext#getPath |
|
160 |
*/ |
|
161 |
public abstract String getContextPath(); |
|
162 |
||
163 |
/** |
|
164 |
* Get the HTTP request method |
|
165 |
* |
|
166 |
* @return the request method |
|
167 |
*/ |
|
168 |
public abstract String getRequestMethod(); |
|
169 |
||
170 |
/** |
|
171 |
* Returns a {@link HttpContext} for this exchange. |
|
172 |
* Container matches the request with the associated Endpoint's HttpContext |
|
173 |
* |
|
174 |
* @return the HttpContext for this exchange |
|
175 |
*/ |
|
176 |
public abstract HttpContext getHttpContext(); |
|
177 |
||
178 |
/** |
|
179 |
* This must be called to end an exchange. Container takes care of |
|
180 |
* closing request and response streams. This must be called so that |
|
181 |
* the container can free or reuse underlying resources. |
|
182 |
* |
|
183 |
* @throws IOException if any i/o error |
|
184 |
*/ |
|
185 |
public abstract void close() throws IOException; |
|
186 |
||
187 |
/** |
|
188 |
* Returns a stream from which the request body can be read. |
|
189 |
* Multiple calls to this method will return the same stream. |
|
190 |
* |
|
191 |
* @return the stream from which the request body can be read. |
|
192 |
* @throws IOException if any i/o error during request processing |
|
193 |
*/ |
|
194 |
public abstract InputStream getRequestBody() throws IOException; |
|
195 |
||
196 |
/** |
|
197 |
* Returns a stream to which the response body must be |
|
198 |
* written. {@link #setStatus}) must be called prior to calling |
|
199 |
* this method. Multiple calls to this method (for the same exchange) |
|
200 |
* will return the same stream. |
|
201 |
* |
|
202 |
* @return the stream to which the response body is written |
|
203 |
* @throws IOException if any i/o error during response processing |
|
204 |
*/ |
|
205 |
public abstract OutputStream getResponseBody() throws IOException; |
|
206 |
||
207 |
/** |
|
208 |
* Sets the HTTP status code for the response. |
|
209 |
* |
|
210 |
* <p> |
|
211 |
* This method must be called prior to calling {@link #getResponseBody}. |
|
212 |
* |
|
213 |
* @param status the response code to send |
|
214 |
* @see #getResponseBody |
|
215 |
*/ |
|
216 |
public abstract void setStatus(int status); |
|
217 |
||
218 |
/** |
|
219 |
* Returns the unresolved address of the remote entity invoking |
|
220 |
* this request. |
|
221 |
* |
|
222 |
* @return the InetSocketAddress of the caller |
|
223 |
*/ |
|
224 |
public abstract InetSocketAddress getRemoteAddress(); |
|
225 |
||
226 |
/** |
|
227 |
* Returns the unresolved local address on which the request was received. |
|
228 |
* |
|
229 |
* @return the InetSocketAddress of the local interface |
|
230 |
*/ |
|
231 |
public abstract InetSocketAddress getLocalAddress(); |
|
232 |
||
233 |
/** |
|
234 |
* Returns the protocol string from the request in the form |
|
235 |
* <i>protocol/majorVersion.minorVersion</i>. For example, |
|
236 |
* "HTTP/1.1" |
|
237 |
* |
|
238 |
* @return the protocol string from the request |
|
239 |
*/ |
|
240 |
public abstract String getProtocol(); |
|
241 |
||
242 |
/** |
|
243 |
* Returns the name of the scheme used to make this request, |
|
244 |
* for example: http, or https. |
|
245 |
* |
|
246 |
* @return name of the scheme used to make this request |
|
247 |
*/ |
|
248 |
public abstract String getScheme(); |
|
249 |
||
250 |
/** |
|
251 |
* Returns the extra path information that follows the web service |
|
252 |
* path but precedes the query string in the request URI and will start |
|
253 |
* with a "/" character. |
|
254 |
* |
|
255 |
* <p> |
|
256 |
* This can be used for {@link MessageContext#PATH_INFO} |
|
257 |
* |
|
258 |
* @return decoded extra path information of web service. |
|
259 |
* It is the path that comes |
|
260 |
* after the web service path but before the query string in the |
|
261 |
* request URI |
|
262 |
* <tt>null</tt> if there is no extra path in the request URI |
|
263 |
*/ |
|
264 |
public abstract String getPathInfo(); |
|
265 |
||
266 |
/** |
|
267 |
* Returns the query string that is contained in the request URI |
|
268 |
* after the path. |
|
269 |
* |
|
270 |
* <p> |
|
271 |
* This can be used for {@link MessageContext#QUERY_STRING} |
|
272 |
* |
|
273 |
* @return undecoded query string of request URI, or |
|
274 |
* <tt>null</tt> if the request URI doesn't have one |
|
275 |
*/ |
|
276 |
public abstract String getQueryString(); |
|
277 |
||
278 |
/** |
|
279 |
* Returns an attribute that is associated with this |
|
280 |
* <code>HttpExchange</code>. JAX-WS handlers and endpoints may then |
|
281 |
* access the attribute via {@link MessageContext}. |
|
282 |
* <p> |
|
283 |
* Servlet containers must expose {@link MessageContext#SERVLET_CONTEXT}, |
|
284 |
* {@link MessageContext#SERVLET_REQUEST}, and |
|
285 |
* {@link MessageContext#SERVLET_RESPONSE} |
|
286 |
* as attributes. |
|
287 |
* |
|
288 |
* <p>If the request has been received by the container using HTTPS, the |
|
289 |
* following information must be exposed as attributes. These attributes |
|
290 |
* are {@link #REQUEST_CIPHER_SUITE}, and {@link #REQUEST_KEY_SIZE}. |
|
291 |
* If there is a SSL certificate associated with the request, it must |
|
292 |
* be exposed using {@link #REQUEST_X509CERTIFICATE} |
|
293 |
* |
|
294 |
* @param name attribute name |
|
295 |
* @return the attribute value, or <tt>null</tt> if the attribute doesn't |
|
296 |
* exist |
|
297 |
*/ |
|
298 |
public abstract Object getAttribute(String name); |
|
299 |
||
300 |
/** |
|
301 |
* Gives all the attribute names that are associated with |
|
302 |
* this <code>HttpExchange</code>. |
|
303 |
* |
|
304 |
* @return set of all attribute names |
|
305 |
* @see #getAttribute(String) |
|
306 |
*/ |
|
307 |
public abstract Set<String> getAttributeNames(); |
|
308 |
||
309 |
/** |
|
310 |
* Returns the {@link Principal} that represents the authenticated |
|
311 |
* user for this <code>HttpExchange</code>. |
|
312 |
* |
|
313 |
* @return Principal for an authenticated user, or |
|
314 |
* <tt>null</tt> if not authenticated |
|
315 |
*/ |
|
316 |
public abstract Principal getUserPrincipal(); |
|
317 |
||
318 |
/** |
|
319 |
* Indicates whether an authenticated user is included in the specified |
|
320 |
* logical "role". |
|
321 |
* |
|
322 |
* @param role specifies the name of the role |
|
323 |
* @return <tt>true</tt> if the user making this request belongs to a |
|
324 |
* given role |
|
325 |
*/ |
|
326 |
public abstract boolean isUserInRole(String role); |
|
327 |
||
328 |
} |