The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Apache2-ClickPath-1.901
River stage zero No dependents
++
/ Apache2::ClickPath::Store

NAME

Apache2::ClickPath::Store - use Apache2::ClickPath sessions to store information

SYNOPSIS

 LoadModule perl_module ".../mod_perl.so"
 PerlLoadModule Apache2::ClickPath::Store
 ClickPathStoreDirectory "some_directory"
 ClickPathStorePath "/uri"
 ClickPathStoreTimeout 300
 ClickPathStoreCleanupInterval 60

DESCRIPTION

Apache2::ClickPath::Store and Apache2::ClickPath::StoreClient can be used in conjunction with Apache2::ClickPath to store arbitrary information for a session. The information itself is stored on a WEB server and accessed via HTTP. Apache2::ClickPath::Store implements the server side and Apache2::ClickPath::StoreClient the client side.

The system is designed to work for a WEB server cluster as well as for a single WEB server. Assuming there is a cluster consisting of N machines all using Apache2::ClickPath to provide session identifiers. Then each WEB server can manage its own information store running on the same server or all servers can use a single or a few dedicated information stores. The information store is simply another WEB server or <Location> running Apache2::ClickPath::Store.

Here each WEB server manages its very own information store:

  +-------------------------+
  |     +----------------+  |
  |     | Cluster        |  |
  |     |                |  |
  |     | +-------------+|  | access the server's very own
  |     | | Server 1    ||  | information store
  |     | |             ||  |
  |     | |        *--------+
  |     | | StoreClient ||
  |     | |        *--------+
  |     | |.............||  |
  |     | | <Loc /store>||  | access a foreign
  +------>|  Info Store ||  | information store
        | | </Loc>      ||  |
        | +-------------+|  |
        |                |  |
        | ...            |  |
        |                |  |
        | +-------------+|  |
        | | Server N    ||  |
        | |.............||  |
        | | <Loc /store>||  |
  +------>|  Info Store ||  |
  |     | | </Loc>      ||  |
  |     | +-------------+|  |
  |     +----------------+  |
  +-------------------------+

And here is a centralized information store:

   here work
   Apache2::ClickPath and
   Apache2::ClickPath::StoreClient
  +----------------+
  | Cluster        |                   and here
  |                |                   Apache2::ClickPath::Store
  | +-------------+|                  +------------+
  | | Server 1    ||                  |            |
  | |             ||    info store    |            |
  | |        *----------------------->|   Info     |
  | |             ||      access      |            |
  | +-------------+|  +-------------->|   store    |
  |                |  |               |            |
  | ...            |  |               |            |
  |                |  |               +------------+
  | +-------------+|  |
  | | Server N    ||  |
  | |             ||  |
  | |        *--------+
  | |             ||
  | +-------------+|
  +----------------+

Protocol

The store offers a simple HTTP-form interface to get and set information items. It doesn't matter whether GET or POST requests are used. The data is accepted in multipart/form-data or application/x-www-form-urlencoded. The following CGI-parameter control how the data is accessed:

a

can be either get or set and defines whether the data is read or written.

s

the session identifier. All data is stored in a session-oriented way. Normally this is a session that was generated by Apache2::ClickPath but in principle it could be any string not containing a slash (/). It must not start with a hash sign (#).

k

within a session data is accessed via a key. The key is a string of characters all matching Perl's \w regular expression. A particular data item is identified by combination of session and key.

v

this parameter is valid only if a is set. It contains the actual data to be written.

Normally the store answers a request with HTTP status code 200 (OK). In case of a read operation the response body contains just the data item. The HTTP content-type is set to application/octet-stream. In case of a write operation the string ok is returned with the content-type set to text/plain.

If something went wrong it is indicated by the HTTP status code. The store returns the following codes:

500 Server Error

this indicates a configuration error. Maybe the data directory doesn't exist or is not writeable.

400 Bad Request

an invalid key or session identifier was used.

404 Not Found

the data item identified by the combination of session and key was not found. If the item had once existed then it was possibly hit by a timeout.

CONFIGURATION

Apache2::ClickPath::Store is loaded with a PerlLoadModule directive and then configured with the following directives. At least ClickPathStoreDirectory must be given to use the store.

ClickPathStoreDirectory

sets the directory where the session data is stored. Under this directory subdirectories will be created one for each session. These subdirectories then will contain data files one for each data item.

If a relative path is given it is treated relative to ServerRoot.

ClickPathStorePath

set an URI where the store is located. That directive effectively created a <Location> section where the store runs. The following lines have the same effect as ClickPathStorePath /store:

 <Location /store>
     SetHandler modperl
     PerlResponseHandler Apache2::ClickPath::Store::handler
 </Location>

If omitted the whole server is configured as store.

ClickPathStoreTimeout
ClickPathStoreCleanupInterval

These 2 directives control data expiring and removal. If a timeout is set (in seconds) each time a connection is hung up a cleanup handler is run. The first thing it checks if at least a cleanup interval is passed by since its last run. If no nothing is done. If yes it finds all subdirectories of ClickPathStoreDirectory that are not modified for more than a timeout period. Each time a data item is accessed (read or written) its directories modification time is adjusted. Thus, checking the modification time of the directory checks if the session data was in use for the last timeout period or not.

Then each expired directory is marked by prepending a hash sign (#) to its name. This way the data is not accessible anymore but pending operations in parallel processes can finish normally.

ClickPathStoreTimeout specifies the timeout period in seconds. ClickPathStoreCleanupInterval specifies after how many seconds the cleanup handler should run again. It defaults to 60.

SEE ALSO

Apache2::ClickPath Apache2::ClickPath::StoreClient http://perl.apache.org, http://httpd.apache.org

AUTHOR

Torsten Foertsch, <torsten.foertsch@gmx.net>

COPYRIGHT AND LICENSE

Copyright (C) 2004-2005 by Torsten Foertsch

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