org.simpleframework.http
Interface Request

All Superinterfaces:
RequestHeader, RequestLine
All Known Implementing Classes:
RequestWrapper

public interface Request
extends RequestHeader

The Request is used to provide an interface to the HTTP entity body and message header. This provides methods that allow the entity body to be acquired as a stream, string, or if the message is a multipart encoded body, then the individual parts of the request body can be acquired.

This can also maintain data during the request lifecycle as well as the session lifecycle. A Session is made available for convenience. It provides a means for the services to associate data with a given client session, which can be retrieved when there are subsequent requests sent to the server.

It is important to note that the entity body can be read multiple times from the request. Calling getInputStream will start reading from the first byte in the body regardless of the number of times it is called. This allows POST parameters as well as multipart bodies to be read from the stream if desired.

Author:
Niall Gallagher

Method Summary
 java.lang.Object getAttribute(java.lang.Object key)
          This is used as a shortcut for acquiring attributes for the response.
 java.util.Map getAttributes()
          This can be used to retrieve the response attributes.
 java.nio.channels.ReadableByteChannel getByteChannel()
          This is used to read the content body.
 java.net.InetSocketAddress getClientAddress()
          This is used to acquire the remote client address.
 java.lang.String getContent()
          This is used to get the content body.
 Form getForm()
          This is used to acquire all the form parameters from the HTTP request.
 java.io.InputStream getInputStream()
          This is used to read the content body.
 java.lang.String getParameter(java.lang.String name)
          This is used to provide quick access to the parameters.
 Part getPart(java.lang.String name)
          This method is used to acquire a Part from the form using a known name for the part.
 Session getSession()
          This method is used to acquire a Session for the request.
 Session getSession(boolean create)
          This method is used to acquire a Session for the request.
 boolean isKeepAlive()
          This is a convenience method that is used to determine whether or not this message has the Connection: close header.
 boolean isSecure()
          This is used to determine if the request has been transferred over a secure connection.
 
Methods inherited from interface org.simpleframework.http.RequestHeader
contains, getContentLength, getContentType, getCookie, getCookies, getDate, getInteger, getLocales, getNames, getValue, getValues
 
Methods inherited from interface org.simpleframework.http.RequestLine
getAddress, getMajor, getMethod, getMinor, getPath, getQuery, getTarget
 

Method Detail

isSecure

boolean isSecure()
This is used to determine if the request has been transferred over a secure connection. If the protocol is HTTPS and the content is delivered over SSL then the request is considered to be secure. Also the associated response will be secure.

Returns:
true if the request is transferred securely

isKeepAlive

boolean isKeepAlive()
This is a convenience method that is used to determine whether or not this message has the Connection: close header. If the close token is present then this stream is not a keep-alive connection. If this has no Connection header then the keep-alive status is determined by the HTTP version, that is, HTTP/1.1 is keep-alive by default, HTTP/1.0 is not keep-alive by default.

Returns:
returns true if this has a keep-alive stream

getForm

Form getForm()
             throws java.io.IOException
This is used to acquire all the form parameters from the HTTP request. This includes the query and POST data values as well as the parts of a multipart request. The form is a convenience object enabling easy access to state.

Returns:
this returns the form containing the state
Throws:
java.io.IOException

getParameter

java.lang.String getParameter(java.lang.String name)
                              throws java.io.IOException
This is used to provide quick access to the parameters. This avoids having to acquire the request Form object. This basically acquires the parameters object and invokes the getParameters method with the given name.

Parameters:
name - this is the name of the parameter value
Throws:
java.io.IOException

getPart

Part getPart(java.lang.String name)
             throws java.io.IOException
This method is used to acquire a Part from the form using a known name for the part. This is typically used when there is a file upload with a multipart POST request. All parts that are not files are added to the query values as strings so that they can be used in a convenient way.

Parameters:
name - this is the name of the part to acquire
Returns:
the named part or null if the part does not exist
Throws:
java.io.IOException

getAttributes

java.util.Map getAttributes()
This can be used to retrieve the response attributes. These can be used to keep state with the response when it is passed to other systems for processing. Attributes act as a convenient model for storing objects associated with the response. This also inherits attributes associated with the client connection.

Returns:
the attributes of that have been set on the request

getAttribute

java.lang.Object getAttribute(java.lang.Object key)
This is used as a shortcut for acquiring attributes for the response. This avoids acquiring the attribute Map in order to retrieve the attribute directly from that object. The attributes contain data specific to the response.

Parameters:
key - this is the key of the attribute to acquire
Returns:
this returns the attribute for the specified name

getClientAddress

java.net.InetSocketAddress getClientAddress()
This is used to acquire the remote client address. This can be used to acquire both the port and the I.P address for the client. It allows the connected clients to be logged and if require it can be used to perform course grained security.

Returns:
this returns the client address for this request

getContent

java.lang.String getContent()
                            throws java.io.IOException
This is used to get the content body. This will essentially get the content from the body and present it as a single string. The encoding of the string is determined from the content type charset value. If the charset is not supported this will throw an exception. Typically only text values should be extracted using this method if there is a need to parse that content.

Returns:
this returns the message bytes as an encoded string
Throws:
java.io.IOException

getInputStream

java.io.InputStream getInputStream()
                                   throws java.io.IOException
This is used to read the content body. The specifics of the data that is read from this InputStream can be determined by the getContentLength method. If the data sent by the client is chunked then it is decoded, see RFC 2616 section 3.6. Also multipart data is available as Part objects however the raw content of the multipart body is still available.

Returns:
this returns an input stream containing the message body
Throws:
java.io.IOException

getByteChannel

java.nio.channels.ReadableByteChannel getByteChannel()
                                                     throws java.io.IOException
This is used to read the content body. The specifics of the data that is read from this ReadableByteChannel can be determined by the getContentLength method. If the data sent by the client is chunked then it is decoded, see RFC 2616 section 3.6. This stream will never provide empty reads as the content is internally buffered, so this can do a full read.

Returns:
this returns the byte channel used to read the content
Throws:
java.io.IOException

getSession

Session getSession()
                   throws LeaseException
This method is used to acquire a Session for the request. The object retrieved provides a container for data associated to the connected client. This allows the request to perform more complex operations based on knowledge that is built up through a series of requests. The session is known to the system using a Cookie, which contains the session reference. This cookie value should not be modified as it used to reference the active session object.

Returns:
returns an active session for the associated client
Throws:
LeaseException

getSession

Session getSession(boolean create)
                   throws LeaseException
This method is used to acquire a Session for the request. The object retrieved provides a container for data associated to the connected client. This allows the request to perform more complex operations based on knowledge that is built up through a series of requests. The session is known to the system using a Cookie, which contains the session reference. This cookie value should not be modified as it used to reference the active session object.

Parameters:
create - creates the session if it does not exist
Returns:
returns an active session for the associated client
Throws:
LeaseException