org.mule.transport.http
Class CookieHelper

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).

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).

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).

parseCookiesAsAServer

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.

transformServerCookieToClientCookie

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.

putAndMergeCookie

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.