com.webobjects.appserver
Class WOCookie

java.lang.Object
  |
  +--com.webobjects.appserver.WOCookie

All Implemented Interfaces:

NSKeyValueCoding, NSKeyValueCoding.ErrorHandling, NSKeyValueCodingAdditions

public class WOCookie

extends Object

implements NSKeyValueCoding, NSKeyValueCoding.ErrorHandling, NSKeyValueCodingAdditions

WOCookie is used for the creation and setting of cookies in response objects. A cookie allows for the persistent storage of client state. Instead of using a WOSession object (which can potentially have a shorter life span), a cookie allows server-side applications to store state in client browsers for a specific or indeterminate amount of time. An advantage to cookies is that the data will be stored on the client and not on the server, allowing the server to maintain less state information. A specific advantage in WebObjects applications is that cookies allow the server to put state into the browser that is not bound to a session. Hence, the client can "leave" your application and return with its cookie's state intact.

A WOCookie object defines a cookie that can be added to the HTTP header for the response. A cookie is created using the static method cookieWithName.

To add or remove cookies from the response, the WOMessage methods addCookie and removeCookie are used. To retrieve cookie data, WORequest methods cookieValues, cookieValueForKey, and cookieValuesForKey are used. WORequest returns the data as name/value pairs and not as WOCookie objects, since browsers don't return the additional data WOCookies provide, such as path name and expiration date.

To create a cookie that expires when the browser window is closed, the cookie must be created with neither a "max-age" nor an "expires" attribute. WOCookie supports this behavior with the 2 argument constructor WOCookie(aName, aValue) and with the 6 argument constructor WOCookie(aName, aValue, aPath, aDomain, timeout, isSecure). If using the 6 argument constructor, you must pass a timeout value of -1. In either case, ensure that you avoid calling setExpires on the WOCookie object you get back from the constructor, or make sure that you call "setExpires(null)" on the WOCookie object before using it. This will prevent the WOCookie object from generating either a "max-age" or an "expires" header, which will indicate the desired expiration behavior. For example:

WOCookie cookie = new WOCookie("cookieName", "cookieValue", "/", null, -1, false);
cookie.setExpires(null);


For more information about cookies and their implementation details, see Netscape's preliminary specification and RFC 2109 - HTTP State Management Mechanism.

If and when new details evolve in the implementation of cookies, you can subclass WOCookie and implement new behaviors. Pay particular attention to how you override headerString, which WOResponse uses to generate headers in the HTTP response.

See Also:

headerString(), WOCookie(String aName, String aValue, String aPath, String aDomain, int timeout, boolean isSecure), WORequest.cookieValues(), WOMessage, WOMessage.addCookie(WOCookie aCookie), WOMessage.removeCookie(WOCookie aCookie), WORequest.cookieValuesForKey(String aKey), WORequest.cookieValuesForKey(String aKey)

Inner classes inherited from class com.webobjects.foundation.NSKeyValueCoding

NSKeyValueCoding.DefaultImplementation, NSKeyValueCoding.ErrorHandling, NSKeyValueCoding.Null, NSKeyValueCoding.UnknownKeyException, NSKeyValueCoding.Utility, NSKeyValueCoding.ValueAccessor

Inner classes inherited from class com.webobjects.foundation.NSKeyValueCodingAdditions

NSKeyValueCodingAdditions.DefaultImplementation, NSKeyValueCodingAdditions.Utility

Fields inherited from interface com.webobjects.foundation.NSKeyValueCoding

NullValue

Fields inherited from interface com.webobjects.foundation.NSKeyValueCodingAdditions

KeyPathSeparator

Constructor Summary

WOCookie(String aName, String aValue)
Constructor for a WOCookie with the specified name and value.

WOCookie(String aName, String aValue, String aPath, String aDomain, int timeout, boolean isSecure)
Constructor for a WOCookie with the specified attributes.

WOCookie(String aName, String aValue, String aPath, String aDomain, NSTimestamp aDate, boolean isSecure)
Constructor for a WOCookie with the specified attributes.

Method Summary

static boolean	canAccessFieldsDirectly() WOCokie's implementation of this static method returns true, indicating that key/value coding is allowed to access fields in this object if an appropriate method isn't present.
static WOCookie	cookieWithName(String aName, String aValue) Deprecated. Use WOCookie(String aName, String aValue) instead
static WOCookie	cookieWithName(String aName, String aValue, String aPath, String aDomain, int timeout, boolean isSecure) Deprecated. Use WOCookie(String aName, String aValue, String aPath, String aDomain, int timeout, boolean isSecure) instead
static WOCookie	cookieWithName(String aName, String aValue, String aPath, String aDomain, NSTimestamp aDate, boolean isSecure) Deprecated. Use WOCookie(String aName, String aValue, String aPath, String aDomain, NSTimestamp aDate, boolean isSecure) instead
String	domain() Cookies for a specific domain (such as apple.com) are sent only when accessing URLs in that domain.
NSTimestamp	expires() Returns the value of the cookie's "expires" attribute as an NSTimestamp.
Object	handleQueryWithUnboundKey(String key) Conformance to NSKeyValueCoding.ErrorHandling.
void	handleTakeValueForUnboundKey(Object value, String key) Conformance to NSKeyValueCoding.ErrorHandling.
String	headerString() Create and return a string which can be used in a Set-Cookie header.
boolean	isSecure() Return whether or not the cookie is secure.
String	name() The name is similar to the key of a dictionary or hash table.
String	path() Cookies for a specific path are sent only when accessing URLs within that path.
void	setDomain(String aDomain) Sets the cookie's "domain" attribute to aDomain.
void	setExpires(NSTimestamp aDate) Sets the cookie's "expires" attribute to expirationDate.
void	setIsSecure(boolean aBoolean) Sets the cookie's "secure" attribute to aBoolean.
void	setName(String aName) Sets the cookie's "name" attribute to aName.
void	setPath(String aPath) Sets the cookie's "path" attribute to aPath.
void	setTimeOut(int timeout) A negative value is used to indicate that there is no timeout, analogous to a NSTimestamp of null.
void	setValue(String aValue) Sets the cookie's "value" attribute to aValue.
void	takeValueForKey(Object value, String key) Conformance to NSKeyValueCoding.
void	takeValueForKeyPath(Object value, String keyPath) Conformance to NSKeyValueCodingAdditions.
int	timeOut() Returns the cookies timeout value in seconds.
String	toString() Returns a string representation of the receiver.
void	unableToSetNullForKey(String key) Conformance to NSKeyValueCoding.ErrorHandling.
String	value() This value attribute is similar to the value of a dictionary or hash table.
Object	valueForKey(String key) Conformance to NSKeyValueCoding.
Object	valueForKeyPath(String keyPath) Conformance to NSKeyValueCodingAdditions.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

WOCookie

public WOCookie(String aName,
                String aValue,
                String aPath,
                String aDomain,
                NSTimestamp aDate,
                boolean isSecure)

Constructor for a WOCookie with the specified attributes. An exception will be thrown if aName is null.

Parameters:

aName - the cookie's "name" attribute

aValue - the cookie's "value" attribute

aPath - the cookie's "path" attribute

aDomain - the cookie's "domain" attribute

aDate - the time at which the cookie will expire

isSecure - the cookie's "secure" attribute

See Also:

name(), value(), path(), domain(), expires(), isSecure()

WOCookie

public WOCookie(String aName,
                String aValue,
                String aPath,
                String aDomain,
                int timeout,
                boolean isSecure)

Constructor for a WOCookie with the specified attributes. An exception will be thrown if aName is null. A note on time out periods: time out periods are in seconds; a negative time out period indicates no time out; a time out of zero indicates expiration of all cookies with the given name.

Parameters:

aName - the cookie's "name" attribute

aValue - the cookie's "value" attribute

aPath - the cookie's "path" attribute

aDomain - the cookie's "domain" attribute

timeout - the cookie's timeout period in seconds

isSecure - the cookie's "secure" attribute

See Also:

name(), value(), path(), domain(), timeOut(), isSecure()

WOCookie

public WOCookie(String aName,
                String aValue)

Constructor for a WOCookie with the specified name and value. This method sets the path attribute to the application's path, with no timeout and no security. An exception will be thrown if aName is null.

Parameters:

aName - the cookie's "name" attribute

aValue - the cookie's "value" attribute

See Also:

name(), value()

Method Detail

canAccessFieldsDirectly

public static boolean canAccessFieldsDirectly()

WOCokie's implementation of this static method returns true, indicating that key/value coding is allowed to access fields in this object if an appropriate method isn't present.

Returns:

true

cookieWithName

public static WOCookie cookieWithName(String aName,
                                      String aValue,
                                      String aPath,
                                      String aDomain,
                                      NSTimestamp aDate,
                                      boolean isSecure)

Deprecated. Use WOCookie(String aName, String aValue, String aPath, String aDomain, NSTimestamp aDate, boolean isSecure) instead

Creates and returns a WOCookie with the specified attributes. Simply invokes WOCookie(aName, aValue, aPath, aDomain, aDate, isSecure).

See Also:

WOCookie(String aName, String aValue, String aPath, String aDomain, NSTimestamp aDate, boolean isSecure)

cookieWithName

public static WOCookie cookieWithName(String aName,
                                      String aValue,
                                      String aPath,
                                      String aDomain,
                                      int timeout,
                                      boolean isSecure)

Deprecated. Use WOCookie(String aName, String aValue, String aPath, String aDomain, int timeout, boolean isSecure) instead

Creates and returns a WOCookie with the specified attributes. Simply invokes WOCookie(aName, aValue, aPath, aDomain, timeout, isSecure).

See Also:

WOCookie(String aName, String aValue, String aPath, String aDomain, int timeout, boolean isSecure)

cookieWithName

public static WOCookie cookieWithName(String aName,
                                      String aValue)

Deprecated. Use WOCookie(String aName, String aValue) instead

Creates and returns a WOCookie with the specified name and value. Simply invokes WOCookie(aName, aValue).

See Also:

WOCookie(String aName, String aValue)

domain

public String domain()

Cookies for a specific domain (such as apple.com) are sent only when accessing URLs in that domain.

Returns:

the value of the cookie's domain attribute in the form companyname.com

See Also:

setDomain(java.lang.String)

expires

public NSTimestamp expires()

Returns the value of the cookie's "expires" attribute as an NSTimestamp. The expiration date tells the browser how long to keep the cookie in its cache. To have the browser remove the cookie from its cache, set the expiration date to a recent date in the past.

Returns:

an NSTimestamp indicating when the cookie will expire

See Also:

setExpires(NSTimestamp aDate)

handleQueryWithUnboundKey

public Object handleQueryWithUnboundKey(String key)

Conformance to NSKeyValueCoding.ErrorHandling. This will throw an NSKeyValueCoding.UnknownKeyException

Specified by:

handleQueryWithUnboundKey in interface NSKeyValueCoding.ErrorHandling

Parameters:

key - identifies the property of an object

Returns:

the receiver's value for the property identified by key

handleTakeValueForUnboundKey

public void handleTakeValueForUnboundKey(Object value,
                                         String key)

Conformance to NSKeyValueCoding.ErrorHandling. This will throw an NSKeyValueCoding.UnknownKeyException

Specified by:

handleTakeValueForUnboundKey in interface NSKeyValueCoding.ErrorHandling

Parameters:

key - identifies the property to be set

value - the value to which the property specified by key should be set

headerString

public String headerString()

Create and return a string which can be used in a Set-Cookie header. The string will have the pattern:

name=value; version="1"; max-age=timeout; expires=date; path=path; domain=domain; secure;

The calendar format for the expiration date is:

 "%A,%d-%b-%Y %H:%M:%S GMT"
 

where all times are converted relative to Greenwich Mean Time. The max-age attribute is not added if the timeout is "-1". Values are quoted if they have spaces and are not already quoted.

Returns:

the string that will be used in the HTTP header

isSecure

public boolean isSecure()

Return whether or not the cookie is secure. The default value is false.

Returns:

true if the cookie should be transmitted only with secure HTTP, false otherwise

See Also:

setIsSecure(boolean aBoolean)

name

public String name()

The name is similar to the key of a dictionary or hash table. Together, the name and value form the cookie's data.

Returns:

the cookie's name attribute

See Also:

setName(java.lang.String)

path

public String path()

Cookies for a specific path are sent only when accessing URLs within that path.

Returns:

the value of the cookie's path attribute

See Also:

setPath(String aPath)

setDomain

public void setDomain(String aDomain)

Sets the cookie's "domain" attribute to aDomain.

Parameters:

aDomain - the cookie's "domain" attribute

See Also:

domain()

setExpires

public void setExpires(NSTimestamp aDate)

Sets the cookie's "expires" attribute to expirationDate.
If you want to set the cookie's expiration date to some date in the distant past (for instance, in order to erase the cookie) don't use NSTimestamp.distantPast(). distantPast returns a date from the year 1 AD, and some browsers incorrectly interpret this as the year 2001. Instead, set the cookie's expiration date to an actual date in the recent past.
This method should be used to ensure the best interoperability with current HTTP clients. Currently, timeout and expires are orthogonal. Setting timeout will not set an expires date "timeout" seconds in the future.

Parameters:

aDate - an NSTimestamp indicating when the cookie should expire

See Also:

setExpires(NSTimestamp aDate)

setIsSecure

public void setIsSecure(boolean aBoolean)

Sets the cookie's "secure" attribute to aBoolean.

Parameters:

aBoolean - true if the cookie should only be transmitted over HTTPS, false otherwise

See Also:

isSecure()

setName

public void setName(String aName)

Sets the cookie's "name" attribute to aName.

Parameters:

aName - the cookie's name attribute

See Also:

name()

setPath

public void setPath(String aPath)

Sets the cookie's "path" attribute to aPath.

Parameters:

aPath - the cookie's path attribute

See Also:

path()

setTimeOut

public void setTimeOut(int timeout)

A negative value is used to indicate that there is no timeout, analogous to a NSTimestamp of null. A value of zero means the user agent shall discard all cookies of this name. Currently, timeout and expires are orthogonal. Setting timeout will not set an expires date "timeout" seconds in the future.

Parameters:

timeout - time after which the cookie expires

See Also:

timeOut()

setValue

public void setValue(String aValue)

Sets the cookie's "value" attribute to aValue.

Parameters:

aValue - the cookie's value attribute

See Also:

value()

takeValueForKey

public void takeValueForKey(Object value,
                            String key)

Conformance to NSKeyValueCoding.

Specified by:

takeValueForKey in interface NSKeyValueCoding

Parameters:

key - identifies the property to be set

value - the value to which the property specified by key should be set

takeValueForKeyPath

public void takeValueForKeyPath(Object value,
                                String keyPath)

Conformance to NSKeyValueCodingAdditions.

Specified by:

takeValueForKeyPath in interface NSKeyValueCodingAdditions

Parameters:

keyPath - identifies a derived property of the receiver

value - value to which the derived property identified by keyPath will be set

timeOut

public int timeOut()

Returns the cookies timeout value in seconds.

Returns:

the cookies timeout in seconds

See Also:

setTimeOut(int timeout)

toString

public String toString()

Returns a string representation of the receiver.

Overrides:

toString in class Object

Returns:

a string representation of the receiver.

unableToSetNullForKey

public void unableToSetNullForKey(String key)

Conformance to NSKeyValueCoding.ErrorHandling. This will throw an IllegalArgumentException.

Specified by:

unableToSetNullForKey in interface NSKeyValueCoding.ErrorHandling

Parameters:

key - identifies the property to be set

value

public String value()

This value attribute is similar to the value of a dictionary or hash table. Together, the name and value form the cookie's data.

Returns:

the value of the cookie's value attribute

See Also:

setValue(String aValue)

valueForKey

public Object valueForKey(String key)

Conformance to NSKeyValueCoding.

Specified by:

valueForKey in interface NSKeyValueCoding

Parameters:

key - identifies the property of an object

Returns:

the receiver's value for the property identified by key

valueForKeyPath

public Object valueForKeyPath(String keyPath)

Conformance to NSKeyValueCodingAdditions.

Specified by:

valueForKeyPath in interface NSKeyValueCodingAdditions

Parameters:

keyPath - identifies the derived property of an object

Returns:

receiver's value for the derived property identified by keyPath