org.mule.transport.http
Class CookieHelper

java.lang.Object
  org.mule.transport.http.CookieHelper

public class CookieHelper
extends Object

Helper functions for parsing, formatting, storing and retrieving cookie headers.

It is important that all access to Cookie data is done using this class. This will help to prevent ClassCastExceptions and data corruption.

The reasons for such a very complex CookieHelper class are historical and are related to the fact that cookies are a multivalued property and we store them as a single message property under the name "cookies".

In an HTTP message going from client to server the cookies come on their own "Cookie" header. The HTTP message can have several of these Cookie headers and each of them can store 1 or more cookies. One problem with this is that in Mule we use Map instances to store the HTTP headers and this means that we can only have one object with the key "cookies" (yes, we use that constant instead of "Cookie" when we store the cookies inside a MuleMessage).

In an HTTP message going from server to client the Cookies go in their own "Set-Cookie" header. But, again, internally we store all the HTTP headers inside a Map that maps each HTTP header with a single value. For Cookies it is a special case so have to be able to store many cookies in the value from that map.

With all these layed out one could say that we could just have a Collection of Cookie instances. But this is not that simple. In some parts of the code the cookies are stored as an array of Cookies and in some others it is stored as a Map where each entry corresponds to a cookie's name/value pair (which is not strictly a cookie). Specifically, when parsing cookies from the client (ie, acting as a server), the code stores it as an array of cookies. When the cookies are specified as a property in the endpoint (like explained in the docs), they are stored as a Map.

This class has helper methods that helps making code that is independent of the way the cookies are stored and still keep backward compatibility. It is very hacky, but I think it is better than what we had before.

Know Limitation: because of how cookies are handled in Mule, we don't handle well the host, port and path of a Cookie. We just handle Cookies as if they were only name/value pairs. This means that, for example, if a message with cookies is received on an endpoint called http://localhost:4020/hello (1) and that message goes to http://www.mulesoft.org/jira/ (2), then service (2) will receive all the cookies that were sent to service (1) as if they were their own. Furthermore, the same thing will happend on the response: all the returned cookies from service (2) will reach service (1) and then the client will receive them as if they were from service (1).

Field Summary

static String	EXPIRE_PATTERN
protected static Log	logger logger used by this class

Method Summary

static void	addCookiesToClient(HttpClient client, Object cookiesObject, String policy, MuleEvent event, URI destinationUri) Adds to the client all the cookies present in the cookiesObject.
static Cookie[]	asArrayOfCookies(Object cookiesObject) Returns an array view of the cookiesObject.
static String	formatCookieForASetCookieHeader(Cookie cookie) This method formats the cookie so it can be send from server to client in a "Set-Cookie" header.
static String	getCookiePolicy(String spec)
static CookieSpec	getCookieSpec(String spec)
static String	getCookieValueFromCookies(Object cookiesObject, String cookieName) Searches and return the cookie with the cookieName in the cookiesObject.
static Cookie[]	parseCookiesAsAClient(Header cookieHeader, String spec)
static Cookie[]	parseCookiesAsAClient(Header cookieHeader, String spec, URI uri)
static Cookie[]	parseCookiesAsAClient(String cookieHeaderValue, String spec)
static Cookie[]	parseCookiesAsAClient(String cookieHeaderValue, String spec, URI uri) This method parses the value of "Set-Cookie" HTTP header, returning an array with all the Cookies found.
static Cookie[]	parseCookiesAsAServer(Header header, URI uri) This method parses the value of an HTTP "Cookie" header that comes from a client to a server.
static Cookie[]	parseCookiesAsAServer(String headerValue, URI uri) This method parses the value of an HTTP "Cookie" header that comes from a client to a server.
static Object	putAndMergeCookie(Object preExistentCookies, Cookie[] newCookiesArray) Merges all the Cookies in newCookiesArray with the preExistentCookies, adding the new ones and overwriting the existing ones (existing means same cookie name).
static Object	putAndMergeCookie(Object preExistentCookies, Map<String,String> newCookiesMap) Merges all the Cookies in newCookiesMap with the preExistentCookies, adding the new ones and overwriting the existing ones (existing means same cookie name).
static Object	putAndMergeCookie(Object preExistentCookies, String cookieName, String cookieValue) This method merges a new Cookie (or override the previous one if it exists) to the preExistentCookies.
protected static Cookie	transformServerCookieToClientCookie(org.apache.tomcat.util.http.ServerCookie serverCookie) Transforms a ServerCookie (from Apache Tomcat) into a Cookie (from commons httpclient).

Methods inherited from class java.lang.Object

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

Field Detail

logger

protected static final Log logger

logger used by this class

EXPIRE_PATTERN

public static final String EXPIRE_PATTERN

See Also:

Constant Field Values

Method Detail

getCookieSpec

public static CookieSpec getCookieSpec(String spec)

Returns:

the CookieSpec (defaults to RFC2109Spec when spec is null)

getCookiePolicy

public static String getCookiePolicy(String spec)

Returns:

the cookie policy (defaults to CookiePolicy.RFC_2109 when spec is null).

parseCookiesAsAClient

public static Cookie[] parseCookiesAsAClient(Header cookieHeader,
                                             String spec)
                                      throws MalformedCookieException

Throws:

MalformedCookieException

See Also:

parseCookiesAsAClient(String, String, URI)

parseCookiesAsAClient

public static Cookie[] parseCookiesAsAClient(String cookieHeaderValue,
                                             String spec)
                                      throws MalformedCookieException

Throws:

MalformedCookieException

See Also:

parseCookiesAsAClient(String, String, URI)

parseCookiesAsAClient

public static Cookie[] parseCookiesAsAClient(Header cookieHeader,
                                             String spec,
                                             URI uri)
                                      throws MalformedCookieException

Throws:

MalformedCookieException

See Also:

parseCookiesAsAClient(String, String, URI)

parseCookiesAsAClient

public static Cookie[] parseCookiesAsAClient(String cookieHeaderValue,
                                             String spec,
                                             URI uri)
                                      throws MalformedCookieException

This method parses the value of "Set-Cookie" HTTP header, returning an array with all the Cookies found. This method is intended to be used from the client side of the HTTP connection.

Parameters:

cookieHeaderValue - the value with the cookie/s to parse.

spec - the spec according to getCookieSpec(String) (can be null)

uri - the uri information that will be use to complete Cookie information (host, port and path). If null then the DEFAULT_URI_STRING will be used.

Throws:

MalformedCookieException

parseCookiesAsAServer

public static Cookie[] parseCookiesAsAServer(Header header,
                                             URI uri)

This method parses the value of an HTTP "Cookie" header that comes from a client to a server. It returns all the Cookies present in the header.

Parameters:

header - the header from which the cookie will be parsed. Please not that only the value of this header will be used. No validation will be made to make sure that the headerName is actually a HttpConstants.HEADER_COOKIE.

parseCookiesAsAServer

public static Cookie[] parseCookiesAsAServer(String headerValue,
                                             URI uri)

This method parses the value of an HTTP "Cookie" header that comes from a client to a server. It returns all the Cookies present in the header.

Parameters:

headerValue - the value of the header from which the cookie will be parsed.

transformServerCookieToClientCookie

protected static Cookie transformServerCookieToClientCookie(org.apache.tomcat.util.http.ServerCookie serverCookie)

Transforms a ServerCookie (from Apache Tomcat) into a Cookie (from commons httpclient). Both types of Cookie hold the same data but the ServerCookie is the type that you get when parsing cookies as a Server.

formatCookieForASetCookieHeader

public static String formatCookieForASetCookieHeader(Cookie cookie)

This method formats the cookie so it can be send from server to client in a "Set-Cookie" header.

addCookiesToClient

public static void addCookiesToClient(HttpClient client,
                                      Object cookiesObject,
                                      String policy,
                                      MuleEvent event,
                                      URI destinationUri)

Adds to the client all the cookies present in the cookiesObject.

Parameters:

cookiesObject - this must be either a Map<String, String> or a Cookie[]. It can be null.

event - this one is used only if the cookies are stored in a Map in order to resolve expressions with the ExpressionManager.

destinationUri - the host, port and path of this URI will be used as the data of the cookies that are added.

putAndMergeCookie

public static Object putAndMergeCookie(Object preExistentCookies,
                                       String cookieName,
                                       String cookieValue)

This method merges a new Cookie (or override the previous one if it exists) to the preExistentCookies. The result (the old cookies with the new one added) is returned. If a cookie with the same name already exists, then it will be overridden.

It is important that you use the returned value of this method because for some implementations of preExistentCookies it is not possible to add new Cookies (for example, on Cookie[]).

Parameters:

preExistentCookies - this must be either a java.util.Map<String, String> or a Cookie[]. It can be null.

cookieName - the new cookie name to be added.

cookieValue - the new cookie value to be added.

putAndMergeCookie

public static Object putAndMergeCookie(Object preExistentCookies,
                                       Cookie[] newCookiesArray)

Merges all the Cookies in newCookiesArray with the preExistentCookies, adding the new ones and overwriting the existing ones (existing means same cookie name).

It is important that you use the returned value of this method because for some implementations of preExistentCookies it is not possible to add new Cookies (for example, on Cookie[]).

putAndMergeCookie

public static Object putAndMergeCookie(Object preExistentCookies,
                                       Map<String,String> newCookiesMap)

Merges all the Cookies in newCookiesMap with the preExistentCookies, adding the new ones and overwriting the existing ones (existing means same cookie name).

It is important that you use the returned value of this method because for some implementations of preExistentCookies it is not possible to add new Cookies (for example, on Cookie[]).

getCookieValueFromCookies

public static String getCookieValueFromCookies(Object cookiesObject,
                                               String cookieName)

Searches and return the cookie with the cookieName in the cookiesObject. It returns null if the cookie is not present.

asArrayOfCookies

public static Cookie[] asArrayOfCookies(Object cookiesObject)

Returns an array view of the cookiesObject.