view release on metacpan or  search on metacpan

lib/Alzabo/Design.pod  view on Meta::CPAN

=head1 ARCHITECTURE

There are objects representing the schema, which contains table
objects.  Table objects contain column, foreign key, and index
objects.  Column objects contain column definition objects.  A single
column definition may be shared by multiple columns, but has only one
owner.

This is a diagram of these inheritance relationships:

  Alzabo::* (::Schema, ::Table, ::Column, ::ColumnDefinition, ::ForeignKey, ::Index)
                   /   \
                is parent to
                 /       \
 Alzabo::Create::*   Alzabo::Runtime::*

This a diagram of how objects contain other objects:

                      Schema - makes--Alzabo::SQLMaker subclass object (many)
                     /      \
              contains       contains--Alzabo::Driver subclass object (1)
                  |                 \
               Table (0 or more)     Alzabo::RDBMSRules subclass object (1)
                /  \                  (* Alzabo::Create::Schema only)
               /    \
              contains--------------------
             /        \                   \
            /          \                   \
     ForeignKey      Column (0 or more)    Index (0 or more)
     (0 or more)       |
                    contains
                       |
                  ColumnDefinition (1)

Note that more than one column I<may> share a single definition object
(this is explained in the
L<C<Alzabo::Create::ColumnDefinition>|Alzabo::Create::ColumnDefinition>
documentation).  This is only relevant if you are writing a schema
creation interface.

=head2 Other classes

=over 4

=item * C<Alzabo::Driver>

These objects handle all the actual communication with the database,
using a thin wrapper over DBI.  The subclasses are used to implement
functionality that must be handled uniquely for a given RDBMS, such as
creating new values for sequenced columns.

=item * C<Alzabo::SQLMaker>

These objects handle the generation of all SQL for runtime operations.
The subclasses are used to implement functionality that varies between
RDBMS's, such as outer joins.

=item * C<Alzabo::RDBMSRules>

These objects perform several funtions.  First, they validate things
such as schema or table names, column type and length, etc.

Second they are used to generate SQL for creating and updating the
database and its tables.

And finally, they also handle the reverse engineering of an existing
database.

=item * C<Alzabo::Runtime::Row> and C<Alzabo::Runtime::RowState::*>

The C<Alzabo::Runtime::Row> class represents a single row.  These
objects are created by
L<C<Alzabo::Runtime::Table>|Alzabo::Runtime::Table>,
L<C<Alzabo::Runtime::RowCursor>|Alzabo::Runtime::RowCursor>, and
L<C<Alzabo::Runtime::JoinCursor>|Alzabo::Runtime::JoinCursor> objects.
It is the sole interface by which actual data is retrieved, updated,
or deleted in a table.

The various C<RowState> classes are used in order to change a row's
behavior depending on whether it is live, live and cached, potential,
or deleted.

=item * C<Alzabo::Runtime::JoinCursor> and C<Alzabo::Runtime::RowCursor>

These objects are cursor that returns row objects.  Using a cursor
saves a lot of memory for big selects.

=item * C<Alzabo::Runtime::UniqueRowCache>

Loading this class turns on Alzabo's simple row caching mechanism.

=item * C<Alzabo::Config>

This class is generated by Makefile.PL during installation and
contains information such as what directory contains saved schemas and
other configuration information.

=item * C<Alzabo::ChangeTracker>

This object provides a method for an object to register a series to
backout from multiple changes.  This is done by providing the
ChangeTracker object with a callback after a change is succesfully
made to an object or objects.  If a future change in a set of
operations fail, the tracker can be told to back the changes out. This
is used primarily in
L<C<Alzabo::Create::Schema>|Alzabo::Create::Schema>.

=item * C<Alzabo::MethodMaker>

This module can auto-generate useful methods for you schema, table,
and row objects based on the structure of your schema.

=item * C<Alzabo::Exceptions>

This object creates the exception subclasses used by Alzabo.

=back

=head1 WHY THE SUBDIVISION BETWEEN Alzabo::*, Alzabo::Create::*, and Alzabo::Runtime::*?