Request
, AutoCloseable
HttpsExchange
public abstract class HttpExchange extends Object implements AutoCloseable, Request
The typical life-cycle of a HttpExchange
is shown in the sequence below:
getRequestMethod()
to determine the command. getRequestHeaders()
to examine the request headers (if needed). getRequestBody()
returns an InputStream
for reading the request body. After reading the request body, the stream should be closed. getResponseHeaders()
to set any response headers, except content-length. sendResponseHeaders(int,long)
to send the response headers. Must be called before next step. getResponseBody()
to get a OutputStream
to send the response body. When the response body has been written, the stream must be closed to terminate the exchange. 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 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.Modifier | Constructor | Description |
---|---|---|
protected |
Constructor for subclasses to call. |
Modifier and Type | Method | Description |
---|---|---|
abstract void |
close() |
Ends this exchange by doing the following in sequence: close the request InputStream , if not already closed. |
abstract Object |
getAttribute |
Filter modules may store arbitrary objects with HttpExchange instances as an out-of-band communication mechanism. |
abstract HttpContext |
getHttpContext() |
Returns the HttpContext for this exchange. |
abstract InetSocketAddress |
getLocalAddress() |
Returns the local address on which the request was received. |
abstract HttpPrincipal |
getPrincipal() |
If an authenticator is set on the HttpContext that owns this exchange, then this method will return the HttpPrincipal that represents the authenticated user for this HttpExchange . |
abstract String |
getProtocol() |
Returns the protocol string from the request in the form protocol/majorVersion.minorVersion. |
abstract InetSocketAddress |
getRemoteAddress() |
Returns the address of the remote entity invoking this request. |
abstract InputStream |
getRequestBody() |
Returns a stream from which the request body can be read. |
abstract Headers |
getRequestHeaders() |
Returns an immutable Headers containing the HTTP headers that were included with this request. |
abstract String |
getRequestMethod() |
Returns the request method. |
abstract URI |
getRequestURI() |
Returns the request URI . |
abstract OutputStream |
getResponseBody() |
Returns a stream to which the response body must be written. |
abstract int |
getResponseCode() |
Returns the response code, if it has already been set. |
abstract Headers |
getResponseHeaders() |
Returns a mutable Headers into which the HTTP response headers can be stored and which will be transmitted as part of this response. |
abstract void |
sendResponseHeaders |
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. |
abstract void |
setAttribute |
Filter modules may store arbitrary objects with HttpExchange instances as an out-of-band communication mechanism. |
abstract void |
setStreams |
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 getRequestBody() will return the given InputStream , and calls to getResponseBody() will return the given OutputStream . |
protected HttpExchange()
public abstract Headers getRequestHeaders()
Headers
containing the HTTP headers that were included with this request. The keys in this Headers
are the header names, while the values are a List
of Strings containing each value that was included in the request, in the order they were included. Header fields appearing multiple times are represented as multiple string values.
The keys in Headers
are case-insensitive.
getRequestHeaders
in interface Request
Headers
which can be used to access request headers.public abstract Headers getResponseHeaders()
Headers
into which the HTTP response headers can be stored and which will be transmitted as part of this response. The keys in the Headers
are 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 Headers
are case-insensitive.
Headers
which can be used to set response headers.public abstract URI getRequestURI()
URI
.getRequestURI
in interface Request
URI
public abstract String getRequestMethod()
getRequestMethod
in interface Request
public abstract HttpContext getHttpContext()
HttpContext
for this exchange.HttpContext
public abstract void close()
InputStream
, if not already closed. OutputStream
, if not already closed. close
in interface AutoCloseable
public abstract InputStream getRequestBody()
InputStream.close()
call will read and discard remaining data (up to an implementation specific number of bytes).public abstract OutputStream getResponseBody()
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 getRequestBody()
(if it is not already closed).
If the call to sendResponseHeaders(int, long)
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 the write method of OutputStream
will throw an IOException
. If too few bytes are written then the stream OutputStream.close()
will throw an IOException
. In both cases, the exchange is aborted and the underlying TCP connection closed.
public abstract void sendResponseHeaders(int rCode, long responseLength) throws IOException
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 appropriate value depending on the response length parameter.
This method must be called prior to calling getResponseBody()
.
Connection: close
header to the response headers before sendResponseHeaders
is called.rCode
- the response code to sendresponseLength
- if > 0, specifies a fixed response body length and that exact number of bytes must be written to the stream acquired from getResponseCode()
If == 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.IOException
- if the response headers have already been sent or an I/O error occurspublic abstract InetSocketAddress getRemoteAddress()
InetSocketAddress
of the callerpublic abstract int getResponseCode()
-1
if not available yet.public abstract InetSocketAddress getLocalAddress()
InetSocketAddress
of the local interfacepublic abstract String getProtocol()
HTTP/1.1
".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.
name
- the name of the attribute to retrievenull
if it does not existNullPointerException
- if name is null
public abstract void setAttribute(String name, Object value)
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.
name
- the name to associate with the attribute valuevalue
- the object to store as the attribute value. null
value is permitted.NullPointerException
- if name is null
public abstract void setStreams(InputStream i, OutputStream o)
InputStream
and OutputStream
, with the given filtered streams so that subsequent calls to getRequestBody()
will return the given InputStream
, and calls to getResponseBody()
will return the given OutputStream
. The streams provided to this call must wrap the original streams, and may be (but are not required to be) sub-classes of FilterInputStream
and FilterOutputStream
.i
- the filtered input stream to set as this object's Inputstream
, or null
if no changeo
- the filtered output stream to set as this object's Outputstream
, or null
if no changepublic abstract HttpPrincipal getPrincipal()
HttpContext
that owns this exchange, then this method will return the HttpPrincipal
that represents the authenticated user for this HttpExchange
.HttpPrincipal
, or null
if no authenticator is set
© 1993, 2023, Oracle and/or its affiliates. All rights reserved.
Documentation extracted from Debian's OpenJDK Development Kit package.
Licensed under the GNU General Public License, version 2, with the Classpath Exception.
Various third party code in OpenJDK is licensed under different licenses (see Debian package).
Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
https://docs.oracle.com/en/java/javase/21/docs/api/jdk.httpserver/com/sun/net/httpserver/HttpExchange.html