NAME

CGI::Cookie::Jam - Jam a large number of cookies to a small.

SYNOPSIS

 use CGI::Cookie::Jam;
 
 my $jam = CGI::Cookie::Jam->new('cookie_jammed');
 
 $jam->enjam(
    name    => 'Masanori HATA'           ,
    mail    => 'lovewing@geocities.co.jp',
    sex     => 'male'                    ,
    birth   => '2003-04-09'              ,
    nation  => 'Japan'                   ,
    pref    => 'Saitama'                 ,
    city    => 'Kawaguchi'               ,
    tel     => '+81-48-2XX-XXXX'         ,
    fax     => '+81-48-2XX-XXXX'         ,
    job     => 'student'                 ,
    role    => 'president'               ,
    hobby   => 'exaggeration'            ,
 );

DESCRIPTION

This module provides jam-ming method about WWW cookie. Cookie is convenient but there are limitations on the number of cookies that a client can store at any one time:

 300 total cookies
 4KB per cookie, where the NAME and the VALUE combine to form the 4KB limit.
 20 cookies per server or domain.

Especially, 20 cookies limitation could be a bottle neck. So this module try to jam some cookies to a cookie at maximum size of 4KB, that you can save the total number of cookies to a minimum number.

METHODS and FUNCTIONS

new($cookie_name [, size => $byte])

Constructor class method. $cookie_name will be coupled with numbering _XX (XX: 00~99) and be used as the NAME of NAME=VALUE string in Set-Cookie: HTTP header.

When you put size attribute, the size of a cookie (that is the size of NAME=VALUE string) will be less than $byte Bytes. The default value of size is 4096 Bytes (4KB).

enjam( $name1 => $value1 [, $name2 => $value2, ...] )

This object-class method jams a lot number of multiple NAME=VALUE strings for Set-Cookie: HTTP header to a minimum number of NAME=VALUE strings for Set-Cookie: HTTP header. Then returns a list of multiple en-jam-ed strings.

The en-jam-ming algorithm is realized by twice uri-escaping. At first, each cookie's NAME and VALUE pairs are uri-escaped and joined with = (an equal mark). Then, multiple NAME=VALUE pairs are joined with & (an ampersand mark). This procedure is the very uri-encoding (see http://www.w3.org/TR/html4/interact/forms.html#h-17.13.4.1).

Still a cookie has only one NAME=VALUE pair, the uri-encoded string must be re-uri-escaped at the second procedure. As a result:

 '=' is converted to '%3D'
 '&' is converted to '%26'
 '%' is converted to '%25'

At last, this module uses the jam's $cookie_name (which is, of course, uri-escaped, and coupled with a serial number like $cookie_name_XX) as cookie NAME and uses the twice uri_escaped string as cookie VALUE, then join both with = to make a NAME=VALUE string. The final product is the very en-jam-ed cookie.

When you use en-jam-ed cookie, you may de-jam to reverse the above procedure:

 1: Extract VALUEs
    and join the splitted en-jam-ed VALUE strings to a string.
 2: uri-unescape '%3D' to '=', '%26' to '&', '%25' to '%'.
 3: uri-decode the uri-encoded string to multiple NAME and VALUE pairs.

This module is going to implement above function as dejam() method. Otherwise, you may implement dejam() function by client side using with JavaScript and so on.

SEE ALSO

Netscape: http://wp.netscape.com/newsref/std/cookie_spec.html (Cookie)

RFC2965: http://www.ietf.org/rfc/rfc2965.txt (Cookie)

HTML4.01: http://www.w3.org/TR/html4/interact/forms.html#h-17.13.4.1 (uri-encode)

AUTHOR

Masanori HATA <lovewing@geocities.co.jp> (Saitama, JAPAN)

COPYRIGHT

Copyright (c) 2003 Masanori HATA. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.