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