Class HttpExchange
- All Implemented Interfaces:
- Request,- AutoCloseable
- Direct Known Subclasses:
- HttpsExchange
 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- InputStreamfor 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- OutputStreamto send the response body. When the response body has been written, the stream must be closed to terminate the exchange.
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
- 
Constructor SummaryConstructors
- 
Method SummaryModifier and TypeMethodDescriptionabstract voidclose()Ends this exchange by doing the following in sequence: close the requestInputStream, if not already closed.abstract ObjectgetAttribute(String name) Filtermodules may store arbitrary objects withHttpExchangeinstances as an out-of-band communication mechanism.abstract HttpContextReturns theHttpContextfor this exchange.abstract InetSocketAddressReturns the local address on which the request was received.abstract HttpPrincipalIf an authenticator is set on theHttpContextthat owns this exchange, then this method will return theHttpPrincipalthat represents the authenticated user for thisHttpExchange.abstract StringReturns the protocol string from the request in the form protocol/majorVersion.minorVersion.abstract InetSocketAddressReturns the address of the remote entity invoking this request.abstract InputStreamReturns a stream from which the request body can be read.abstract HeadersReturns an immutableHeaderscontaining the HTTP headers that were included with this request.abstract StringReturns the request method.abstract URIReturns the requestURI.abstract OutputStreamReturns a stream to which the response body must be written.abstract intReturns the response code, if it has already been set.abstract HeadersReturns a mutableHeadersinto which the HTTP response headers can be stored and which will be transmitted as part of this response.abstract voidsendResponseHeaders(int rCode, long 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.abstract voidsetAttribute(String name, Object value) Filtermodules may store arbitrary objects withHttpExchangeinstances as an out-of-band communication mechanism.abstract voidUsed by Filters to wrap either (or both) of this exchange'sInputStreamandOutputStream, with the given filtered streams so that subsequent calls togetRequestBody()will return the givenInputStream, and calls togetResponseBody()will return the givenOutputStream.
- 
Constructor Details- 
HttpExchangeprotected HttpExchange()Constructor for subclasses to call.
 
- 
- 
Method Details- 
getRequestHeadersReturns an immutableHeaderscontaining the HTTP headers that were included with this request.The keys in this Headersare the header names, while the values are aListof 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 Headersare case-insensitive.- Specified by:
- getRequestHeadersin interface- Request
- Returns:
- a read-only Headerswhich can be used to access request headers.
 
- 
getResponseHeadersReturns a mutableHeadersinto which the HTTP response headers can be stored and which will be transmitted as part of this response.The keys in the Headersare the header names, while the values must be aListof Strings containing each value that should be included multiple times (in the order that they should be included).The keys in Headersare case-insensitive.- Returns:
- a writable Headerswhich can be used to set response headers.
 
- 
getRequestURIReturns the requestURI.- Specified by:
- getRequestURIin interface- Request
- Returns:
- the request URI
 
- 
getRequestMethodReturns the request method.- Specified by:
- getRequestMethodin interface- Request
- Returns:
- the request method string
 
- 
getHttpContextReturns theHttpContextfor this exchange.- Returns:
- the HttpContext
 
- 
closepublic abstract void close()Ends this exchange by doing the following in sequence:-  close the request InputStream, if not already closed.
-  close the response OutputStream, if not already closed.
 - Specified by:
- closein interface- AutoCloseable
 
-  close the request 
- 
getRequestBodyReturns 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 theInputStream.close()call will read and discard remaining data (up to an implementation specific number of bytes).- Returns:
- the stream from which the request body can be read
 
- 
getResponseBodyReturns 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 InputStreamreturned fromgetRequestBody()(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 ofOutputStreamwill throw anIOException. If too few bytes are written then the streamOutputStream.close()will throw anIOException. In both cases, the exchange is aborted and the underlying TCP connection closed.- Returns:
- the stream to which the response body is written
 
- 
sendResponseHeadersStarts 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 thanzero, this specifies an exact number of bytes to send and the application must send that exact amount of data. If the response length parameter iszero, then chunked transfer encoding is used and an arbitrary amount of data may be sent. The application terminates the response body by closing theOutputStream. If response length has the value-1then 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().- Implementation Note:
- This implementation allows the caller to instruct the
 server to force a connection close after the exchange terminates, by
 supplying a Connection: closeheader to the response headers beforesendResponseHeadersis called.
- Parameters:
- rCode- the response code to send
- responseLength- 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.
- Throws:
- IOException- if the response headers have already been sent or an I/O error occurs
- See Also:
 
- 
getRemoteAddressReturns the address of the remote entity invoking this request.- Returns:
- the InetSocketAddressof the caller
 
- 
getResponseCodepublic abstract int getResponseCode()Returns the response code, if it has already been set.- Returns:
- the response code, if available. -1if not available yet.
 
- 
getLocalAddressReturns the local address on which the request was received.- Returns:
- the InetSocketAddressof the local interface
 
- 
getProtocolReturns the protocol string from the request in the form protocol/majorVersion.minorVersion. For example, "HTTP/1.1".- Returns:
- the protocol string from the request
 
- 
getAttributeFiltermodules may store arbitrary objects withHttpExchangeinstances as an out-of-band communication mechanism. Other filters or the exchange handler may then access these objects.Each Filterclass will document the attributes which they make available.- Parameters:
- name- the name of the attribute to retrieve
- Returns:
- the attribute object, or nullif it does not exist
- Throws:
- NullPointerException- if name is- null
 
- 
setAttributeFiltermodules may store arbitrary objects withHttpExchangeinstances as an out-of-band communication mechanism. Other filters or the exchange handler may then access these objects.Each Filterclass will document the attributes which they make available.- Parameters:
- name- the name to associate with the attribute value
- value- the object to store as the attribute value.- nullvalue is permitted.
- Throws:
- NullPointerException- if name is- null
 
- 
setStreamsUsed by Filters to wrap either (or both) of this exchange'sInputStreamandOutputStream, with the given filtered streams so that subsequent calls togetRequestBody()will return the givenInputStream, and calls togetResponseBody()will return the givenOutputStream. The streams provided to this call must wrap the original streams, and may be (but are not required to be) sub-classes ofFilterInputStreamandFilterOutputStream.- Parameters:
- i- the filtered input stream to set as this object's- Inputstream, or- nullif no change
- o- the filtered output stream to set as this object's- Outputstream, or- nullif no change
 
- 
getPrincipalIf an authenticator is set on theHttpContextthat owns this exchange, then this method will return theHttpPrincipalthat represents the authenticated user for thisHttpExchange.- Returns:
- the HttpPrincipal, ornullif no authenticator is set
 
 
-