org.simpleframework.http.Request Maven / Gradle / Ivy
/*
* Request.java February 2001
*
* Copyright (C) 2001, Niall Gallagher
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
* License as published by the Free Software Foundation.
*
* This library is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General
* Public License along with this library; if not, write to the
* Free Software Foundation, Inc., 59 Temple Place, Suite 330,
* Boston, MA 02111-1307 USA
*/
package org.simpleframework.http;
import java.io.InputStream;
import java.net.InetSocketAddress;
import java.nio.channels.ReadableByteChannel;
import java.util.Map;
import org.simpleframework.http.session.Session;
/**
* 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
*/
public interface Request extends RequestHeader {
/**
* 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.
*
* @return true if the request is transferred securely
*/
public boolean isSecure();
/**
* 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.
*
* @return returns true if this has a keep-alive stream
*/
public boolean isKeepAlive();
/**
* 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.
*
* @return this returns the form containing the state
*
* @throws Exception thrown if it could not be acquired
*/
public Form getForm() throws Exception;
/**
* 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.
*
* @param name this is the name of the parameter value
*
* @exception Exception thrown if there is an I/O problem
*/
public String getParameter(String name) throws Exception;
/**
* 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.
*
* @param name this is the name of the part to acquire
*
* @return the named part or null if the part does not exist
*/
public Part getPart(String name) throws Exception;
/**
* 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.
*
* @return the attributes of this Response object
*/
public Map getAttributes();
/**
* 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.
*
* @param key this is the key of the attribute to acquire
*
* @return this returns the attribute for the specified name
*/
public Object getAttribute(Object key);
/**
* 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.
*
* @return this returns the client address for this request
*/
public InetSocketAddress getClientAddress();
/**
* 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.
*
* @return this returns the message bytes as an encoded string
*/
public String getContent() throws Exception;
/**
* 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.
*
* @return this returns an input stream containing the message body
*/
public InputStream getInputStream() throws Exception;
/**
* 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.
*
* @return this returns the byte channel used to read the content
*/
public ReadableByteChannel getByteChannel() throws Exception;
/**
* 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.
*
* @return returns an active Session object
*/
public Session getSession() throws Exception;
/**
* 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.
*
* @param create creates the session if it does not exist
*
* @return returns an active Session object
*/
public Session getSession(boolean create) throws Exception;
}