diff options
Diffstat (limited to 'simple/simple-http/src/main/java/org/simpleframework/http/ResponseHeader.java')
| -rw-r--r-- | simple/simple-http/src/main/java/org/simpleframework/http/ResponseHeader.java | 304 |
1 files changed, 304 insertions, 0 deletions
diff --git a/simple/simple-http/src/main/java/org/simpleframework/http/ResponseHeader.java b/simple/simple-http/src/main/java/org/simpleframework/http/ResponseHeader.java new file mode 100644 index 0000000..5b36994 --- /dev/null +++ b/simple/simple-http/src/main/java/org/simpleframework/http/ResponseHeader.java @@ -0,0 +1,304 @@ +/* + * Response.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.util.List; + +/** + * The <code>ResponseHeader</code> object is used to manipulate the + * header information for a given response. Headers are stored and + * retrieved from this object in a case insensitive manner. This + * implements the <code>StatusLine</code> object, which exposes the + * protocol version and response status code. + * <p> + * All cookies set on the response header will be delivered as a + * Set-Cookie header in the response message. The Content-Length and + * Transfer-Encoding headers can be set to configure how the message + * body is delivered to the connected client. + * + * @author Niall Gallagher + */ +public interface ResponseHeader extends StatusLine { + + /** + * This is used to acquire the names of the of the headers that + * have been set in the response. This can be used to acquire all + * header values by name that have been set within the response. + * If no headers have been set this will return an empty list. + * + * @return a list of strings representing the set header names + */ + List<String> getNames(); + + /** + * This can be used to add a HTTP message header to this object. + * The name and value of the HTTP message header will be used to + * create a HTTP message header object which can be retrieved using + * the <code>getValue</code> in combination with the get methods. + * + * @param name the name of the HTTP message header to be added + * @param value the value the HTTP message header will have + */ + void addValue(String name, String value); + + /** + * This can be used to add a HTTP message header to this object. + * The name and value of the HTTP message header will be used to + * create a HTTP message header object which can be retrieved using + * the <code>getInteger</code> in combination with the get methods. + * + * @param name the name of the HTTP message header to be added + * @param value the value the HTTP message header will have + */ + void addInteger(String name, int value); + + /** + * This is used as a convenience method for adding a header that + * needs to be parsed into a HTTPdate string. This will convert + * the date given into a date string defined in RFC 2616 sec 3.3.1. + * + * @param name the name of the HTTP message header to be added + * @param date the value constructed as an RFC 1123 date string + */ + void addDate(String name, long date); + + /** + * This can be used to set a HTTP message header to this object. + * The name and value of the HTTP message header will be used to + * create a HTTP message header object which can be retrieved using + * the <code>getValue</code> in combination with the get methods. + * This will perform a <code>remove</code> using the issued header + * name before the header value is set. + * + * @param name the name of the HTTP message header to be added + * @param value the value the HTTP message header will have + */ + void setValue(String name, String value); + + /** + * This can be used to set a HTTP message header to this object. + * The name and value of the HTTP message header will be used to + * create a HTTP message header object which can be retrieved using + * the <code>getValue</code> in combination with the get methods. + * This will perform a <code>remove</code> using the issued header + * name before the header value is set. + * + * @param name the name of the HTTP message header to be added + * @param value the value the HTTP message header will have + */ + void setInteger(String name, int value); + + /** + * This can be used to set a HTTP message header to this object. + * The name and value of the HTTP message header will be used to + * create a HTTP message header object which can be retrieved using + * the <code>getValue</code> in combination with the get methods. + * This will perform a <code>remove</code> using the issued header + * name before the header value is set. + * + * @param name the name of the HTTP message header to be added + * @param value the value the HTTP message header will have + */ + void setLong(String name, long value); + + /** + * This is used as a convenience method for adding a header that + * needs to be parsed into a HTTP date string. This will convert + * the date given into a date string defined in RFC 2616 sec 3.3.1. + * This will perform a <code>remove</code> using the issued header + * name before the header value is set. + * + * @param name the name of the HTTP message header to be added + * @param date the value constructed as an RFC 1123 date string + */ + void setDate(String name, long date); + + /** + * This can be used to get the value of the first message header + * that has the specified name. This will return the full string + * representing the named header value. If the named header does + * not exist then this will return a null value. + * + * @param name the HTTP message header to get the value from + * + * @return this returns the value that the HTTP message header + */ + String getValue(String name); + + /** + * This can be used to get the value of the first message header + * that has the specified name. This will return the full string + * representing the named header value. If the named header does + * not exist then this will return a null value. + * + * @param name the HTTP message header to get the value from + * @param index used if there are multiple headers present + * + * @return this returns the value that the HTTP message header + */ + String getValue(String name, int index); + + /** + * This can be used to get the value of the first message header + * that has the specified name. This will return the integer + * representing the named header value. If the named header does + * not exist then this will return a value of minus one, -1. + * + * @param name the HTTP message header to get the value from + * + * @return this returns the value that the HTTP message header + */ + int getInteger(String name); + + /** + * This can be used to get the value of the first message header + * that has the specified name. This will return the long value + * representing the named header value. If the named header does + * not exist then this will return a value of minus one, -1. + * + * @param name the HTTP message header to get the value from + * + * @return this returns the value that the HTTP message header + */ + long getDate(String name); + + /** + * This can be used to get the values of HTTP message headers + * that have the specified name. This is a convenience method that + * will present that values as tokens extracted from the header. + * This has obvious performance benefits as it avoids having to + * deal with <code>substring</code> and <code>trim</code> calls. + * <p> + * The tokens returned by this method are ordered according to + * there HTTP quality values, or "q" values, see RFC 2616 section + * 3.9. This also strips out the quality parameter from tokens + * returned. So "image/html; q=0.9" results in "image/html". If + * there are no "q" values present then order is by appearance. + * <p> + * The result from this is either the trimmed header value, that + * is, the header value with no leading or trailing whitespace + * or an array of trimmed tokens ordered with the most preferred + * in the lower indexes, so index 0 is has highest preference. + * + * @param name the name of the headers that are to be retrieved + * + * @return ordered list of tokens extracted from the header(s) + */ + List<String> getValues(String name); + + /** + * The <code>setCookie</code> method is used to set a cookie value + * with the cookie name. This will add a cookie to the response + * stored under the name of the cookie, when this is committed it + * will be added as a Set-Cookie header to the resulting response. + * + * @param cookie this is the cookie to be added to the response + * + * @return returns the cookie that has been set in the response + */ + Cookie setCookie(Cookie cookie); + + /** + * The <code>setCookie</code> method is used to set a cookie value + * with the cookie name. This will add a cookie to the response + * stored under the name of the cookie, when this is committed it + * will be added as a Set-Cookie header to the resulting response. + * This is a convenience method that avoids cookie creation. + * + * @param name this is the cookie to be added to the response + * @param value this is the cookie value that is to be used + * + * @return returns the cookie that has been set in the response + */ + Cookie setCookie(String name, String value); + + /** + * This returns the <code>Cookie</code> object stored under the + * specified name. This is used to retrieve cookies that have been + * set with the <code>setCookie</code> methods. If the cookie does + * not exist under the specified name this will return null. + * + * @param name this is the name of the cookie to be retrieved + * + * @return returns the <code>Cookie</code> by the given name + */ + Cookie getCookie(String name); + + /** + * This returns all <code>Cookie</code> objects stored under the + * specified name. This is used to retrieve cookies that have been + * set with the <code>setCookie</code> methods. If there are no + * cookies then this will return an empty list. + * + * @return returns all the <code>Cookie</code> in the response + */ + List<Cookie> getCookies(); + + /** + * This is a convenience method that can be used to determine the + * content type of the message body. This will determine whether + * there is a <code>Content-Type</code> header, if there is then + * this will parse that header and represent it as a typed object + * which will expose the various parts of the HTTP header. + * + * @return this returns the content type value if it exists + */ + ContentType getContentType(); + + /** + * This is a convenience method that can be used to determine the + * content type of the message body. This will determine whether + * there is a <code>Transfer-Encoding</code> header, if there is + * then this will parse that header and return the first token in + * the comma separated list of values, which is the primary value. + * + * @return this returns the transfer encoding value if it exists + */ + String getTransferEncoding(); + + /** + * This is a convenience method that can be used to determine + * the length of the message body. This will determine if there + * is a <code>Content-Length</code> header, if it does then the + * length can be determined, if not then this returns -1. + * + * @return content length, or -1 if it cannot be determined + */ + long getContentLength(); + + /** + * This method returns a <code>CharSequence</code> holding the header + * created for the request. A character sequence is returned as it + * can provide a much more efficient means of representing the header + * data by just wrapping the the data generated. + * + * @return this returns the characters generated for the header + */ + CharSequence getHeader(); + + /** + * This method returns a string representing the header that was + * generated for this header. For performance reasons it is better + * to acquire the character sequence representing the header as it + * does not require the allocation on new memory. + * + * @return this returns a string representation of this response + */ + String toString(); +} |