PGObject (database mapped) classes API

PGObject is a framework to map objects to the PostgreSQL database. LedgerSMB uses it from Perl to wrap the database-level API provided through stored procedures.

Please note that the description below is about the design to be followed. It's not necessarily the case that all code adheres to this scheme as of yet. However, it's the intention that the code base adheres to this design "as soon as possible".

Constructors

The API needs two constructors:

1. To create a new object which will be stored in the database at a later point (but doesn't have a database representation yet)
2. To load an existing object from the database (using some kind of unique key) and create a Perl representation of it

The traditional new() constructor will be used to handle the former case. This constructor is a general Moose constructor which takes the values of the fields and the inherited fields as named arguments. E.g.:

   my $inventory = LedgerSMB::Inventory->new( app => $instance, part_id => $id, lastcost => $cost );

Here, the $instance is a "user's view of the application" (I'm not calling it an application instance, because IMO the database is the application instance; the "application view" is simply a proxy for that, as seen by the user).

The latter case will be handled by the get() constructor. This constructor will take two arguments; first an application view just like the new() constructor, second a primary key or array of primary keys. E.g.:

  my $part = LedgerSMB::Part->get( app => $instance, key => { id => 1 } );
  my @parts = LedgerSMB::Part->get( app => $instance, key => [ { id => 1 }, { id => 2 } ] );

The first form retrieves exactly one part, the one identified by hash as passed as the key argument. The second form retrieves multiple (in this case 2) parts, each identified by the hashes that are the array elements of the argument passed as the key.

Destructors

Since we want to prevent the use of built-ins as subs on objects (things become obfuscated when you do), we have decided to name the "object removal function" (basically the function responsible for destructing the object in the database) will be named remove.

Updating the database representation

Every object which can be retrieved with get() from the database (i.e. has a primary key allowing lookup), will have a mirror method save() to update the in-database representation.