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.

BUGS and WISH-LIST

Name

Description

Priority/When

Transients

Specify transient registry attributes that are not stored.

Useful. This release or next. After transient implemented in Serialize

METHODS and FUNCTIONS - Initialization

Title

new

Usage

my $registry=new Class::AutoDB::Registry;
my $saved_registry=new Class::AutoDB::Registry
      (-autodb=>$autodb, -object_table=>'_AutoDB');

Function

Constructor.

Args

-autodb

Class::AutoDB object for this database. Must already be connected.

-object_table

Name of the database table used to store AutoDB objects. Default _AutoDB. All objects, including the registry, are stored in this table.

Returns

Registry object

METHODS and FUNCTIONS – Simple Attributes

These are methods for getting and setting the values of simple attributes. Methods have the same name as the attribute. Some of these should be read-only (more precisely, should only be written by code internal to the object), but this is not enforced.

To get the value of attribute xxx, just say

$xxx=$object->xxx;

To set an attribute, say

$object->xxx($new_value);

To clear it, say

$object->xxx(undef);

Attribute

autodb

Function

Class::AutoDB object connected to database

Access

Read-write


Attribute

oid

Function

Object id of saved registry

Access

Read-only. No mutator provided even for internal use

METHODS and FUNCTIONS – Manage registrations and collections

Title

register

Usage

$registry->register
   (-class=>'Person',
    -collection=>'Person',
    -keys=>qq(name string, dob integer, 
              significant_other object,friends list(object)),
    -transients=>[qw(age)],
    -auto_gets=>[qw(significant_other)]);

Function

Register a collection with the system

Args

-class

Name of class being registered

-collection

Name of collection being registered or ARRAY ref of names

-collections

Synonym for -collection

-keys

Search keys for collection.

Can be string of comma separated attribute and data type pairs, or ARRAY ref of attributes in which case the type is assumed to be 'string'.

-transients

ARRAY ref of attributes that will not be stored.

-auto_gets

ARRAY ref of attributes that should be automatically retrieved when this object is retrieved.

Returns

Nothing

Notes

The arguments are passed to Class::AutoDB::Registration::new.

The keys argument is a HASH ref of attribute, data type pairs. Each attribute is generally an attribute defined in the AutoClass @AUTO_ATTRIBUTES or @OTHER_ATTRIBUTES variables. (echnically, it's the name of a method that can be called with no arguments. The value of an attribute must be a scalar, an object reference, or an ARRAY (or list) of such values.

The data type can be 'string', 'integer', 'float', 'object', or the phrase list(<data type>), eg, 'list(integer)'. These can be abbreviated. The types 'object' and 'list(object)' only work for objects whose persistence is managed by AutoDB.

The 'keys' parameter can also be an array of attribute names, eg,

-keys=>[qw(name sex)]

in which case the data type of each attribute is assumed to be 'string'. This works in many cases even if the data is really numeric as discussed in the Persistence Model section of the Class::AutoDB man page.



Title

collections

Usage

my @collections=$registry->collections;

my $collections=$registry->collections;

Function

Return all collections defined in the registry

Args

None


Returns

ARRAY or ARRAY ref of Class::AutoDB::Collection objects depending on context



Title

collection

Usage

my $collection=$registry->collection($name);

Function

Lookup a collection given its name

Args

$name

Name of collection to be looked up. Can also be a collection object, in which case the collection name is used.

Returns

Class::AutoDB::Collection object



Title

merge

Usage

$registry->merge

Function

Merge changes from current registry into saved version

Args

none


Returns

Nothing

Notes

If the saved registry does not contain a collection of the same name, the new collection is simply added to the registry. If the registry contains a collection of the same name, the information from the new collection is merged with the existing collection. It is an error if the merged information is not consistent.

METHODS and FUNCTIONS – Manage database schema

Title

schema

Usage

my @sql=$registry->schema
my $sql=$registry->schema
my @sql=$registry->schema($what)
my $sql=$registry->schema($what)

Function

Returns SQL statements needed to create, drop, or alter the registry. Does not touch the database

Args

$what

String indicating what schema operation is desired:

create – default
drop
alter

Returns

ARRAY or ARRAY ref depending on context. Each element of the results is a single SQL statement as a string

METHODS and FUNCTIONS – Read and write registry

These methods read or write the registry from the actual database. The registry is should already be connected to the database.

Title

get

Usage

$registry->get

Function

Retrieve saved registry from the database

Args

none


Returns

Nothing



Title

put

Usage

$registry->put

Function

Store saved registry in the database

Args

none


Returns

Nothing