WebObjects 5.2

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

Last updated Fri Feb 21 13:15:00 PST 2003.

Copyright © 2003 Apple Computer, Inc.