diff options
Diffstat (limited to 'simple/simple-http/src/main/java/org/simpleframework/http/Request.java')
| -rw-r--r-- | simple/simple-http/src/main/java/org/simpleframework/http/Request.java | 210 |
1 files changed, 210 insertions, 0 deletions
diff --git a/simple/simple-http/src/main/java/org/simpleframework/http/Request.java b/simple/simple-http/src/main/java/org/simpleframework/http/Request.java new file mode 100644 index 0000000..2c83c28 --- /dev/null +++ b/simple/simple-http/src/main/java/org/simpleframework/http/Request.java @@ -0,0 +1,210 @@ +/* + * Request.java February 2001 + * + * Copyright (C) 2001, Niall Gallagher <niallg@users.sf.net> + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + * implied. See the License for the specific language governing + * permissions and limitations under the License. + */ + +package org.simpleframework.http; + +import java.io.IOException; +import java.io.InputStream; +import java.net.InetSocketAddress; +import java.nio.channels.ReadableByteChannel; +import java.util.List; +import java.util.Map; + +import org.simpleframework.transport.Certificate; +import org.simpleframework.transport.Channel; + +/** + * The <code>Request</code> 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. + * <p> + * This can also maintain data during the request lifecycle as well + * as the session lifecycle. A <code>Session</code> 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. + * <p> + * It is important to note that the entity body can be read multiple + * times from the request. Calling <code>getInputStream</code> 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 + */ + boolean isSecure(); + + /** + * This is a convenience method that is used to determine whether + * or not this message has the <code>Connection: close</code> + * header. If the close token is present then this stream is not + * a keep-alive connection. If this has no <code>Connection</code> + * 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 + */ + boolean isKeepAlive(); + + /** + * This is the time in milliseconds when the request was first + * read from the underlying socket. The time represented here + * represents the time collection of this request began. This + * does not necessarily represent the time the bytes arrived as + * as some data may have been buffered before it was parsed. + * + * @return this represents the time the request arrived at + */ + long getRequestTime(); + + /** + * This provides the underlying channel for the request. It + * contains the TCP socket channel and various other low level + * components. Typically this will only ever be needed when + * there is a need to switch protocols. + * + * @return the underlying channel for this request + */ + Channel getChannel(); + + /** + * This is used to acquire the SSL certificate used when the + * server is using a HTTPS connection. For plain text connections + * or connections that use a security mechanism other than SSL + * this will be null. This is only available when the connection + * makes specific use of an SSL engine to secure the connection. + * + * @return this returns the associated SSL certificate if any + */ + Certificate getClientCertificate(); + + /** + * 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 + */ + InetSocketAddress getClientAddress(); + + /** + * 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 that have been set on the request + */ + Map getAttributes(); + + /** + * This is used as a shortcut for acquiring attributes for the + * response. This avoids acquiring the attribute <code>Map</code> + * 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 + */ + Object getAttribute(Object key); + + /** + * This is used to provide quick access to the parameters. This + * avoids having to acquire the request <code>Form</code> object. + * This basically acquires the parameters object and invokes + * the <code>getParameters</code> method with the given name. + * + * @param name this is the name of the parameter value + */ + String getParameter(String name); + + /** + * This method is used to acquire a <code>Part</code> from the + * HTTP request 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 can be acquired as string values + * from the attachment object. + * + * @param name this is the name of the part object to acquire + * + * @return the named part or null if the part does not exist + */ + Part getPart(String name); + + /** + * This method is used to get all <code>Part</code> objects that + * are associated with the request. Each attachment contains the + * body and headers associated with it. If the request is not a + * multipart POST request then this will return an empty list. + * + * @return the list of parts associated with this request + */ + List<Part> getParts(); + + /** + * 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 + */ + String getContent() throws IOException; + + /** + * This is used to read the content body. The specifics of the data + * that is read from this <code>InputStream</code> can be determined + * by the <code>getContentLength</code> 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 <code>Part</code> objects + * however the raw content of the multipart body is still available. + * + * @return this returns an input stream containing the message body + */ + InputStream getInputStream() throws IOException; + + /** + * This is used to read the content body. The specifics of the data + * that is read from this <code>ReadableByteChannel</code> can be + * determined by the <code>getContentLength</code> 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 + */ + ReadableByteChannel getByteChannel() throws IOException; +} |