The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.

NAME

Class::AutoDB::Collection - Schema information for an AutoDB database

SYNOPSIS

This a major subsystem of Class::AutoDB which keeps track of the classes and collections being managed by the AutoDB system. Most users will never use this class explicitly. The synopsis show approximately how the class is used by AutoDB itself.

 use Class::AutoDB;
 use Class::AutoDB::Registry;
 my $autodb=new Class::AutoDB(-database=>'test');
 my $registry=new Class::AutoDB::Registry(-autodb=>$autodb);
 $registry->register
   (-class=>'Person',
    -collection=>'Person',
    -keys=>qq(name string, sex string, friends list(string)));
 @registrations=$registry->registrations;# all registrations
 @collections=$registry->collections;    # all collections
 
 confess "Current registry inconsistent with saved one" 
   unless $registry->is_consistent;
 if ($registry->is_different && !$registry->is_sub {
                                       # current registry expands 
                                       #   saved registry
   $registry->alter;                   # SQL statements to change
                                       #   database structure to
                                       #   reflect changes
 }
 $registry->put;                       # store in database for next time
 
 # Other commonly used methods
 $registry->create;                    # SQL statements to create database
 $registry->drop;                      # SQL statements to drop database

DESCRIPTION

This class maintains the schema information for an AutoDB database. There can only be one registry per database and you should only have one registry object in your program. The registry object may contain two versions of the registry.

  1. An in-memory version generated by calls to the 'register' method. This method is usually called automatically when AutoClass proceses %AUTO_PERSISTENCE declarations from classes as they are loaded. The 'register' method can also be called explicitly at runtime.

  2. 2. A version saved in the database. The database version is supposed to reflect the real structure of the AutoDB database. (Someday we will provide a method for confirming this.)

Before the AutoDB mechanism can run, it must ensure that the in-memory version of the registry is self-consistent, and that the in-memory and database versions are mutually consistent. (It doesn't have to check the database version for self-consistency since the software won't store an inconsistent version.) The in-memory version is inconsistent if the same search key is registered for a collection with different data types. The in-memory and database versions are inconsistent if the combination has this property.

The in-memory and database versions of the registry can be different but consistent if the running program registers only a subset of the collections that are known to the system, or registers a subset of the search keys for a collection. This is a very common case and requires no special action.

The in-memory and database versions can also be different but consistent if the running program adds new collections or new search keys to an existing collection. In this case, the database version of the registry and the database itself must be updated to reflect the new information. Methods are provided to effect these changes.

This class talks to the database.