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 } |