bayou.http

Class CookieJar

java.lang.Object

bayou.http.CookieJar

public class CookieJar
extends Object

For managing cookies in a request-response cycle.

A server application can read HttpRequest.cookies() and generate HttpResponse.cookies(). However, it might be inconvenient to manage cookies that way, particularly where request/response is not available to the code.

CookieJar models client cookies as a map-like structure that the application can read from and write to. For example

     CookieJar cookieJar = CookieJar.current();
     String foo = cookieJar.get("foo");
     if(foo==null)
         cookieJar.put("foo", foo="bar", Cookie.SESSION);

     String flashMsg = CookieJar.current().remove("flashMsg");
 

A CookieJar is a fiber-local concept, for a single request-response cycle.

A CookeJar is initialized with cookies from the fiber-local request; the cookies in the jar can be changed by put/remove/clear methods. At the end of the request-response cycle, HttpServer will collect all changes and generate proper response cookies.

{domain,path}

Each CookieJar is intended for a specific cookie {domain,path}; it manages cookies only of that {domain,path}. See Cookie.

Method CookieJar.current() uses default {domain=null, path="/"}. If the application uses cookies of different domain/path, call CookieJar.current(domain,path) instead.

Unfortunately, cookie domain/path are not available in request Cookie header, therefore a CookieJar cannot know which {domain,path} a request cookie belongs to. It is best if the application uses the same {domain,path} for all cookies. Otherwise, never use the same cookie name in different {domain,path}, or CookieJar may not function properly.

See Also:

Cookie

Method Summary

Instance Methods
Map<String,String>	toMap() Get all cookies in this jar as a Map.
String	get(String cookieName) Get the value of a cookie.
String	put(String cookieName, String cookieValue, Duration maxAge) Add a cookie to this jar.
String	put(Cookie cookie) Add a cookie to this jar.
String	remove(String cookieName) Remove a cookie from this jar.
void	clear() Remove all cookies from this jar.
Collection<Cookie>	getChanges() Get all changes to this jar.
Static Methods
CookieJar	current() Get the default fiber-local CookieJar.
CookieJar	current(String cookieDomain, String cookiePath) Get the fiber-local CookieJar for the cookie {domain,path}.
Collection<Cookie>	getAllChanges() Get all changes in all fiber-local CookieJars.
void	clearAll() Clear all fiber-local CookieJars.

Methods inherited from class java.lang.Object

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

Method Detail

current

public static CookieJar current()

Get the default fiber-local CookieJar.

This method is equivalent to current(null, "/"), i.e. the jar has {domain=null, path="/"}.

See Also:

current(domain,path)

current

public static CookieJar current(String cookieDomain,
                                String cookiePath)

Get the fiber-local CookieJar for the cookie {domain,path}.

The `cookiePath` must not be null; we strongly recommend to always use "/" for cookie path.

The jar for the current request-response cycle; it is initialized with cookies from the fiber-local request.

The jar is persistent in the fiber, until clearAll() is called.

getAllChanges

public static Collection<Cookie> getAllChanges()

Get all changes in all fiber-local CookieJars.

See Also:

getChanges() - get changes in a single jar

clearAll

public static void clearAll()

Clear all fiber-local CookieJars.

All the jars will be removed from the fiber. This is usually called by HttpServer at the end of a request-response cycle.

toMap

public Map<String,String> toMap()

Get all cookies in this jar as a Map.

The returned Map is a read-only snapshot.

get

public String get(String cookieName)

Get the value of a cookie.

put

public String put(String cookieName,
                  String cookieValue,
                  Duration maxAge)

Add a cookie to this jar.

The cookie will have the same {domain,path} as this jar's, and secure=httpOnly=false.

Returns:

the previous value of the cookie, or null if none.

See Also:

put(Cookie)

put

public String put(Cookie cookie)

Add a cookie to this jar.

The cookie must have the same {domain,path} as this jar's.

Returns:

the previous value of the cookie, or null if none.

remove

public String remove(String cookieName)

Remove a cookie from this jar.

Returns:

the previous value of the cookie, or null if none.

clear

public void clear()

Remove all cookies from this jar.

getChanges

public Collection<Cookie> getChanges()

Get all changes to this jar.

Return a list of response cookies that reflect changes done by previous put/remove/clear calls.