Class Request
- Direct Known Subclasses:
TestRequest
Provides a set of accessor functions to fetch the individual fields of the HTTP request.
Utility methods that are generically useful for manipulating HTTP requests are included here as well. An instance of this class is passed to handlers. There will be exactly one request object per thead at any time.
The fields
headers
,
query
, and
url
, and the method
getQueryData()
are most often used to examine the content of the request.
The field
props
contains information about the server, or up-stream handlers.
The methods
sendResponse(String, String, int)
and
sendError(int, String)
are commonly used to return content to the client. The methods
addHeader(String)
and
setStatus(int)
can be used to modify the response headers
and return code respectively before the response is sent.
Many of the other methods are used internally, but can be useful to
handlers that need finer control over the output that the above methods
provide. Note that the order of the methods is important. For instance,
the user cannot change the HTTP response headers (by calling the
addHeader
method or by modifying the
responseHeaders
field) after having already sent an HTTP
response.
A number of the fields in the Request
object are public,
by design. Many of the methods are convenience methods; the underlying
data fields are meant to be accessed for more complicated operations,
such as changing the URL or deleting HTTP response headers.
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionstatic class
TheHttpOutputStream
provides the convenience methodwriteBytes
for writing the byte representation of a string, without bringing in the overhead and the deprecated warnings associated with ajava.io.DataOutputStream
. -
Field Summary
FieldsModifier and TypeFieldDescriptionThe header "Connection" usually controls whether the client connection will be of type "Keep-Alive" or "close".The HTTP request headers.protected boolean
protected HttpInputStream
boolean
true
if the client requested a persistent connection,false
otherwise.static final int
Maximum number of blank lines allowed between requests before aborting the connecion.The HTTP request method, such as "GET", "POST", or "PUT".The HTTP response to the client is written to this stream.byte[]
The uploaded content of this request, usually from a POST.A set of properties local to this request.The HTTP protocol specified in the request, either "HTTP/1.0" or "HTTP/1.1".The query string specified after the URL, or""
if no query string was specified.protected int
The HTTP response headers.The server that initiated this request.APropertiesList
object that wrapsserver.props
.This is the server's protocol.Our connection to the client.long
Time stamp for start of this request - set, but not used.protected int
protected String
The URL specified in the request, not including any "?" query string.int
Derived fromprotocol
, the version of the HTTP protocol used for this request. -
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionvoid
Adds a response header to the HTTP response.void
Adds a response header to the HTTP response.boolean
Adds the givenDictionary
to the set of properties that are searched byrequest.props.getProperty()
.Retrieves the query data as a hashtable.getQueryData
(Hashtable table) Retrieves the query data as a hashtable.boolean
Reads an HTTP request from the socket.getRequestHeader
(String key) Returns the value that the given case-insensitive key maps to in the HTTP request headers.int
Return uses of this socketThe socket from which the HTTP request was received, and to where the HTTP response will be written.int
Return the status code.void
Logs a message by callingServer.log
.void
Logs a message by callingServer.log
.void
Responds to an HTTP request with a redirection reply, telling the client that the requested url has moved.boolean
Removes aDictionary
added byaddSharedProps
.void
Sends a HTTP error response to the client.void
Sends a HTTP error response to the client.void
sendHeaders
(int code, String type, int length) Sends the HTTP status line and response headers to the client.void
sendResponse
(byte[] body, String type) Sends an HTTP response to the client.void
sendResponse
(InputStream in, int length, String type, int code) Sends the contents of the given input stream as the HTTP response.void
sendResponse
(String body) Convenience method that sends an HTTP response to the client with a "Content-Type" of "text/html" and the default HTTP status code.void
sendResponse
(String body, String type) Convenience method that sends an HTTP response to the client with the default HTTP status code.void
sendResponse
(String body, String type, int code) Sends an HTTP response to the client.Returns the server's fully-qualified base URL.void
setStatus
(int code) Sets the status code of the HTTP response.protected void
Set the HTTP status code and status phrase of this request.toString()
Returns a string representation of thisRequest
.
-
Field Details
-
MAX_BLANKS
public static final int MAX_BLANKSMaximum number of blank lines allowed between requests before aborting the connecion. The spec allows 0, but some clients add one or more.- See Also:
-
server
The server that initiated this request. Only under rare circumstances should this be modified. -
sock
Our connection to the client. Only under rare circumstances would this need to be modified. -
in
-
props
A set of properties local to this request. The property is wrapped in aPropertiesList
object and initially is the head of a linked list of properties that are searched in order. This is useful for handlers that wish to communicate via properties to down-stream handlers, such as modifying a server property for a particular request. Some handlers may even add entire new sets of properties onto the front ofrequest.props
to temporarily modify the properties seen by downstream handlers. -
serverProps
APropertiesList
object that wrapsserver.props
. When thisrequest
is created, a newPropertiesList
wrappingserver.props
is created and added to a list consisting only ofprops
andserverProps
. -
out
The HTTP response to the client is written to this stream. Normally the convenience methods, such assendResponse
, are used to send the response, but this field is available if a handler needs to generate the response specially.If the user chooses to write the response directly to this stream, the user is still encouraged to use the convenience methods, such as
sendHeaders
, to first send the HTTP response headers. TheFilterHandler
examines the HTTP response headers set by the convenience methods to determine whether to filter the output.Note that the HTTP response headers will not automatically be sent as a side effect if the user writes to this stream. The user would either need to call the convenience method
sendHeaders
or need to generate the HTTP response headers themselves.This variable is declared as a
Request.HttpOutputStream
, which provides the convenience methodwriteBytes
to write the byte representation of a string back to the client. If the user does not need this functionality, this variable may be accessed simply as a normalOutputStream
. -
requestsLeft
protected int requestsLeft -
method
The HTTP request method, such as "GET", "POST", or "PUT". -
url
The URL specified in the request, not including any "?" query string.NOTE: Traditionally handlers modify this as needed. The request property "url.orig" is set to match the url at creation time, and should be considered "Read only", for those cases where the original url is required.
-
query
The query string specified after the URL, or""
if no query string was specified. -
protocol
The HTTP protocol specified in the request, either "HTTP/1.0" or "HTTP/1.1".- See Also:
-
version
public int versionDerived fromprotocol
, the version of the HTTP protocol used for this request. Either10
for "HTTP/1.0" or11
for "HTTP/1.1". -
headers
The HTTP request headers. Keys and values in this table correspond the field names and values from each line in the HTTP header; field names are case-insensitive, but the case of the values is preserved. The order of entries in this table corresponds to the order in which the request headers were seen. Multiple header lines with the same key are stored as separate entries in the table. -
postData
public byte[] postDataThe uploaded content of this request, usually from a POST. Set tonull
if the request has no content. -
keepAlive
public boolean keepAlivetrue
if the client requested a persistent connection,false
otherwise. Derived from theprotocol
and theheaders
,When "Keep-Alive" is requested, the client can issue multiple, consecutive requests via a single socket connection. By default:
- HTTP/1.0 requests are not Keep-Alive, unless the "Connection: Keep-Alive" header was present.
- HTTP/1.1 requests are Keep-Alive, unless the "Connection: close" header was present.
true
tofalse
to forcefully close the connection to the client after sending the response. The user can change this value fromfalse
totrue
if the client is using a different header to request a persistent connection. SeeconnectionHeader
.Regardless of this value, if an error is detected while receiving or responding to an HTTP request, the connection will be closed.
-
connectionHeader
The header "Connection" usually controls whether the client connection will be of type "Keep-Alive" or "close". The same header is written back to the client in the response headers.The field
keepAlive
is set based on the value of the "Connection" header. However, not all clients use "Connection" to request that the connection be kept alive. For instance (although it does not appear in the HTTP/1.0 or HTTP/1.1 documentation) both Netscape and IE use the "Proxy-Connection" header when issuing requests via an HTTP proxy. If aHandler
is written to respond to HTTP proxy requests, it should setkeepAlive
depending on the value of the "Proxy-Connection" header, and setconnectionHeader
to "Proxy-Connection", since the convenience methods likesetResponse()
use these fields when constructing the response. The server does not handle the "Proxy-Connection" header by default, since trying to pre-anticipate all the exceptions to the specification is a "slippery slope". -
serverProtocol
This is the server's protocol. It is normally null, but may be overriden to change the protocol on a per-request basis. If not set then server.protocol should be used instead. -
statusCode
protected int statusCode -
statusPhrase
-
responseHeaders
The HTTP response headers. Keys and values in this table correspond to the HTTP headers that will be written back to the client when the response is sent. The order of entries in this table corresponds to the order in which the HTTP headers will be sent. Multiple header lines with the same key will be stored as separate entries in the table.- See Also:
-
headersSent
protected boolean headersSent -
startMillis
public long startMillisTime stamp for start of this request - set, but not used.
-
-
Constructor Details
-
Request
Create a new http request. Requests are created by the server for use by handlers.- Parameters:
server
- The server that owns this request.sock
- The socket of the incoming HTTP request.
-
Request
protected Request()Needed by VelocityFilter.Vrequest. Should not be used to create aRequest
object.
-
-
Method Details
-
toString
Returns a string representation of thisRequest
. The string representation is the first line (the method line) of the HTTP request that thisRequest
is handling. Useful for debugging. -
getRequest
Reads an HTTP request from the socket.- Returns:
true
if the request was successfully read and parsed,false
if the request was malformed.- Throws:
IOException
- if there was an IOException reading from the socket. See the socket documentation for a description of socket exceptions.
-
getSocket
The socket from which the HTTP request was received, and to where the HTTP response will be written. The user should not directly read from or write to this socket. The socket is provided other purposes, for example, imagine a handler that provided different content depending upon the IP address of the client.- Returns:
- The client socket that issued this HTTP request.
-
log
Logs a message by callingServer.log
. Typically a message is generated on the console or in a log file, if thelevel
is less than the current server log setting.- Parameters:
level
- The severity of the message.message
- The message that will be logged.- See Also:
-
log
Logs a message by callingServer.log
. Typically a message is generated on the console or in a log file, if thelevel
is less than the current server log setting.- Parameters:
level
- The severity of the message.obj
- The object that the message relates to.message
- The message that will be logged.- See Also:
-
getRequestHeader
Returns the value that the given case-insensitive key maps to in the HTTP request headers. In order to do fancier things like changing or deleting an existing request header, the user may directly access theheaders
field.- Parameters:
key
- The key to look for in the HTTP request headers. May not benull
.- Returns:
- The value to which the given key is mapped, or
null
if the key is not in the headers. - See Also:
-
getQueryData
Retrieves the query data as a hashtable. This includes both the query information included as part of the url and any posted "application/x-www-form-urlencoded" data.- Parameters:
table
- An existing hashtable in which to put the query data as name/value pairs. May benull
, in which case a new hashtable is allocated.- Returns:
- The hashtable in which the query data was stored.
-
getQueryData
Retrieves the query data as a hashtable. This includes both the query information included as part of the url and any posted "application/x-www-form-urlencoded" data.- Returns:
- The hashtable in which the query data was stored.
-
setStatus
public void setStatus(int code) Sets the status code of the HTTP response. The default status code for a response is200
if this method is not called.An HTTP status phrase will be chosen based on the given status code. For example, the status code
404
will get the status phrase "Not Found".If this method is called, it must be called before
sendHeaders
is either directly or indirectly called. Otherwise, it will have no effect.- Parameters:
code
- The HTTP status code, such as200
or404
. If < 0, the HTTP status code will not be changed.- See Also:
-
setStatus
Set the HTTP status code and status phrase of this request. The given status will be sent to the client when the user directly or indirectly calls the methodsendHeaders
. The given status phrase replaces the default HTTP status phrase normally associated with the given status code.- Parameters:
code
- The HTTP status code, such as200
or404
.message
- The HTTP status phrase, such as"Okey dokey"
or"I don't see it"
.- See Also:
-
getStatus
public int getStatus()Return the status code. -
getReuseCount
public int getReuseCount()Return uses of this socket -
addHeader
Adds a response header to the HTTP response. In order to do fancier things like appending a value to an existing response header, the user may directly access theresponseHeaders
field.If this method is called, it must be called before
sendHeaders
is either directly or indirectly called. Otherwise, it will have no effect.- Parameters:
key
- The header name.value
- The value for the request header.- See Also:
-
addHeader
Adds a response header to the HTTP response. In order to do fancier things like appending a value to an existing response header, the user may directly access theresponseHeaders
field.If this method is called, it must be called before
sendHeaders
is either directly or indirectly called. Otherwise, it will have no effect.- Parameters:
line
- The HTTP response header, of the form "key
:value
".- See Also:
-
sendResponse
Sends an HTTP response to the client.This method first calls
sendHeaders
to send the HTTP response headers, then sends the given byte array as the HTTP response body. If the request method is HEAD, or the result code is "204", the body is not sent.The "Content-Length" will be set to the length of the given byte array. The "Content-Type" will be set to the given MIME type.
- Parameters:
body
- The array of bytes to send as the HTTP response body. May not benull
.type
- The MIME type of the response, such as "text/html". May benull
to use the existing "Content-Type" response header (if any).- Throws:
IOException
- if there was an I/O error while sending the response to the client.- See Also:
-
sendResponse
Sends an HTTP response to the client.This method first calls
sendHeaders
to send the HTTP response headers. It then writes out the given string to the client as a sequence of bytes. Each character in the string is written out by discarding its high eight bits.The "Content-Length" will be set to the length of the string. The "Content-Type" will be set to the given MIME type.
Note: to use a different character encoding, use
sendResponse(body.getBytes(encoding)...)
instead.- Parameters:
body
- The string to send as the HTTP response body. May not benull
. If the request method is HEAD, the body is not sent.type
- The MIME type of the response, such as "text/html". May benull
to preserve the existing "Content-Type" response header (if any).code
- The HTTP status code for the response, such as200
. May be < 0 to preserve the existing status code.- Throws:
IOException
- if there was an I/O error while sending the response to the client.- See Also:
-
sendResponse
Convenience method that sends an HTTP response to the client with a "Content-Type" of "text/html" and the default HTTP status code.- Parameters:
body
- The string to send as the HTTP response body.- Throws:
IOException
- See Also:
-
sendResponse
Convenience method that sends an HTTP response to the client with the default HTTP status code.- Parameters:
body
- The string to send as the HTTP response body. If the request method is HEAD, only the headers are sent to the client.type
- The MIME type of the response.- Throws:
IOException
- See Also:
-
sendResponse
Sends the contents of the given input stream as the HTTP response.This method first calls
sendHeaders
to send the HTTP response headers. It then transfers a total oflength
bytes of data from the given input stream to the client as the HTTP response body.This method takes care of setting the "Content-Length" header if the actual content length is known, or the "Transfer-Encoding" header if the content length is not known (for HTTP/1.1 clients only).
This method may set the
keepAlive
tofalse
before returning, if fewer thanlength
bytes could be read. If the request method is HEAD, only the headers are sent.- Parameters:
in
- The input stream to read from.length
- The content length. The number of bytes to send to the client. May be < 0, in which case this method will read until reaching the end of the input stream.type
- The MIME type of the response, such as "text/html". May benull
to preserve the existing "Content-Type" response header (if any).code
- The HTTP status code for the response, such as200
. May be < 0 to preserve the existing status code.- Throws:
IOException
- if there was an I/O error while sending the response to the client.
-
sendError
Sends a HTTP error response to the client.- Parameters:
code
- The HTTP status code.clientMessage
- A short message to be included in the error response and logged to the server.
-
sendError
Sends a HTTP error response to the client.- Parameters:
code
- The HTTP status code.clientMessage
- A short message to be included in the error response.logMessage
- A short message to be logged to the server. This message is not sent to the client.
-
sendHeaders
Sends the HTTP status line and response headers to the client. This method is automatically invoked bysendResponse
, but can be manually invoked if the user needs direct access to the client's output stream. If this method is not called, then the HTTP status and response headers will not automatically be sent to the client; the user would be responsible for forming the entire HTTP response.The user may call the
addHeader
method or modify theresponseHeaders
field before calling this method. This method then adds a number of HTTP headers, as follows:- "Date" - the current time, if this header is not already present.
- "Server" - the server's name (from
server.name
), if this header is not already present. - "Connection" - "Keep-Alive" or "close", depending upon the
keepAlive
field. - "Content-Length" - set to the given
length
. - "Content-Type" - set to the given
type
.
The string used for "Connection" header actually comes from the
connectionHeader
field.- Parameters:
code
- The HTTP status code for the response, such as200
. May be < 0 to preserve the existing status code.type
- The MIME type of the response, such as "text/html". May benull
to preserve the existing "Content-Type" response header (if any).length
- The length of the response body. May be < 0 if the length is unknown and/or to preserve the existing "Content-Length" response header (if any).- Throws:
IOException
- if there was an I/O error while sending the headers to the client.- See Also:
-
redirect
Responds to an HTTP request with a redirection reply, telling the client that the requested url has moved. Generally, this is used if the client did not put a '/' on the end of a directory.- Parameters:
url
- The URL the client should have requested. This URL may be fully-qualified (in the form "http://....") or host-relative (in the form "/...").body
- The body of the redirect response, ornull
to send a hardcoded message.- Throws:
IOException
-
serverUrl
Returns the server's fully-qualified base URL. This is "http://" followed by the server's hostname and port.If the HTTP request header "Host" is present, it specifies the hostname and port that will be used instead of the server's internal name for itself. Due bugs in certain browsers, when using the server's internal name, the port number will be elided if it is
80
.- Returns:
- The string representation of the server's URL.
-