99 /**
100 * Get the request URI
101 *
102 * @return the request URI
103 */
104 public abstract URI getRequestURI () ;
105
106 /**
107 * Get the request method
108 * @return the request method
109 */
110 public abstract String getRequestMethod ();
111
112 /**
113 * Get the HttpContext for this exchange
114 * @return the HttpContext
115 */
116 public abstract HttpContext getHttpContext ();
117
118 /**
119 * Ends this exchange by doing the following in sequence:<p><ol>
120 * <li>close the request InputStream, if not already closed<p></li>
121 * <li>close the response OutputStream, if not already closed. </li>
122 * </ol>
123 */
124 public abstract void close () ;
125
126 /**
127 * returns a stream from which the request body can be read.
128 * Multiple calls to this method will return the same stream.
129 * It is recommended that applications should consume (read) all of the
130 * data from this stream before closing it. If a stream is closed
131 * before all data has been read, then the close() call will
132 * read and discard remaining data (up to an implementation specific
133 * number of bytes).
134 * @return the stream from which the request body can be read.
135 */
136 public abstract InputStream getRequestBody () ;
137
138 /**
139 * returns a stream to which the response body must be
140 * written. {@link #sendResponseHeaders(int,long)}) must be called prior to calling
141 * this method. Multiple calls to this method (for the same exchange)
146 * Closing this stream implicitly
147 * closes the InputStream returned from {@link #getRequestBody()}
148 * (if it is not already closed).
149 * <P>
150 * If the call to sendResponseHeaders() specified a fixed response
151 * body length, then the exact number of bytes specified in that
152 * call must be written to this stream. If too many bytes are written,
153 * then write() will throw an IOException. If too few bytes are written
154 * then the stream close() will throw an IOException. In both cases,
155 * the exchange is aborted and the underlying TCP connection closed.
156 * @return the stream to which the response body is written
157 */
158 public abstract OutputStream getResponseBody () ;
159
160
161 /**
162 * Starts sending the response back to the client using the current set of response headers
163 * and the numeric response code as specified in this method. The response body length is also specified
164 * as follows. If the response length parameter is greater than zero, this specifies an exact
165 * number of bytes to send and the application must send that exact amount of data.
166 * If the response length parameter is <code>zero</code>, then chunked transfer encoding is
167 * used and an arbitrary amount of data may be sent. The application terminates the
168 * response body by closing the OutputStream. If response length has the value <code>-1</code>
169 * then no response body is being sent.
170 * <p>
171 * If the content-length response header has not already been set then
172 * this is set to the appropriate value depending on the response length parameter.
173 * <p>
174 * This method must be called prior to calling {@link #getResponseBody()}.
175 * @param rCode the response code to send
176 * @param responseLength if > 0, specifies a fixed response body length
177 * and that exact number of bytes must be written
178 * to the stream acquired from getResponseBody(), or else
179 * if equal to 0, then chunked encoding is used,
180 * and an arbitrary number of bytes may be written.
181 * if <= -1, then no response body length is specified and
182 * no response body may be written.
183 * @see HttpExchange#getResponseBody()
184 */
185 public abstract void sendResponseHeaders (int rCode, long responseLength) throws IOException ;
186
187 /**
188 * Returns the address of the remote entity invoking this request
189 * @return the InetSocketAddress of the caller
190 */
191 public abstract InetSocketAddress getRemoteAddress ();
192
193 /**
194 * Returns the response code, if it has already been set
195 * @return the response code, if available. <code>-1</code> if not available yet.
196 */
197 public abstract int getResponseCode ();
198
199 /**
200 * Returns the local address on which the request was received
201 * @return the InetSocketAddress of the local interface
202 */
203 public abstract InetSocketAddress getLocalAddress ();
204
205 /**
206 * Returns the protocol string from the request in the form
207 * <i>protocol/majorVersion.minorVersion</i>. For example,
208 * "HTTP/1.1"
209 * @return the protocol string from the request
210 */
211 public abstract String getProtocol ();
212
213 /**
214 * Filter modules may store arbitrary objects with HttpExchange
215 * instances as an out-of-band communication mechanism. Other Filters
216 * or the exchange handler may then access these objects.
217 * <p>
218 * Each Filter class will document the attributes which they make
219 * available.
220 * @param name the name of the attribute to retrieve
221 * @return the attribute object, or null if it does not exist
222 * @throws NullPointerException if name is <code>null</code>
223 */
224 public abstract Object getAttribute (String name) ;
225
226 /**
227 * Filter modules may store arbitrary objects with HttpExchange
228 * instances as an out-of-band communication mechanism. Other Filters
229 * or the exchange handler may then access these objects.
230 * <p>
231 * Each Filter class will document the attributes which they make
232 * available.
233 * @param name the name to associate with the attribute value
234 * @param value the object to store as the attribute value. <code>null</code>
235 * value is permitted.
236 * @throws NullPointerException if name is <code>null</code>
237 */
238 public abstract void setAttribute (String name, Object value) ;
239
240 /**
241 * Used by Filters to wrap either (or both) of this exchange's InputStream
242 * and OutputStream, with the given filtered streams so
243 * that subsequent calls to {@link #getRequestBody()} will
244 * return the given {@link java.io.InputStream}, and calls to
245 * {@link #getResponseBody()} will return the given
246 * {@link java.io.OutputStream}. The streams provided to this
247 * call must wrap the original streams, and may be (but are not
248 * required to be) sub-classes of {@link java.io.FilterInputStream}
249 * and {@link java.io.FilterOutputStream}.
250 * @param i the filtered input stream to set as this object's inputstream,
251 * or <code>null</code> if no change.
252 * @param o the filtered output stream to set as this object's outputstream,
253 * or <code>null</code> if no change.
254 */
255 public abstract void setStreams (InputStream i, OutputStream o);
256
257
258 /**
259 * If an authenticator is set on the HttpContext that owns this exchange,
260 * then this method will return the {@link HttpPrincipal} that represents
261 * the authenticated user for this HttpExchange.
262 * @return the HttpPrincipal, or <code>null</code> if no authenticator is set.
263 */
264 public abstract HttpPrincipal getPrincipal ();
265 }
|
99 /**
100 * Get the request URI
101 *
102 * @return the request URI
103 */
104 public abstract URI getRequestURI () ;
105
106 /**
107 * Get the request method
108 * @return the request method
109 */
110 public abstract String getRequestMethod ();
111
112 /**
113 * Get the HttpContext for this exchange
114 * @return the HttpContext
115 */
116 public abstract HttpContext getHttpContext ();
117
118 /**
119 * Ends this exchange by doing the following in sequence:<ol>
120 * <li>close the request InputStream, if not already closed;</li>
121 * <li>close the response OutputStream, if not already closed.</li>
122 * </ol>
123 */
124 public abstract void close () ;
125
126 /**
127 * returns a stream from which the request body can be read.
128 * Multiple calls to this method will return the same stream.
129 * It is recommended that applications should consume (read) all of the
130 * data from this stream before closing it. If a stream is closed
131 * before all data has been read, then the close() call will
132 * read and discard remaining data (up to an implementation specific
133 * number of bytes).
134 * @return the stream from which the request body can be read.
135 */
136 public abstract InputStream getRequestBody () ;
137
138 /**
139 * returns a stream to which the response body must be
140 * written. {@link #sendResponseHeaders(int,long)}) must be called prior to calling
141 * this method. Multiple calls to this method (for the same exchange)
146 * Closing this stream implicitly
147 * closes the InputStream returned from {@link #getRequestBody()}
148 * (if it is not already closed).
149 * <P>
150 * If the call to sendResponseHeaders() specified a fixed response
151 * body length, then the exact number of bytes specified in that
152 * call must be written to this stream. If too many bytes are written,
153 * then write() will throw an IOException. If too few bytes are written
154 * then the stream close() will throw an IOException. In both cases,
155 * the exchange is aborted and the underlying TCP connection closed.
156 * @return the stream to which the response body is written
157 */
158 public abstract OutputStream getResponseBody () ;
159
160
161 /**
162 * Starts sending the response back to the client using the current set of response headers
163 * and the numeric response code as specified in this method. The response body length is also specified
164 * as follows. If the response length parameter is greater than zero, this specifies an exact
165 * number of bytes to send and the application must send that exact amount of data.
166 * If the response length parameter is {@code zero}, then chunked transfer encoding is
167 * used and an arbitrary amount of data may be sent. The application terminates the
168 * response body by closing the OutputStream. If response length has the value {@code -1}
169 * then no response body is being sent.
170 * <p>
171 * If the content-length response header has not already been set then
172 * this is set to the appropriate value depending on the response length parameter.
173 * <p>
174 * This method must be called prior to calling {@link #getResponseBody()}.
175 * @param rCode the response code to send
176 * @param responseLength if > 0, specifies a fixed response body length
177 * and that exact number of bytes must be written
178 * to the stream acquired from getResponseBody(), or else
179 * if equal to 0, then chunked encoding is used,
180 * and an arbitrary number of bytes may be written.
181 * if <= -1, then no response body length is specified and
182 * no response body may be written.
183 * @see HttpExchange#getResponseBody()
184 */
185 public abstract void sendResponseHeaders (int rCode, long responseLength) throws IOException ;
186
187 /**
188 * Returns the address of the remote entity invoking this request
189 * @return the InetSocketAddress of the caller
190 */
191 public abstract InetSocketAddress getRemoteAddress ();
192
193 /**
194 * Returns the response code, if it has already been set
195 * @return the response code, if available. {@code -1} if not available yet.
196 */
197 public abstract int getResponseCode ();
198
199 /**
200 * Returns the local address on which the request was received
201 * @return the InetSocketAddress of the local interface
202 */
203 public abstract InetSocketAddress getLocalAddress ();
204
205 /**
206 * Returns the protocol string from the request in the form
207 * <i>protocol/majorVersion.minorVersion</i>. For example,
208 * "HTTP/1.1"
209 * @return the protocol string from the request
210 */
211 public abstract String getProtocol ();
212
213 /**
214 * Filter modules may store arbitrary objects with HttpExchange
215 * instances as an out-of-band communication mechanism. Other Filters
216 * or the exchange handler may then access these objects.
217 * <p>
218 * Each Filter class will document the attributes which they make
219 * available.
220 * @param name the name of the attribute to retrieve
221 * @return the attribute object, or null if it does not exist
222 * @throws NullPointerException if name is {@code null}
223 */
224 public abstract Object getAttribute (String name) ;
225
226 /**
227 * Filter modules may store arbitrary objects with HttpExchange
228 * instances as an out-of-band communication mechanism. Other Filters
229 * or the exchange handler may then access these objects.
230 * <p>
231 * Each Filter class will document the attributes which they make
232 * available.
233 * @param name the name to associate with the attribute value
234 * @param value the object to store as the attribute value. {@code null}
235 * value is permitted.
236 * @throws NullPointerException if name is {@code null}
237 */
238 public abstract void setAttribute (String name, Object value) ;
239
240 /**
241 * Used by Filters to wrap either (or both) of this exchange's InputStream
242 * and OutputStream, with the given filtered streams so
243 * that subsequent calls to {@link #getRequestBody()} will
244 * return the given {@link java.io.InputStream}, and calls to
245 * {@link #getResponseBody()} will return the given
246 * {@link java.io.OutputStream}. The streams provided to this
247 * call must wrap the original streams, and may be (but are not
248 * required to be) sub-classes of {@link java.io.FilterInputStream}
249 * and {@link java.io.FilterOutputStream}.
250 * @param i the filtered input stream to set as this object's inputstream,
251 * or {@code null} if no change.
252 * @param o the filtered output stream to set as this object's outputstream,
253 * or {@code null} if no change.
254 */
255 public abstract void setStreams (InputStream i, OutputStream o);
256
257
258 /**
259 * If an authenticator is set on the HttpContext that owns this exchange,
260 * then this method will return the {@link HttpPrincipal} that represents
261 * the authenticated user for this HttpExchange.
262 * @return the HttpPrincipal, or {@code null} if no authenticator is set.
263 */
264 public abstract HttpPrincipal getPrincipal ();
265 }
|