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

NAME

Persistent::Hash - API Reference (0.1)

DESCRIPTION

This file contains the complete API Reference to Persistent::Hash. It explains the configuration options and their meaning.

Other Persistent::Hash manuals:

Persistent::Hash - Persistent::Hash module overview and description

Persistent::Hash::Manual - Programmer manual, examples and explanations

Persistent::Hash::Storage - Guide to Persistent::Hash Storage module programmers

IMPLEMENTATION

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.

DATA TYPES CONFIGURATION OPTIONS (Constants)

This is an exaustive list of configuration options (constants) that can be overriden in a Persistent::Hash data type.

PROJECT

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)

        i.e. use constant PROJECT => 'MyProject';
        i.e. MyProject/Data_Type_Package

DEBUG_LEVEL

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)

        i.e. use constant DEBUG_LEVEL => 1;

STORAGE_MODULE

Defines the storage module to be used when saving a hash. (default: Persistent::Hash::MySQL)

        i.e. use constant STORAGE_MODULE => 'Persistent::Hash::MySQL';

INFO_TABLE

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.

        i.e. use constant INFO_TABLE => 'phash_info';

DATA_TABLE

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.

        i.e. use constant DATA_TABLE => 'phash_data';

INDEX_TABLE

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.

        i.e. use constant INDEX_TABLE => 'phash_index';

DATA_FIELDS

This option needs to be set to an anonymous list of keys/fields that will be serialized in the DATA_TABLE.

        i.e. use constant DATA_FIELDS => ['field','field2','field3'];

INDEX_FIELDS

This option needs to be set to an anonymous list of keys/fields that will be saved in the INDEX_TABLE.

        i.e. use constant INDEX_FIELDS => ['field','field2','field3'];

STRICT_FIELDS

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)

        i.e. use constant STRICT_FIELDS => 1;

STORABLE

When set to a true value, will allow the hash to be saved to storage. When set to false, Save() will return undef and do NOOP. (default: off)

        i.e. use constant STORABLE => 1;

LOAD_ON_DEMAND

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 Load() alot of object without hitting your storage too much, and then spread the retrieval load by accessing keys in your hashes. (default: on)

        i.e. use constant LOAD_ON_DEMAND => 1;

SAVE_ONLY_IF_DIRTY

When set to a true value, Save() will return undef and do NOOP if the object is not dirty when Save() was called. (default: off)

        i.e use constant SAVE_ONLY_IF_DIRTY => 1;

STANDARD API

Type()

Returns the hash type of a Persistent::Hash. Constructed from the PROJECT config constant and the hash's package name.

        i.e. MyProject/MyProject_Customer

Id()

Returns the current hash id. Returns undef if object has not been saved.

        i.e. my $hash_id = $hash->Id();

TimeCreated()

Returns the epoch time at wich this hash has been saved for the first time. Returns undef when object has not been saved.

        i.e. print localtime($hash->TimeCreated());

TimeModified()

Returns the epoch time of the last time this hash was saved to Storage. Returns undef when object has not been saved.

        i.e. print localtime($hash->TimeModified());

new()

Constructor to create a new hash. No save operation is performed without explicit Save()

        i.e. my $hash = MyProject::MyHash->new();

Load() / load()

Constructor to retrieve a has from storage with it's unique id. Returns undef when object is unloadable.

        i.e. my $hash = MyProject::MyHash->Load($id);

Save()

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.

        i.e. my $hash_id = $hash->Save();

Delete()

Delete a hash from storage and untie the reference. Returns true on success.

        i.e. $hash->Delete();

DATA TYPE METHODS HOOKS

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.

DatabaseHandle()

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.

        i.e.
        
        sub DatabaseHandle
        {
                my $self = shift;

                if(not defined $DBH_CACHE)
                {
                        $DBH_CACHE = DBI->connect('dbi:db:db','dbuser','dbpw') || die $DBI::errstr;
                }

                return $DBH_CACHE; 
        }

SaveHook()

This method will be automatically called after a call to Save() 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:

        i.e. (Unusable object after save)

        sub SaveHook
        {       
                my $self = shift;
                $self->Untie(); 
        }

DeleteHook()

This method will be automatically called after a call to Delete() has been done, just before the object is untied. Use this hook to provide after deletion processing to the object.

        i.e. (Cascading delete) 
        sub DeleteHook
        {
                my $self = shift;

                foreach my $child ($self->{childs)
                {
                        $child->Delete();       
                }
        }

LoadHook()

This method will be automatically called after a call to Load() has been done, just before the object is returned. Use this hook to implement some processing after a load has been done.

        i.e. (Remove index keys after load)

        sub LoadHook
        {
                my $self = shift;

                foreach my $key (@{ $self->INDEX_FIELDS() })
                {
                        delete $self->{$key};
                }
        }

COPYRIGHT

Copyright(c) 2001 Benoit Beausejour <bbeausej@pobox.com>

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

AUTHOR

Benoit Beausejour <bbeausej@pobox.com>

SEE ALSO

Persistent::Hash(1). perltie(1). perl(1).