/* * 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 com.sun.net.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. *

* The typical life-cycle of a HttpExchange is shown in the sequence * below. *

  1. {@link #getRequestMethod()} to determine the command *
  2. {@link #getRequestHeaders()} to examine the request headers (if needed) *
  3. {@link #getRequestBody()} returns a {@link java.io.InputStream} for reading the request body. * After reading the request body, the stream is close. *
  4. {@link #getResponseHeaders()} to set any response headers, except content-length *
  5. {@link #sendResponseHeaders(int,long)} to send the response headers. Must be called before * next step. *
  6. {@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. *
* Terminating exchanges *
* 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. *

* 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). *

* 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:

    *
  1. close the request InputStream, if not already closed

  2. *
  3. close the response OutputStream, if not already closed.
  4. *
*/ 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. *

* Closing this stream implicitly * closes the InputStream returned from {@link #getRequestBody()} * (if it is not already closed). *

* 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 zero, 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 -1 * then no response body is being sent. *

* 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. *

* 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. -1 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 * protocol/majorVersion.minorVersion. 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. *

* 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 null */ 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. *

* 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. null * value is permitted. * @throws NullPointerException if name is null */ 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 null if no change. * @param o the filtered output stream to set as this object's outputstream, * or null 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 null if no authenticator is set. */ public abstract HttpPrincipal getPrincipal (); }