| java.lang.Object
 sunlabs.brazil.server.Request
| Request | | public class Request (Code) | | Represents an HTTP transaction. A new instance is created
by the server for each connection.
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
Request.headers ,
Request.query , and
Request.url , and the method
Request.getQueryData() are most often used to examine the content of the request.
The field
Request.props contains information about the server, or up-stream handlers.
The methods
Request.sendResponse(String,String,int) and
Request.sendError(intString) are commonly used to return content to the client. The methods
Request.addHeader(String) and
Request.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.
See Also: Handler
See Also: Server
author:
Stephen Uhler (stephen.uhler@sun.com)
author:
Colin Stevens (colin.stevens@sun.com)
version:
1.47, 00/12/05 |
| Inner Class :public static class RechainableProperties extends Properties | |
| Field Summary | |
| public String | connectionHeader
The header "Connection" usually controls whether the client
connection will be of type "Keep-Alive" or "close". | | public MimeHeaders | headers
The HTTP request headers. | | HttpInputStream | in
| | public boolean | keepAlive
true if the client requested a persistent connection,
false otherwise. | | public String | method
The HTTP request method, such as "GET", "POST", or "PUT". | | public HttpOutputStream | out
The HTTP response to the client is written to this stream. | | public byte[] | postData
The uploaded content of this request, usually from a POST. | | public RechainableProperties | props
A set of properties local to this request. | | public String | protocol
The HTTP protocol specified in the request, either "HTTP/1.0" or
"HTTP/1.1". | | public String | query
The query string specified after the URL, or "" if no
query string was specified. | | public MimeHeaders | responseHeaders
The HTTP response headers. | | Server | server
| | Socket | sock
| | public long | startMillis
Time stamp for start of this request - set, but not used. | | int | statusCode
| | String | statusPhrase
| | public String | url
The URL specified in the request, not including any "?" query
string. | | public int | version
Derived from
Request.protocol , the version of the HTTP protocol
used for this request. |
| Method Summary | |
| public void | addHeader(String key, String value)
Adds a response header to the HTTP response. | | public void | addHeader(String line)
Adds a response header to the HTTP response. | | public Hashtable | getQueryData(Hashtable table)
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 asname/value pairs. | | public Hashtable | getQueryData()
Retrieves the query data as a hashtable. | | boolean | getRequest(Properties defaults)
Reads an HTTP request from the socket.
Parameters:
props - The server props associated with this request true if the request was successfully read andparsed, false if the request was malformed.
throws:
IOException - if there was an IOException reading from the socket. | | public String | getRequestHeader(String key)
Returns the value that the given case-insensitive key maps to
in the HTTP request headers. | | public int | getReuseCount()
| | public Socket | getSocket()
The socket from which the HTTP request was received, and to where the
HTTP response will be written. | | public int | getStatus()
Return the status code. | | public void | log(int level, String message)
Logs a message by calling Server.log. | | public void | log(int level, Object obj, String message)
Logs a message by calling Server.log. | | public void | redirect(String url, String body)
Responds to an HTTP request with a redirection reply, telling the
client that the requested url has moved. | | public void | sendError(int code, String clientMessage)
Sends a HTTP error response to the client. | | public void | sendError(int code, String clientMessage, String logMessage)
Sends a HTTP error response to the client. | | public void | sendHeaders(int code, String type, int length)
Sends the HTTP status line and response headers to the client. | | public void | sendResponse(byte[] body, String type)
Sends an HTTP response to the client. | | public void | sendResponse(String body, String type, int code)
Sends an HTTP response to the client. | | public 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. | | public void | sendResponse(String body, String type)
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. | | public void | sendResponse(InputStream in, int length, String type, int code)
Sends the contents of the given input stream as the HTTP response.
This method first calls sendHeaders to send the HTTP
response headers. | | public String | serverUrl()
Returns the server's fully-qualified base URL. | | public void | setStatus(int code)
Sets the status code of the HTTP response. | | boolean | shouldKeepAlive()
| | public String | toString()
Returns a string representation of this Request.
The string representation is the first line (the method line) of the
HTTP request that this Request is handling. |
| connectionHeader | | public String connectionHeader(Code) | | 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
Request.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 a Handler is written to
respond to HTTP proxy requests, it should set keepAlive
depending on the value of the "Proxy-Connection" header, and set
connectionHeader to "Proxy-Connection", since the
convenience methods like setResponse() 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".
|
| headers | | public MimeHeaders headers(Code) | | 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.
|
| keepAlive | | public boolean keepAlive(Code) | | true if the client requested a persistent connection,
false otherwise. Derived from the
Request.protocol and
the
Request.headers ,
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.
The user can change this value from true to
false to forcefully close the connection to the client
after sending the response. The user can change this value from
false to true if the client is using a
different header to request a persistent connection. See
Request.connectionHeader .
Regardless of this value, if an error is detected while receiving
or responding to an HTTP request, the connection will be closed.
|
| method | | public String method(Code) | | The HTTP request method, such as "GET", "POST", or "PUT".
|
| out | | public HttpOutputStream out(Code) | | The HTTP response to the client is written to this stream. Normally
the convenience methods, such as sendResponse, 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.
The
sunlabs.brazil.filter.FilterHandler 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 method writeBytes 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 normal OutputStream.
See Also: Request.sendResponse(String,String,int)
See Also: Request.sendHeaders(int,String,int) |
| postData | | public byte[] postData(Code) | | The uploaded content of this request, usually from a POST. Set to
null if the request has no content.
|
| props | | public RechainableProperties props(Code) | | A set of properties local to this request. Created with
server.props as the default. 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.
This variable is declared as a Request.RechainableProperties,
which provides the ability to reorder the properties in an existing
request, to insert a whole new set of properties into a request w/o
having to copy those properties one by one into the request's
properties. If the user does not need this functionality, this
variable may be accessed simply as a normal Properties.
|
| protocol | | public String protocol(Code) | | The HTTP protocol specified in the request, either "HTTP/1.0" or
"HTTP/1.1".
See Also: Request.version |
| query | | public String query(Code) | | The query string specified after the URL, or "" if no
query string was specified.
|
| responseHeaders | | public MimeHeaders responseHeaders(Code) | | 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: Request.addHeader(String,String) |
| startMillis | | public long startMillis(Code) | | Time stamp for start of this request - set, but not used.
|
| statusCode | | int statusCode(Code) | | |
| url | | public String url(Code) | | The URL specified in the request, not including any "?" query
string.
|
| version | | public int version(Code) | | Derived from
Request.protocol , the version of the HTTP protocol
used for this request. Either 10 for "HTTP/1.0" or
11 for "HTTP/1.1".
|
| Request | | Request(Server server, Socket sock)(Code) | | Create a new http request. Requests are created by the server for
use by handlers.
Parameters:
server - The server that owns this request.
Parameters:
sock - The socket of the incoming HTTP request. |
| addHeader | | public void addHeader(String key, String value)(Code) | | 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 the responseHeaders 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.
Parameters:
value - The value for the request header.
See Also: Request.sendHeaders(int,String,int)
See Also: Request.responseHeaders |
| addHeader | | public void addHeader(String line)(Code) | | 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 the responseHeaders 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: Request.sendHeaders(int,String,int)
See Also: Request.responseHeaders |
| getQueryData | | public Hashtable getQueryData(Hashtable table)(Code) | | 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 asname/value pairs. May be null, in which casea new hashtable is allocated. |
| getQueryData | | public Hashtable getQueryData()(Code) | | 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.
|
| getRequest | | boolean getRequest(Properties defaults) throws IOException(Code) | | Reads an HTTP request from the socket.
Parameters:
props - The server props associated with this request true if the request was successfully read andparsed, false if the request was malformed.
throws:
IOException - if there was an IOException reading from the socket. Seethe socket documentation for a description of socketexceptions. |
| getRequestHeader | | public String getRequestHeader(String key)(Code) | | 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 the headers field.
Parameters:
key - The key to look for in the HTTP request headers. May notbe null. The value to which the given key is mapped, ornull if the key is not in the headers.
See Also: Request.headers |
| getReuseCount | | public int getReuseCount()(Code) | | Return uses of this socket
|
| getSocket | | public Socket getSocket()(Code) | | 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.
The client socket that issued this HTTP request. |
| getStatus | | public int getStatus()(Code) | | Return the status code.
|
| log | | public void log(int level, String message)(Code) | | Logs a message by calling Server.log. Typically a
message is generated on the console or in a log file, if the
level is less than the current server log setting.
Parameters:
level - The severity of the message.
Parameters:
message - The message that will be logged.
See Also: Server.log(intObjectString) |
| log | | public void log(int level, Object obj, String message)(Code) | | Logs a message by calling Server.log. Typically a
message is generated on the console or in a log file, if the
level is less than the current server log setting.
Parameters:
level - The severity of the message.
Parameters:
obj - The object that the message relates to.
Parameters:
message - The message that will be logged.
See Also: Server.log(intObjectString) |
| redirect | | public void redirect(String url, String body) throws IOException(Code) | | 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 befully-qualified (in the form "http://....") or host-relative(in the form "/...").
Parameters:
body - The body of the redirect response, or null tosend a hardcoded message. |
| sendError | | public void sendError(int code, String clientMessage)(Code) | | Sends a HTTP error response to the client.
Parameters:
code - The HTTP status code.
Parameters:
clientMessage - A short message to be included in the error responseand logged to the server. |
| sendError | | public void sendError(int code, String clientMessage, String logMessage)(Code) | | Sends a HTTP error response to the client.
Parameters:
code - The HTTP status code.
Parameters:
clientMessage - A short message to be included in the error response.
Parameters:
logMessage - A short message to be logged to the server. This message isnot sent to the client. |
| sendHeaders | | public void sendHeaders(int code, String type, int length) throws IOException(Code) | | Sends the HTTP status line and response headers to the client. This
method is automatically invoked by sendResponse, 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 the
responseHeaders 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 existingstatus code.
Parameters:
type - The MIME type of the response, such as "text/html". May benull to preserve the existing "Content-Type"response header (if any).
Parameters:
length - The length of the response body. May be < 0 if the lengthis 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 tothe client.
See Also: Request.setStatus(int)
See Also: Request.addHeader(String,String)
See Also: Request.sendResponse(String,String,int)
See Also: Request.connectionHeader |
| sendResponse | | public void sendResponse(byte[] body, String type) throws IOException(Code) | | 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.
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. Maynot be null.
Parameters:
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 tothe client.
See Also: Request.sendHeaders(int,String,int) |
| sendResponse | | public void sendResponse(String body, String type, int code) throws IOException(Code) | | 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.
Parameters:
body - The string to send as the HTTP response body. Maynot be null.
Parameters:
type - The MIME type of the response, such as "text/html". May benull to preserve the existing "Content-Type"response header (if any).
Parameters:
code - The HTTP status code for the response, such as200. May be < 0 to preserve the existingstatus code.
throws:
IOException - if there was an I/O error while sending the response tothe client.
See Also: Request.sendHeaders(int,String,int) |
| sendResponse | | public void sendResponse(String body) throws IOException(Code) | | 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.
See Also: Request.sendResponse(String,String,int) |
| sendResponse | | public void sendResponse(String body, String type) throws IOException(Code) | | 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.
Parameters:
type - The MIME type of the response.
See Also: Request.sendResponse(String,String,int) |
| sendResponse | | public void sendResponse(InputStream in, int length, String type, int code) throws IOException(Code) | | 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 of length
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 to false
before returning, if fewer than length bytes could be
read.
Parameters:
in - The input stream to read from.
Parameters:
length - The content length. The number of bytes to send to theclient. May be < 0, in which case this method will readuntil reaching the end of the input stream.
Parameters:
type - The MIME type of the response, such as "text/html". May benull to preserve the existing "Content-Type"response header (if any).
Parameters:
code - The HTTP status code for the response, such as200. May be < 0 to preserve the existingstatus code.
throws:
IOException - if there was an I/O error while sending the response tothe client. |
| serverUrl | | public String serverUrl()(Code) | | 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.
The string representation of the server's URL. |
| setStatus | | public void setStatus(int code)(Code) | | Sets the status code of the HTTP response. The default status
code for a response is 200 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 as 200 or404. If < 0, the HTTP status code willnot be changed.
See Also: Request.sendHeaders(int,String,int) |
| shouldKeepAlive | | boolean shouldKeepAlive()(Code) | | |
| toString | | public String toString()(Code) | | Returns a string representation of this Request.
The string representation is the first line (the method line) of the
HTTP request that this Request is handling. Useful for
debugging.
The string representation of this Request. |
|
|