<HTML>
<HEAD>
<TITLE>Persistent::Hash - API Reference</TITLE>
<LINK REV="made" HREF="mailto:bhcompile@daffy.perf.redhat.com">
</HEAD>
<BODY>
<A NAME="__index__"></A>
<!-- INDEX BEGIN -->
<UL>
<LI><A HREF="#name">NAME</A></LI>
<LI><A HREF="#description">DESCRIPTION</A></LI>
<LI><A HREF="#implementation">IMPLEMENTATION</A></LI>
<LI><A HREF="#data types configuration options (constants)">DATA TYPES CONFIGURATION OPTIONS (Constants)</A></LI>
<UL>
<LI><A HREF="#project">PROJECT</A></LI>
<LI><A HREF="#debug_level">DEBUG_LEVEL</A></LI>
<LI><A HREF="#storage_module">STORAGE_MODULE</A></LI>
<LI><A HREF="#info_table">INFO_TABLE</A></LI>
<LI><A HREF="#data_table">DATA_TABLE</A></LI>
<LI><A HREF="#index_table">INDEX_TABLE</A></LI>
<LI><A HREF="#data_fields">DATA_FIELDS</A></LI>
<LI><A HREF="#index_fields">INDEX_FIELDS</A></LI>
<LI><A HREF="#strict_fields">STRICT_FIELDS</A></LI>
<LI><A HREF="#storable">STORABLE</A></LI>
<LI><A HREF="#load_on_demand">LOAD_ON_DEMAND</A></LI>
<LI><A HREF="#save_only_if_dirty">SAVE_ONLY_IF_DIRTY</A></LI>
</UL>
<LI><A HREF="#standard api">STANDARD API</A></LI>
<UL>
<LI><A HREF="#type()"><CODE>Type()</CODE></A></LI>
<LI><A HREF="#id()"><CODE>Id()</CODE></A></LI>
<LI><A HREF="#timecreated()"><CODE>TimeCreated()</CODE></A></LI>
<LI><A HREF="#timemodified()"><CODE>TimeModified()</CODE></A></LI>
<LI><A HREF="#new()"><CODE>new()</CODE></A></LI>
<LI><A HREF="#load() / load()"><CODE>Load()</CODE> / <CODE>load()</CODE></A></LI>
<LI><A HREF="#save()"><CODE>Save()</CODE></A></LI>
<LI><A HREF="#delete()"><CODE>Delete()</CODE></A></LI>
</UL>
<LI><A HREF="#data type methods hooks">DATA TYPE METHODS HOOKS</A></LI>
<UL>
<LI><A HREF="#databasehandle()"><CODE>DatabaseHandle()</CODE></A></LI>
<LI><A HREF="#savehook()"><CODE>SaveHook()</CODE></A></LI>
<LI><A HREF="#deletehook()"><CODE>DeleteHook()</CODE></A></LI>
<LI><A HREF="#loadhook()"><CODE>LoadHook()</CODE></A></LI>
</UL>
<LI><A HREF="#copyright">COPYRIGHT</A></LI>
<LI><A HREF="#author">AUTHOR</A></LI>
<LI><A HREF="#see also">SEE ALSO</A></LI>
</UL>
<!-- INDEX END -->
<HR>
<P>
<H1><A NAME="name">NAME</A></H1>
<P>Persistent::Hash - API Reference (0.1)</P>
<P>
<HR>
<H1><A NAME="description">DESCRIPTION</A></H1>
<P>This file contains the complete API Reference to Persistent::Hash. It explains
the configuration options and their meaning.</P>
<P>Other Persistent::Hash manuals:</P>
<P><A HREF="/Persistent/Hash.html">the Persistent::Hash manpage</A> - Persistent::Hash module overview and description</P>
<P><A HREF="/Persistent/Hash/Manual.html">the Persistent::Hash::Manual manpage</A> - Programmer manual, examples and explanations</P>
<P><A HREF="/Persistent/Hash/Storage.html">the Persistent::Hash::Storage manpage</A> - Guide to Persistent::Hash Storage module programmers</P>
<P>
<HR>
<H1><A NAME="implementation">IMPLEMENTATION</A></H1>
<P>The basic implementation of Persistent::Hash uses the perltie mechanism to hook into the standard
hash structure and provide additionnal functionnality. When creating a subclass (data type), you basically
create a class that inherits from Persistent::Hash. You control the options of your data type by overloading
constants/subroutines to the desired behaviour.</P>
<P>
<HR>
<H1><A NAME="data types configuration options (constants)">DATA TYPES CONFIGURATION OPTIONS (Constants)</A></H1>
<P>This is an exaustive list of configuration options (constants) that can be overriden in a Persistent::Hash
data type.</P>
<P>
<H2><A NAME="project">PROJECT</A></H2>
<P>The project constant defines the first part of the automatically generated hash type (object type) of a specific
data type. When defining a data type, this value should be set to the project's name. (default: phash)</P>
<PRE>
i.e. use constant PROJECT =&gt; 'MyProject';
i.e. MyProject/Data_Type_Package</PRE>
<P>
<H2><A NAME="debug_level">DEBUG_LEVEL</A></H2>
<P>This constant when set to a true value will activate debugging output to STDERR of Persistent::Hash.
This allows a programmer to troubleshoot problem in a data type. (default: off)</P>
<PRE>
i.e. use constant DEBUG_LEVEL =&gt; 1;</PRE>
<P>
<H2><A NAME="storage_module">STORAGE_MODULE</A></H2>
<P>Defines the storage module to be used when saving a hash. (default: Persistent::Hash::MySQL)</P>
<PRE>
i.e. use constant STORAGE_MODULE =&gt; 'Persistent::Hash::MySQL';</PRE>
<P>
<H2><A NAME="info_table">INFO_TABLE</A></H2>
<P>This constant defines the table used to save the basic information for a Persistent::Hash object. This
table should follow the standard table definition defined in docs/tables.pod.</P>
<PRE>
i.e. use constant INFO_TABLE =&gt; 'phash_info';</PRE>
<P>
<H2><A NAME="data_table">DATA_TABLE</A></H2>
<P>This option defines the table used to save the serialized keys specified in DATA_FIELDS. This table should
follow the standard table definition for 'phash_data' defined in docs/tables.pod.</P>
<PRE>
i.e. use constant DATA_TABLE =&gt; 'phash_data';</PRE>
<P>
<H2><A NAME="index_table">INDEX_TABLE</A></H2>
<P>This option defines the table used to save the keys specified in INDEX_FIELDS. This table needs a mandatory
'id' field and a column for each of the INDEX_FIELDS.</P>
<PRE>
i.e. use constant INDEX_TABLE =&gt; 'phash_index';</PRE>
<P>
<H2><A NAME="data_fields">DATA_FIELDS</A></H2>
<P>This option needs to be set to an anonymous list of keys/fields that will be serialized in the DATA_TABLE.</P>
<PRE>
i.e. use constant DATA_FIELDS =&gt; ['field','field2','field3'];</PRE>
<P>
<H2><A NAME="index_fields">INDEX_FIELDS</A></H2>
<P>This option needs to be set to an anonymous list of keys/fields that will be saved in the INDEX_TABLE.</P>
<PRE>
i.e. use constant INDEX_FIELDS =&gt; ['field','field2','field3'];</PRE>
<P>
<H2><A NAME="strict_fields">STRICT_FIELDS</A></H2>
<P>When set to a true value, only the keys/fields listed in INDEX_FIELDS and DATA_FIELDS will be allowed to be
set in the hash. (default: off)</P>
<PRE>
i.e. use constant STRICT_FIELDS =&gt; 1;</PRE>
<P>
<H2><A NAME="storable">STORABLE</A></H2>
<P>When set to a true value, will allow the hash to be saved to storage. When set to false, <CODE>Save()</CODE> will return undef
and do NOOP. (default: off)</P>
<PRE>
i.e. use constant STORABLE =&gt; 1;</PRE>
<P>
<H2><A NAME="load_on_demand">LOAD_ON_DEMAND</A></H2>
<P>When set to a true value, the actual data and index fields/keys will only be loaded when a key is requested.
This means that you can <CODE>Load()</CODE> alot of object without hitting your storage too much, and then spread the
retrieval load by accessing keys in your hashes. (default: on)</P>
<PRE>
i.e. use constant LOAD_ON_DEMAND =&gt; 1;</PRE>
<P>
<H2><A NAME="save_only_if_dirty">SAVE_ONLY_IF_DIRTY</A></H2>
<P>When set to a true value, <CODE>Save()</CODE> will return undef and do NOOP if the object is not dirty when <CODE>Save()</CODE> was called.
(default: off)</P>
<PRE>
i.e use constant SAVE_ONLY_IF_DIRTY =&gt; 1;</PRE>
<P>
<HR>
<H1><A NAME="standard api">STANDARD API</A></H1>
<P>
<H2><A NAME="type()"><CODE>Type()</CODE></A></H2>
<PRE>
Returns the hash type of a Persistent::Hash. Constructed from the PROJECT config constant
and the hash's package name.</PRE>
<PRE>
i.e. MyProject/MyProject_Customer</PRE>
<P>
<H2><A NAME="id()"><CODE>Id()</CODE></A></H2>
<P>Returns the current hash id. Returns undef if object has not been saved.</P>
<PRE>
i.e. my $hash_id = $hash-&gt;Id();</PRE>
<P>
<H2><A NAME="timecreated()"><CODE>TimeCreated()</CODE></A></H2>
<P>Returns the epoch time at wich this hash has been saved for the first time.
Returns undef when object has not been saved.</P>
<PRE>
i.e. print localtime($hash-&gt;TimeCreated());</PRE>
<P>
<H2><A NAME="timemodified()"><CODE>TimeModified()</CODE></A></H2>
<P>Returns the epoch time of the last time this hash was saved to Storage.
Returns undef when object has not been saved.</P>
<PRE>
i.e. print localtime($hash-&gt;TimeModified());</PRE>
<P>
<H2><A NAME="new()"><CODE>new()</CODE></A></H2>
<P>Constructor to create a new hash. No save operation is performed without explicit <CODE>Save()</CODE></P>
<PRE>
i.e. my $hash = MyProject::MyHash-&gt;new();</PRE>
<P>
<H2><A NAME="load() / load()"><CODE>Load()</CODE> / <CODE>load()</CODE></A></H2>
<P>Constructor to retrieve a has from storage with it's unique id.
Returns undef when object is unloadable.</P>
<PRE>
i.e. my $hash = MyProject::MyHash-&gt;Load($id);</PRE>
<P>
<H2><A NAME="save()"><CODE>Save()</CODE></A></H2>
<P>Perform save to Storage using the currently defined STORAGE_MODULE.
Returns the hash id (or new id if new hash) on success. Undef on error.</P>
<PRE>
i.e. my $hash_id = $hash-&gt;Save();</PRE>
<P>
<H2><A NAME="delete()"><CODE>Delete()</CODE></A></H2>
<P>Delete a hash from storage and untie the reference. Returns true on success.</P>
<PRE>
i.e. $hash-&gt;Delete();</PRE>
<P>
<HR>
<H1><A NAME="data type methods hooks">DATA TYPE METHODS HOOKS</A></H1>
<P>This is an exaustive list of the method can can or should be overloaded by a programmer to create a useful
base class or data type.</P>
<P>
<H2><A NAME="databasehandle()"><CODE>DatabaseHandle()</CODE></A></H2>
<P>This method receives the hash as a reference and should return a database handle. We strongly recommend
implementing some kind of database caching at this level for optimal performance. This method will be called
by the storage module to connect to the database.</P>
<PRE>
i.e.
</PRE>
<PRE>
sub DatabaseHandle
{
my $self = shift;</PRE>
<PRE>
if(not defined $DBH_CACHE)
{
$DBH_CACHE = DBI-&gt;connect('dbi:db:db','dbuser','dbpw') || die $DBI::errstr;
}</PRE>
<PRE>
return $DBH_CACHE;
}</PRE>
<P>
<H2><A NAME="savehook()"><CODE>SaveHook()</CODE></A></H2>
<P>This method will be automatically called after a call to <CODE>Save()</CODE> has been done and can be used to perform tasks
after a save. For example, if you want an object to be unusable after a save:</P>
<PRE>
i.e. (Unusable object after save)</PRE>
<PRE>
sub SaveHook
{
my $self = shift;
$self-&gt;Untie();
}</PRE>
<P>
<H2><A NAME="deletehook()"><CODE>DeleteHook()</CODE></A></H2>
<P>This method will be automatically called after a call to <CODE>Delete()</CODE> has been done, just before the object is untied.
Use this hook to provide after deletion processing to the object.</P>
<PRE>
i.e. (Cascading delete)
sub DeleteHook
{
my $self = shift;</PRE>
<PRE>
foreach my $child ($self-&gt;{childs)
{
$child-&gt;Delete();
}
}</PRE>
<P>
<H2><A NAME="loadhook()"><CODE>LoadHook()</CODE></A></H2>
<P>This method will be automatically called after a call to <CODE>Load()</CODE> has been done, just before the object is returned.
Use this hook to implement some processing after a load has been done.</P>
<PRE>
i.e. (Remove index keys after load)</PRE>
<PRE>
sub LoadHook
{
my $self = shift;</PRE>
<PRE>
foreach my $key (@{ $self-&gt;INDEX_FIELDS() })
{
delete $self-&gt;{$key};
}
}</PRE>
<P>
<HR>
<H1><A NAME="copyright">COPYRIGHT</A></H1>
<P><CODE>Copyright(c)</CODE> 2001 Benoit Beausejour &lt;<A HREF="mailto:bbeausej@pobox.com">bbeausej@pobox.com</A>&gt;</P>
<P>All rights reserved. This program is free software; you can redistribute it and/or modify it under the same
terms as Perl itself.</P>
<P>
<HR>
<H1><A NAME="author">AUTHOR</A></H1>
<P>Benoit Beausejour &lt;<A HREF="mailto:bbeausej@pobox.com">bbeausej@pobox.com</A>&gt;</P>
<P>
<HR>
<H1><A NAME="see also">SEE ALSO</A></H1>
<P>Persistent::Hash(1).
perltie(1).
perl(1).</P>
</BODY>
</HTML>