NAME

SPOPS::Manual::Intro - Introduction and overview of SPOPS

DESCRIPTION

This document aims to answer the questions:

What needs does SPOPS fill?
Why would I use SPOPS?
How does everything broadly fit together?

CLASS HIERARCHY

SPOPS (Simple Perl Object Persistence with Security) provides a framework to make your application objects persistent (meaning, you can store them somewhere, e.g., in a relational database), and to control access to them (the usual user/group access rights stuff). You will usually just configure SPOPS by means of configuration files, and SPOPS will create the necessary classes and objects for your application on the fly. You can of course have your own code implement your objects - extending the default SPOPS object behavior with your methods. However, if SPOPS shall know about your classes and objects, you will have to tell it -- by configuring it.

The typical class hierarchy for an SPOPS object looks like this:

     --------------------------
    |SPOPS                     |
     --------------------------
                ^
                |
     --------------------------
    |SPOPS::MyStorageTechnology|
     --------------------------
                ^
                |
     --------------------------
    |SPOPS::MyApplicationClass |
     --------------------------

SPOPS
Abstract base class, provides persistency and security framework (fetch, save, remove)

Example: You are reading it now!
SPOPS::MyStorageTechnology
Concrete base class, provides technical implementation of framework for a particular storage technology (e.g., Filesystem, RDBMS, LDAP, ... )

Example: SPOPS::DBI, SPOPS::GDBM, ...
SPOPS::MyApplicationClass
User class, provides semantic implementation of framework (configuration of parent class, e.g., database connection strings, field mappings, ... )

Example: MyApplication::User, MyApplication::Document, ...

SPOPS Object States

Basically, each SPOPS object is always in one of two states:

Runtime State
Persistent State

In Runtime State, the object representation is based on a hash of attributes. The object gets notified about any changes to it through the tie mechanism.

In Persistent State, the object exists in some more permanent form -- saved in a database, in the filesystem, in a directory, etc.

You can control what happens to the object when it gets written to its persistent form, or when it is deleted, or fetched from its storage form, by implementing a simple API: "fetch()", "save()", "remove()". (The "save()" method encompasses both 'create' and 'update' actions.)

     -------------         save, remove         ----------------
    |Runtime State|     ------------------->   |Persistent State|
     -------------      <------------------     ----------------
                              fetch

Around the "fetch()", "save()", and "remove()" calls, you can execute helper functions (rules in one or more of the following stages: pre_fetch, post_fetch, pre_save, post_save, pre_remove, post_remove), in case you need to prepare anything or clean up something, according to needs of your storage technology. These are pushed on a queue based on a search of @ISA, and executed front to end of the queue. If any of the calls in a given queue returns a false value, the whole action (save, remove, fetch) is short-circuited (that is, a failing method bombs out of the action). See SPOPS::Manual::ObjectRules for details on the process and how to implement your own.

It's important to note that you have to tell an SPOPS object to persist itself -- it will not happen automatically. A call to "new()" will not create an entry in your datastore, only "save()" will. For instance:

 my $film = Film->new();          # Object exists in memory
 $film->{name} = 'The Matrix';    #   |
 $film->{year} = '1999';          #   |
 $film->save;                     # Object exists in datastore

COPYRIGHT

See SPOPS::Manual for license.

AUTHORS

Chris Winters <chris@cwinters.com>