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