StoredHash::ISA

- NAME
- DESCRIPTION
- SYNOPSIS
- METHODS
  - my ($id) = $e->insert(%opts)
  - $entry->update($ids)
  - $entry->delete($ids)
  - $e = MyType->load($ids)
  - $e->reload($ids)
  - MyType->loadset($filter, $sortattrs, %opts)
  - MyType->exists($ids)

# NAME

StoredHash::ISA - Allow Object to be-a StoredHash by automatically inheriting persistence abilities.

# DESCRIPTION

StoredHash::ISA allows to create an IS-A (ISA in Perl lingo) relationship between any object class and StoredHash persister. This allows you to call StoredHash methods directly via instance (or as Class methods where appropriate).

Because StoredHash::ISA bases persistence operations on class introspection, the persisted objects must belong to a class package and not be "plain" HASHes (You'd use StoredHash). Even when some methods are overloaded to work as Instance or class methods, the Objects must be blessed.

Using StoredHash::ISA as a base class allows you to use following persistence methods

- insert() - as instance method
- update() - as instance method
- load() - as class method
- loadset() - as class method
- delete() - as instance method - or class method
- exists() - as class method
- reload() - StoredHash::ISA custom instance method to reload instance from db

The ways of using methods (class vs. instance) above. Perl generally allows class methods (i.e. non-instance methods) to be called with two syntaxes (with major underlying differences):

       ThePack::a_method()
       # And
       ThePack-> a_method()

All StoredHash::ISA class methods (as listed above) need to be called using ThePack-> a_method() (this is related to giving framework a hint about objects type).

# SYNOPSIS

Package wanting to be-a persister:

       {
         package Justanother::Object;
         # Inherit persister methods
         # our @ISA = ('StoredHash::ISA'); # Or more by more modern style ...
         use base ('StoredHash::ISA');
         # Must declare
         our $shp = {'table' => 'another', 'pkey' => ['id'], 'autoid' => 1,}
         # Custom functionality ... methods as usual

       }

using the class ...

       my $o = Justanother::Object->new('prop' => 'The Value',);
       my $id = $o->insert();

       # Load object
       my $o = Justanother::Object->load([46]);
       # Load related children (blessed automatically)
       my $o->{'items'} = Justanother::Object::Children->loadset({'parent' => 46});

       # Setting up Your inheriting class-package for persistence
       {
         package Justanother::Object;

         our $shp = {'table' => 'anotherobj', ...};
         use base 'StoredHash::ISA'; # Same as our @ISA = ('StoredHash::ISA');
       }

# METHODS

Implementations as distinct instance methods

## my ($id) = $e->insert(%opts)

Insert an instance of a class to database. Return id(s) as a array / list (real array that is).

## $entry->update($ids)

Update entry in database. Allows using explicit 'attrs' to minimize attributes to be updated. Return true value on success. Throw exception on failure.

## $entry->delete($ids)

Delete an instance of an entry from DB. Note that as the persisted version ceases to exist, probably the runtime instance should as well.

       $entry->delete($ids)
       undef($entry);

## $e = MyType->load($ids)

Class Method to load an entry of particular type from DB. Return (blessed) entry.

## $e->reload($ids)

Reload entry instance from database. $ids is optional as long as entry contains the id attribute values. Return (blessed) entry.

## MyType->loadset($filter, $sortattrs, %opts)

Class method to load a set of entries for a class from the database.

## MyType->exists($ids)

Class method to test if an instance exists in database. Return true for "does exist", false for "not".