org.simpleframework.http.ResponseHeader Maven / Gradle / Ivy
/*
* Response.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.util.List;
/**
* The ResponseHeader 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 StatusLine object, which exposes the
* protocol version and response status code.
*
* 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
*/
public List 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 getValue 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
*/
public void add(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 getInteger 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
*/
public void add(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
*/
public 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 getValue in combination with the get methods.
* This will perform a remove 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
*/
public void set(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 getValue in combination with the get methods.
* This will perform a remove 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
*/
public void set(String name, int 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 remove 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
*/
public void setDate(String name, long date);
/**
* This is used to remove the named header from the response. This
* removes all header values assigned to the specified name. If it
* does not exist then this will return without modifying the HTTP
* response. Headers names removed are case insensitive.
*
* @param name the HTTP message header to remove from the response
*/
public void remove(String name);
/**
* This is used to see if there is a HTTP message header with the
* given name in this container. If there is a HTTP message header
* with the specified name then this returns true otherwise false.
*
* @param name the HTTP message header to get the value from
*
* @return this returns true if the HTTP message header exists
*/
public boolean contains(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
*
* @return this returns the value that the HTTP message header
*/
public 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 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
*/
public 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
*/
public 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 substring and trim calls.
*
* 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.
*
* 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)
*/
public List getValues(String name);
/**
* The setCookie 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
*/
public Cookie setCookie(Cookie cookie);
/**
* The setCookie 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
*/
public Cookie setCookie(String name, String value);
/**
* This returns the Cookie object stored under the
* specified name. This is used to retrieve cookies that have been
* set with the setCookie 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 Cookie by the given name
*/
public Cookie getCookie(String name);
/**
* This returns all Cookie objects stored under the
* specified name. This is used to retrieve cookies that have been
* set with the setCookie methods. If there are no
* cookies then this will return an empty list.
*
* @return returns all the Cookie in the response
*/
public List 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 Content-Type 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
*/
public 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 Transfer-Encoding 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
*/
public 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 Content-Length 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
*/
public int getContentLength();
}