Repository navigation
Expand file tree
/
Copy pathHttpExchange.java
More file actions
265 lines (241 loc) · 11.6 KB
/
Copy pathHttpExchange.java
File metadata and controls
265 lines (241 loc) · 11.6 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
/*
* Copyright (c) 2005, 2006, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Oracle designates this
* particular file as subject to the "Classpath" exception as provided
* by Oracle in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
* or visit www.oracle.com if you need additional information or have any
* questions.
*/
package net.tommalone.httpserver;
import java.io.*;
import java.nio.*;
import java.nio.channels.*;
import java.net.*;
import javax.net.ssl.*;
import java.util.*;
import sun.net.www.MessageHeader;
/**
* This class encapsulates a HTTP request received and a
* response to be generated in one exchange. It provides methods
* for examining the request from the client, and for building and
* sending the response.
* <p>
* The typical life-cycle of a HttpExchange is shown in the sequence
* below.
* <ol><li>{@link #getRequestMethod()} to determine the command
* <li>{@link #getRequestHeaders()} to examine the request headers (if needed)
* <li>{@link #getRequestBody()} returns a {@link java.io.InputStream} for reading the request body.
* After reading the request body, the stream is close.
* <li>{@link #getResponseHeaders()} to set any response headers, except content-length
* <li>{@link #sendResponseHeaders(int,long)} to send the response headers. Must be called before
* next step.
* <li>{@link #getResponseBody()} to get a {@link java.io.OutputStream} to send the response body.
* When the response body has been written, the stream must be closed to terminate the exchange.
* </ol>
* <b>Terminating exchanges</b>
* <br>
* Exchanges are terminated when both the request InputStream and response OutputStream are closed.
* Closing the OutputStream, implicitly closes the InputStream (if it is not already closed).
* However, it is recommended
* to consume all the data from the InputStream before closing it.
* The convenience method {@link #close()} does all of these tasks.
* Closing an exchange without consuming all of the request body is not an error
* but may make the underlying TCP connection unusable for following exchanges.
* The effect of failing to terminate an exchange is undefined, but will typically
* result in resources failing to be freed/reused.
* @since 1.6
*/
public abstract class HttpExchange {
protected HttpExchange () {
}
/**
* Returns an immutable Map containing the HTTP headers that were
* included with this request. The keys in this Map will be the header
* names, while the values will be a List of Strings containing each value
* that was included (either for a header that was listed several times,
* or one that accepts a comma-delimited list of values on a single line).
* In either of these cases, the values for the header name will be
* presented in the order that they were included in the request.
* <p>
* The keys in Map are case-insensitive.
* @return a read-only Map which can be used to access request headers
*/
public abstract Headers getRequestHeaders () ;
/**
* Returns a mutable Map into which the HTTP response headers can be stored
* and which will be transmitted as part of this response. The keys in the
* Map will be the header names, while the values must be a List of Strings
* containing each value that should be included multiple times
* (in the order that they should be included).
* <p>
* The keys in Map are case-insensitive.
* @return a writable Map which can be used to set response headers.
*/
public abstract Headers getResponseHeaders () ;
/**
* Get the request URI
*
* @return the request URI
*/
public abstract URI getRequestURI () ;
/**
* Get the request method
* @return the request method
*/
public abstract String getRequestMethod ();
/**
* Get the HttpContext for this exchange
* @return the HttpContext
*/
public abstract HttpContext getHttpContext ();
/**
* Ends this exchange by doing the following in sequence:<p><ol>
* <li>close the request InputStream, if not already closed<p></li>
* <li>close the response OutputStream, if not already closed. </li>
* </ol>
*/
public abstract void close () ;
/**
* returns a stream from which the request body can be read.
* Multiple calls to this method will return the same stream.
* It is recommended that applications should consume (read) all of the
* data from this stream before closing it. If a stream is closed
* before all data has been read, then the close() call will
* read and discard remaining data (up to an implementation specific
* number of bytes).
* @return the stream from which the request body can be read.
*/
public abstract InputStream getRequestBody () ;
/**
* returns a stream to which the response body must be
* written. {@link #sendResponseHeaders(int,long)}) must be called prior to calling
* this method. Multiple calls to this method (for the same exchange)
* will return the same stream. In order to correctly terminate
* each exchange, the output stream must be closed, even if no
* response body is being sent.
* <p>
* Closing this stream implicitly
* closes the InputStream returned from {@link #getRequestBody()}
* (if it is not already closed).
* <P>
* If the call to sendResponseHeaders() specified a fixed response
* body length, then the exact number of bytes specified in that
* call must be written to this stream. If too many bytes are written,
* then write() will throw an IOException. If too few bytes are written
* then the stream close() will throw an IOException. In both cases,
* the exchange is aborted and the underlying TCP connection closed.
* @return the stream to which the response body is written
*/
public abstract OutputStream getResponseBody () ;
/**
* Starts sending the response back to the client using the current set of response headers
* and the numeric response code as specified in this method. The response body length is also specified
* as follows. If the response length parameter is greater than zero, this specifies an exact
* number of bytes to send and the application must send that exact amount of data.
* If the response length parameter is <code>zero</code>, then chunked transfer encoding is
* used and an arbitrary amount of data may be sent. The application terminates the
* response body by closing the OutputStream. If response length has the value <code>-1</code>
* then no response body is being sent.
* <p>
* If the content-length response header has not already been set then
* this is set to the apropriate value depending on the response length parameter.
* <p>
* This method must be called prior to calling {@link #getResponseBody()}.
* @param rCode the response code to send
* @param responseLength if > 0, specifies a fixed response body length
* and that exact number of bytes must be written
* to the stream acquired from getResponseBody(), or else
* if equal to 0, then chunked encoding is used,
* and an arbitrary number of bytes may be written.
* if <= -1, then no response body length is specified and
* no response body may be written.
* @see HttpExchange#getResponseBody()
*/
public abstract void sendResponseHeaders (int rCode, long responseLength) throws IOException ;
/**
* Returns the address of the remote entity invoking this request
* @return the InetSocketAddress of the caller
*/
public abstract InetSocketAddress getRemoteAddress ();
/**
* Returns the response code, if it has already been set
* @return the response code, if available. <code>-1</code> if not available yet.
*/
public abstract int getResponseCode ();
/**
* Returns the local address on which the request was received
* @return the InetSocketAddress of the local interface
*/
public abstract InetSocketAddress getLocalAddress ();
/**
* Returns the protocol string from the request in the form
* <i>protocol/majorVersion.minorVersion</i>. For example,
* "HTTP/1.1"
* @return the protocol string from the request
*/
public abstract String getProtocol ();
/**
* Filter modules may store arbitrary objects with HttpExchange
* instances as an out-of-band communication mechanism. Other Filters
* or the exchange handler may then access these objects.
* <p>
* Each Filter class will document the attributes which they make
* available.
* @param name the name of the attribute to retrieve
* @return the attribute object, or null if it does not exist
* @throws NullPointerException if name is <code>null</code>
*/
public abstract Object getAttribute (String name) ;
/**
* Filter modules may store arbitrary objects with HttpExchange
* instances as an out-of-band communication mechanism. Other Filters
* or the exchange handler may then access these objects.
* <p>
* Each Filter class will document the attributes which they make
* available.
* @param name the name to associate with the attribute value
* @param value the object to store as the attribute value. <code>null</code>
* value is permitted.
* @throws NullPointerException if name is <code>null</code>
*/
public abstract void setAttribute (String name, Object value) ;
/**
* Used by Filters to wrap either (or both) of this exchange's InputStream
* and OutputStream, with the given filtered streams so
* that subsequent calls to {@link #getRequestBody()} will
* return the given {@link java.io.InputStream}, and calls to
* {@link #getResponseBody()} will return the given
* {@link java.io.OutputStream}. The streams provided to this
* call must wrap the original streams, and may be (but are not
* required to be) sub-classes of {@link java.io.FilterInputStream}
* and {@link java.io.FilterOutputStream}.
* @param i the filtered input stream to set as this object's inputstream,
* or <code>null</code> if no change.
* @param o the filtered output stream to set as this object's outputstream,
* or <code>null</code> if no change.
*/
public abstract void setStreams (InputStream i, OutputStream o);
/**
* If an authenticator is set on the HttpContext that owns this exchange,
* then this method will return the {@link HttpPrincipal} that represents
* the authenticated user for this HttpExchange.
* @return the HttpPrincipal, or <code>null</code> if no authenticator is set.
*/
public abstract HttpPrincipal getPrincipal ();
}