APIdia Launch Partner
Top Description Fields Constructors Methods
com.sun.net.httpserver

public abstract Class HttpExchange

extends Object
implements AutoCloseable, Request
Class Inheritance
All Implemented Interfaces
com.sun.net.httpserver.Request, java.lang.AutoCloseable
Known Direct Subclasses
com.sun.net.httpserver.HttpsExchange, sun.net.httpserver.DelegatingHttpExchange, sun.net.httpserver.HttpExchangeImpl
Imports
java.io.IOException, .InputStream, .OutputStream, java.net.InetSocketAddress, .URI
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. getRequestMethod() to determine the command.
  2. getRequestHeaders() to examine the request headers (if needed).
  3. getRequestBody() returns an InputStream for reading the request body. After reading the request body, the stream should be closed.
  4. getResponseHeaders() to set any response headers, except content-length.
  5. sendResponseHeaders(int, long) to send the response headers. Must be called before next step.
  6. 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.
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 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

Field Summary

Modifier and TypeField and Description
public static final long
RSPBODY_CHUNKED

The response body length is unspecified and will be chunk encoded

public static final long
RSPBODY_EMPTY

No response body is being sent with this response

Constructor Summary

AccessConstructor and Description
protected
HttpExchange()

Constructor for subclasses to call.

Method Summary

Modifier and TypeMethod and Description
public abstract void
close()

Redeclares java.lang.AutoCloseable.close.

Ends this exchange by doing the following in sequence:

  1. close the request InputStream, if not already closed.
  2. close the response OutputStream, if not already closed.
public abstract Object

Returns:

the attribute object, or null if it does not exist
getAttribute(String
the name of the attribute to retrieve
name)

Filter modules may store arbitrary objects with HttpExchange instances as an out-of-band communication mechanism.

public abstract HttpContext

Returns:

the HttpContext
getHttpContext()

Returns the HttpContext for this exchange.

public abstract InetSocketAddress

Returns:

the InetSocketAddress of the local interface
getLocalAddress()

Returns the local address on which the request was received.

public abstract HttpPrincipal

Returns:

the HttpPrincipal, or null if no authenticator is set
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.

public abstract String

Returns:

the protocol string from the request
getProtocol()

Returns the protocol string from the request in the form protocol/majorVersion.minorVersion.

public abstract InetSocketAddress

Returns:

the InetSocketAddress of the caller
getRemoteAddress()

Returns the address of the remote entity invoking this request.

public abstract InputStream

Returns:

the stream from which the request body can be read
getRequestBody()

Returns a stream from which the request body can be read.

public abstract Headers
getRequestHeaders()

Redeclares com.sun.net.httpserver.Request.getRequestHeaders.

Returns an immutable Headers containing the HTTP headers that were included with this request.

public abstract String
getRequestMethod()

Redeclares com.sun.net.httpserver.Request.getRequestMethod.

Returns the request method.

public abstract URI
getRequestURI()

Redeclares com.sun.net.httpserver.Request.getRequestURI.

Returns the request URI.

public abstract OutputStream

Returns:

the stream to which the response body is written
getResponseBody()

Returns a stream to which the response body must be written.

public abstract int

Returns:

the response code, if available. -1 if not available yet.
getResponseCode()

Returns the response code, if it has already been set.

public abstract Headers

Returns:

a writable Headers which can be used to set response 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.

public abstract void
sendResponseHeaders(int
the response code to send
rCode, long
if > 0, specifies a fixed response body length and that exact number of bytes must be written to the stream acquired from getResponseCode() If equal to RSPBODY_CHUNKED, then chunked encoding is used, and an arbitrary number of bytes may be written. If equal to RSPBODY_EMPTY, then no response body length is specified and no response body may be written. Any value <= -1 is treated the same as RSPBODY_EMPTY.
responseLength)

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.

public abstract void
setAttribute(String
the name to associate with the attribute value
name, Object
the object to store as the attribute value. null value is permitted.
value)

Filter modules may store arbitrary objects with HttpExchange instances as an out-of-band communication mechanism.

public abstract void
setStreams(InputStream
the filtered input stream to set as this object's Inputstream, or null if no change
i, OutputStream
the filtered output stream to set as this object's Outputstream, or null if no change
o)

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.

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

RSPBODY_CHUNKEDback to summary
public static final long RSPBODY_CHUNKED

The response body length is unspecified and will be chunk encoded

Since
26
See Also
sendResponseHeaders(int, long)
RSPBODY_EMPTYback to summary
public static final long RSPBODY_EMPTY

No response body is being sent with this response

Since
26
See Also
sendResponseHeaders(int, long)

Constructor Detail

HttpExchangeback to summary
protected HttpExchange()

Constructor for subclasses to call.

Method Detail

closeback to summary
public abstract void close()

Redeclares java.lang.AutoCloseable.close.

Ends this exchange by doing the following in sequence:

  1. close the request InputStream, if not already closed.
  2. close the response OutputStream, if not already closed.
getAttributeback to summary
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.

Parameters
name:String

the name of the attribute to retrieve

Returns:Object

the attribute object, or null if it does not exist

Exceptions
NullPointerException:
if name is null
getHttpContextback to summary
public abstract HttpContext getHttpContext()

Returns the HttpContext for this exchange.

Returns:HttpContext

the HttpContext

getLocalAddressback to summary
public abstract InetSocketAddress getLocalAddress()

Returns the local address on which the request was received.

Returns:InetSocketAddress

the InetSocketAddress of the local interface

getPrincipalback to summary
public 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.

Returns:HttpPrincipal

the HttpPrincipal, or null if no authenticator is set

getProtocolback to summary
public abstract String getProtocol()

Returns the protocol string from the request in the form protocol/majorVersion.minorVersion. For example, "HTTP/1.1".

Returns:String

the protocol string from the request

getRemoteAddressback to summary
public abstract InetSocketAddress getRemoteAddress()

Returns the address of the remote entity invoking this request.

Returns:InetSocketAddress

the InetSocketAddress of the caller

getRequestBodyback to summary
public abstract InputStream getRequestBody()

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 InputStream#close() call will read and discard remaining data (up to an implementation specific number of bytes).

Returns:InputStream

the stream from which the request body can be read

getRequestHeadersback to summary
public abstract Headers getRequestHeaders()

Redeclares com.sun.net.httpserver.Request.getRequestHeaders.

Doc from com.sun.net.httpserver.Request.getRequestHeaders.

Returns an immutable 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 java.util.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.

getRequestMethodback to summary
public abstract String getRequestMethod()

Redeclares com.sun.net.httpserver.Request.getRequestMethod.

Doc from com.sun.net.httpserver.Request.getRequestMethod.

Returns the request method.

getRequestURIback to summary
public abstract URI getRequestURI()

Redeclares com.sun.net.httpserver.Request.getRequestURI.

Doc from com.sun.net.httpserver.Request.getRequestURI.

Returns the request URI.

getResponseBodyback to summary
public abstract OutputStream getResponseBody()

Returns a stream to which the response body must be written. 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.

Returns:OutputStream

the stream to which the response body is written

getResponseCodeback to summary
public abstract int getResponseCode()

Returns the response code, if it has already been set.

Returns:int

the response code, if available. -1 if not available yet.

getResponseHeadersback to summary
public 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.

The keys in the Headers are the header names, while the values must be a java.util.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.

Returns:Headers

a writable Headers which can be used to set response headers.

sendResponseHeadersback to summary
public abstract void sendResponseHeaders(int rCode, long responseLength) throws IOException

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 has the value RSPBODY_CHUNKED (zero) then the response body uses chunked transfer encoding 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 RSPBODY_EMPTY 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().

API Note

If a response body is to be sent from a byte array and the length of the array is used as the responseLength parameter, then note the behavior in the case when the array is empty. In that case, the responseLength will be zero which is the value of RSPBODY_CHUNKED resulting in a zero length, but chunked encoded response body. While this is not incorrect, it may be preferable to check for an empty array and set responseLength to RSPBODY_EMPTY instead. Also, when sending a chunked encoded response body, whatever length, the output stream must be explicitly closed by the handler.

Implementation Note

This implementation allows the caller to instruct the server to force a connection close after the exchange terminates, by supplying a Connection: close header to the response headers before sendResponseHeaders is called.

Parameters
rCode:int

the response code to send

responseLength:long

if > 0, specifies a fixed response body length and that exact number of bytes must be written to the stream acquired from getResponseCode() If equal to RSPBODY_CHUNKED, then chunked encoding is used, and an arbitrary number of bytes may be written. If equal to RSPBODY_EMPTY, then no response body length is specified and no response body may be written. Any value <= -1 is treated the same as RSPBODY_EMPTY.

Exceptions
IOException:
if the response headers have already been sent or an I/O error occurs
See Also
HttpExchange#getResponseBody()
setAttributeback to summary
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.

Parameters
name:String

the name to associate with the attribute value

value:Object

the object to store as the attribute value. null value is permitted.

Exceptions
NullPointerException:
if name is null
setStreamsback to summary
public abstract void setStreams(InputStream i, OutputStream o)

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. The streams provided to this call must wrap the original streams, and may be (but are not required to be) sub-classes of java.io.FilterInputStream and java.io.FilterOutputStream.

Parameters
i:InputStream

the filtered input stream to set as this object's Inputstream, or null if no change

o:OutputStream

the filtered output stream to set as this object's Outputstream, or null if no change