simple.http
Interface State


public interface State

The State is used by the Request to examine the cookies that have been issued with the HTTP request. The purpose of this interface is to provide implementations of the ProtocolHandler with a simple HTTP state control mechanism. This provides access to the cookies issued using the simple.http.net.Cookie object.

The HTTP State Management Mechanism, RFC 2109, specifies Cookie and Set-Cookie headers that can be used by HTTP servers to manage state across multiple requests. The State object abstracts this by setting up a context between the Request and Response. The various setCookie methods enable the State to be used to add Set-Cookie headers to the HTTP response header once it commits and cookie objects can be examined using the getCookie and getValue methods.

Author:
Niall Gallagher

Method Summary
 void clear()
          Removes all cookies from the state.
 boolean contains(java.lang.String name)
          Checks to see if the cookie of the specified name exists in the State.
 Cookie getCookie(java.lang.String name)
          This returns the Cookie object stored under the specified name.
 Cookie[] getCookies()
          The getCookies method returns all cookies that exist within the state.
 Cookie[] getSetCookies()
          The getSetCookies method is used to retrieve the cookies that have been added to the state.
 java.lang.String getValue(java.lang.String name)
          This is used to retreive the value of the Cookie stored under the specified name.
 boolean isEmpty()
          Checks to see if the State is empty.
 Cookie remove(java.lang.String name)
          This method removes and returns the removed cookie object from the State.
 void setCookie(Cookie cookie)
          The setCookie method is used to set a cookie value with the cookie name.
 void setCookie(java.lang.String name, java.lang.String value)
          The setCookie method is used to set a cookie value for a specified name.
 void setCookie(java.lang.String name, java.lang.String value, java.lang.String path)
          The setCookie method is used to set a cookie value for a specified name.
 int size()
          Returns the number of cookies that exist within the state.
 

Method Detail

setCookie

void setCookie(Cookie cookie)
The setCookie method is used to set a cookie value with the cookie name. This will add a cookie to the state stored under the Cookie.getName value. Once the Response object commits then the header will be given to the client with the Set-Cookie header.

Parameters:
cookie - this is the simple.util.net.Cookie that is to be used in a Set-Cookie response header

setCookie

void setCookie(java.lang.String name,
               java.lang.String value)
The setCookie method is used to set a cookie value for a specified name. This will add a cookie to the state stored under the specified name as a Cookie object. Once the Response object commits then the header will be given to the client with the Set-Cookie header. This is a convienience method that avoids having to create a cookie.

Parameters:
name - the name of the cookie to be given to the client
value - the value that the cookie is to be given

setCookie

void setCookie(java.lang.String name,
               java.lang.String value,
               java.lang.String path)
The setCookie method is used to set a cookie value for a specified name. This will add a cookie to the state stored under the specified name as a Cookie object. Once the Response object commits then the header will be given to the client with the Set-Cookie header. This is a convienience method that avoids having to create a cookie.

Parameters:
name - the name of the cookie to be given to the client
value - the value that the cookie is to be given
path - specifies the path the cookie object is to have

getCookie

Cookie getCookie(java.lang.String name)
This returns the Cookie object stored under the specified name. This is used to retieve cookies that have been issued with the HTTP request and set using the setCookie methods.

Parameters:
name - this is the name of the cookie to be retreived
Returns:
returns the Cookie by the given name

getSetCookies

Cookie[] getSetCookies()
The getSetCookies method is used to retrieve the cookies that have been added to the state. This is useful so that the ProtocolHandler can determine the cookies add using the setCookie methods. The cookies returned from this method are the only cookies sent to the HTTP client using the Set-Cookie header.

Returns:
this returns an array of Cookie with the cookies set with this instance

getCookies

Cookie[] getCookies()
The getCookies method returns all cookies that exist within the state. The cookies returned include all cookies retreived from the HTTP request header and all cookies set using the current State instance.

Returns:
this returns an array of Cookie of all cookies within the current state

getValue

java.lang.String getValue(java.lang.String name)
This is used to retreive the value of the Cookie stored under the specified name. This is a convienience method that avoids having to deal with the cookie object directly. If the cookis does not exist ths returns null.

Parameters:
name - this is the name of the cookie to be retreived
Returns:
the valie of the specified Cookie

remove

Cookie remove(java.lang.String name)
This method removes and returns the removed cookie object from the State. If the a Cookie by the specified name does not exist then null is returned.

Parameters:
name - this name of the cookie that is to be removed
Returns:
the Cookie instance removed from this state or null is it did not exist.

contains

boolean contains(java.lang.String name)
Checks to see if the cookie of the specified name exists in the State.

Parameters:
name - the name of the Cookie object
Returns:
this returns true of the specified cookie exists

isEmpty

boolean isEmpty()
Checks to see if the State is empty. If empty this represents a new client or a browser that does not accept Set-Cookie headers for privacy.

Returns:
this returns true if there are no cookies

size

int size()
Returns the number of cookies that exist within the state. If the size is zero this isEmpty.

Returns:
the number of cookies within the state

clear

void clear()
Removes all cookies from the state. This is useful if the HTTP response does not want to send any cookies.