INTRODUCTION

The motivation for the design of this module is two-fold.

First, it seeks to provide users with a powerful and rich feature set
for object persistence that lives on top of SQL driven databases in a
way that is transparent to the application programmer.  Users of this
framework create Perl objects, manipulate them as they please,
indicate that they want them saved to the database, and later load
them for further interaction.  During all of this the user is relieved
of the burden of hand-crafting SQL statements.

Second, this framework seeks to enforce a judicious balance between
efficiency and extensibility in database table structure and querying
mechanisms.  While you are certainly free to mix and match usage of
this framework with custom tables and raw SQL of your own, you are not
apt to need to so often, if ever, and the result will be a consistent
and coherent system.  Table layout will be clean, and manipulation of
table contents will occur in a fashion that pays heed both the need to
minimize resource consumption and program complexity.

FRAMEWORK COMPONENTS

The core classes of the framework embody the following things:
objects, links, queries, and result sets.  Objects lie at the center
of this system, as every operation herein involves creating,
modifying, deleting and linking them.  Links serve as a way of tying
together objects in arbitrary ways.  Queries embody specifications of
a collection of objects in a database, and possibly also relatives in
which you are interested.  Result sets are what you get back when you
execute queries; they function more or less as iterators.

  OBJECTS

Underneath the hood, objects are stored and loaded from database
tables that have nearly limitless flexibility in their design, but
must adhere to one constraint.  Specifically, a table that holds
objects must have a solo primary key, and it must be specified as an
automatically incrementing integer.  This will function as what is
known as a surrogate primary key, a column that has no semantic
meaning except to act as a row identifier.  This key is of central
importance to loading objects via links.

The fields of an object consist of all of the columns of the table
that house objects of the given type.  You may get and set all of the
field values of an object, except for the primary key, which may only
be retrieved, not set.  Objects also have contextual values, values
that are set when an object is loaded via a link, that indicate the
context from which they were instantiated.  These contextual values
can not be set directly via the object, but rather are set when object
linking information is put into the database.

To create an object class of your own, you will do so by subclassing
PROP::Object.  At the very simplest level, you can get away with
doing nothing more than providing in this package a get_table_name()
method that returns the name of the table in which objects of this
type reside in the database.  The PROP::Object base class will
use this method to extract the format of the table, to auto-generate
accessor methods, and to save/load objects to/from the table.  While
providing the get_table_name() method is the only thing that you
strictly must do, you will probably want to treat your subclass as a
decorator class, providing various convenience methods that wrap up
invocations of methods in the base class, manipulating links to other
objects, etc.

  LINKS

Links are how one ties together objects into collections, and are
embodied in the PROP::Link class.  Under the hood, link tables
have dual primary keys, and zero or more contextual fields.  The two
primary key fields house the surrogate primary keys of the objects
being linked, and the contextual fields provide, well, contextual
information, information that will be accessible from objects after
they have been loaded via a link that indicates from whence they have
sprung.

This general format is conducive to specifying any kind of
relationship information that is desired, whether it be on-to-one,
one-to-many, or many-to-many.

  QUERIES

Query objects are the mechanism via which one loads collections of
objects.  They come in two flavors: PROP::Query::Object and
PROP::Query::Link.  The former is used to query collections of
objects.  The latter is used to query collections of links, and one or
more such objects can be specified to the former to facillitate the
loading of objects along with specific relatives all in one fell swoop
as opposed to doing lazy loading at a later point.  Queries can
specify conditions, orderings, and limits.  With the right combination
of properly constructed query objects, one can load pretty much any
desired collection of information via the framework.

  RESULT SETS

Result set objects, returned by the execute() methods of query
objects, not only act as convenient iterators over collections of
objects, but also perform behind-the-scenes work to avoid choking
system memory when queries specify very large collections of data.
While the user of a result set object can treat it like a stream,
casually pulling back one object after another, underneath the hood
the result set object repeatedly pulls in reasonable sized chunks of
data, refilling its buffers every time it runs out of results.  In the
case of loading objects along with relatives, what the result set
object is doing unbeknownst to the user is taking several disjointed
streams of results, one for the objects and one for each type of
relative, and sewing them together into a single stream of objects
with the relatives loaded.

EXTENSIBILITY

Presently this framework only supports the MySQL database, but it has
been designed to be highly database agnostic, and to allow for people
to write extensions that allow for the use of other RDBMS.
Specifically, DBD specific code lives in subclasses of more generic
classes.  For example, when you instantiate a subclass of PROP::Object,
the base class constructor examines which RDBMS is in use, and
mangle's the subclass's ISA array to no longer have PROP::Object as its
base class, but rather PROP::Object::MySQL which is a subclass of
PROP::Object that provides MySQL specific functionality, such as
extracting auto_increment values from statement handles.  The
PROP::Conf class is another example of such subclassing, and
PROP::Conf::MySQL is written to parse .my.cnf files to extract
connection information.
