NAME

Apache2::ClickPath::StoreClient - an Apache2::ClickPath::Store client

SYNOPSIS

 use Apache2::ClickPath::StoreClient;

 my $store=Apache2::ClickPath::StoreClient->new;
 my $val=$store->get( 'val' );
 unless( $store->set( val=>$v ) ) {
   my $code=$store->lasterror;
   ...
 }

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.

For more information see the Apache2::ClickPath::Store manpage.

Apache2::ClickPath::StoreClient provides a OO interface to the data stored in an Apache2::ClickPath::Store. It uses the information exported by Apache2::ClickPath to find the correct store.

Apache2::ClickPath::StoreClient can be used from within a mod_perl handler or a CGI script.

If called from a mod_perl handler it requires the GlobalRequest to be set. See Apache2::RequestUtil for more information.

For communication with the store an LWP::UserAgent is used unless a local store is used, see "Local Store" below. It is configured to use keep-alive requests.

METHODS

Apache2::ClickPath::StoreClient->new

the constructor. It uses the environment variables SESSION and ClickPathMachineStore to initiate itself. These variables are exported from Apache2::ClickPath. The store address is given as the 3rd column of a ClickPathMachineTable. It can be either an absolute URL like http://server.com/store or a URI without the server part (/store). In the second case the store is assumed to be located on the same WEB server (in terms of Hostname or IP address, port and protocol (HTTP or HTTPS)).

$store->set( name => $value1, $value2, ... )

The set method is used to write a data item.

On success 1 is returned on failure undef. If there was an error the HTTP response code of the last store operation can be fetched using lasterror().

@list=$store->get( 'name' )

returns a previously stored data item. In scalar context the first data element is returned.

On error undef is returned. The reason can be examined via lasterror().

$code=$store->lasterror

returns the HTTP status code of the last store operation. See Apache2::ClickPath::Store for a list of possible codes.

$ua=$store->ua or $store->ua=$ua

provides access to the internal LWP::UserAgent. In case the store is behind a proxy this can be useful. If a local store is used no user agent is created, see "Local Store" below.

Local Store

If this module is called from within a modperl handler and the store address passed in the ClickPathMachineStore environment variable starts with a slash (/), i.e. the machine part of the URL is omitted, then the store is taken as local. That means the WEB server handling the current request is also providing the store. Hence, access to the store can be short-circuited using a simple sub-request instead of a full-featured user agent.

In this case the ua method will return undef.

Using a local store is the fastest method to access the data. Use it if you can spare an URI for the store on your main server.

SEE ALSO

Apache2::ClickPath Apache2::ClickPath::Store LWP::UserAgent 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.