Persistent Perl Objects

The Persistent Perl Objects (PPO) provide a functionality to store perl objects persistently in a mySQL database.

Overview

The PPO allows you to create an object schema in XML, which will be used to generate:

• an SQL file to create the underlying database
• a set of perl modules to create, read, update and delete objects
• a set of perl stub modules to create custom access methods for the objects if desired

On this page you will get a short introduction on how to use the PPO. A more detailed example can be found at PPO Example. You can find the definition of the XML at PPO XML Definition.

Source

The PPO module is checked into CVS. If you wish to use it, check it out to your cvs working directory and make sure it is in your path so the perl interpreter can find it. Something like the following should happen:

username@biologin-1:~/cvs$ cvs co PPO
Enter passphrase for key '/home/username/.ssh/id_rsa': 
cvs checkout: Updating PPO
U PPO/.cvsignore
U PPO/DBMaster.pm
U PPO/DBObject.pm
U PPO/DBObjectCache.pm
U PPO/DBSQLArray.pm
U PPO/Makefile
U PPO/PPOBackend.pm
U PPO/PPOGenerator.pm
U PPO/generate.pl
cvs checkout: Updating PPO/PPOBackend
U PPO/PPOBackend/MySQL.pm
U PPO/PPOBackend/SQLite.pm

Usage

First, create a directory to store your project files. Within this directory, create an XML file to describe your object schema. The XML must have the following format:

 <?xml version="1.0" encoding="UTF-8"?>
 <project_space label="ProjectName1">
   <object label="ObjectName1">
     <scalar label="attributeName1" type="int" mandatory="1" />
     <scalar label="attributeName2" type="CHAR(25)" />
     <scalar label="attributeName3" type="text" default="-" />
     <object_ref label="attributeName6" type="ProjectName1::ObjectName7" />
     <array>
       <object_ref label="attributeName4" type="ProjectName2::ObjectName2" />
     </array>
     <array>
       <scalar label="attributeName5" type="boolean" />
     </array>
     <unique_index>
       <attribute label="attributeName1" />
       <attribute label="attributeName2" />
     </unique_index>
   </object>
 </project_space>

After creating the schema file, you can call the generate script from the PPO to

1. create the perl modules and
2. create the PPO database on your database system.

generate.pl -xml xml_file -perl_target target_dir/

This will create a perl modules for your schema and a subdirectory with the neccessary ObjectBase.pm file which contains the access methods for your objects. Within this directory, you will also find a separate perl module for every object type in your schema. These files are stubs that allow you to customize the access methods to the according objects.

Note: the trailing '/' is important for the -perl_target parameter!

generate.pl -xml xml_file -backend db_backend -database db_name
e.g.: generate.pl -xml xml_file -backend MySQL -database my_db_name -user root

Run this command to create database on your database host. For this to work best, you have to be on the machine the database server runs on (in our case that's biofiler).

The setup of your schema is now complete. The following example will demonstrate how to use it in your code.

# include the Database Master Module
use DBMaster;

# initialize a DBMaster object
my $dbmaster = DBMaster->new(-database => 'my_db_name');

# create an object, passing attributes as a hash
my $new_object = $dbmaster->MyObject->create( { attribute1 => 'value1',
                                                attribute2 => 'value2' } );

# it's a good idea to check what you got back
unless (ref $new_object) {
  # substitute with a more appropriate reaction
  die "Unable to create object.";
}

# change an attribute value
$new_object->attribute1( 'new_value' );

# retrieve an attribute value
my $value = $new_object->attribute1();

# get a single object, using an indexed attribute
my $new_object2 = $dbmaster->MyObject->init( { key_attribute1 => 'value1' } );

# get all objects that match the passed attribute values
my $object_list_array_reference = $dbmaster->MyObject->get_objects( { attribute1 => 'value1' } );

foreach (@$object_list_array_reference) {
  # do something with each element of that array
}

# delete an object (and remove it from the database)
$new_object->delete();