diff -r 4ebc2e2fb97c -r 71c04702a3d5 src/jdk.httpserver/share/classes/com/sun/net/httpserver/HttpExchange.java --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/src/jdk.httpserver/share/classes/com/sun/net/httpserver/HttpExchange.java Tue Sep 12 19:03:39 2017 +0200 @@ -0,0 +1,264 @@ +/* + * Copyright (c) 2005, 2013, 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.*; + +/** + * 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. + *
  2. close the response OutputStream, if not already closed.
    3. + *
+ */ + 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 {@code 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 {@code -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 appropriate 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 {@literal > 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 {@literal <= -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} 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 {@code 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. {@code null} + * value is permitted. + * @throws NullPointerException if name is {@code 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 {@code null} if no change. + * @param o the filtered output stream to set as this object's outputstream, + * or {@code 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 {@code null} if no authenticator is set. + */ + public abstract HttpPrincipal getPrincipal (); +}