NAME
Tangram::Schema - describe a system of persistent classes
SYNOPSIS
use Tangram::Core; # or: use Tangram;
$schema = Tangram::Schema->new( $hashref );
$schema = Tangram::Schema->new( %hash ); # only for compatibility
$storage->connect( $schema, ... );
DESCRIPTION
A Schema contains all the information about the persistent aspects of a system of classes. That information is used to perform the mapping between OO constructs and a relational database.
Schema objects are initialized from a nested data structure called a schema hash. The general structure of the schema hash is described here.
The resulting Schema object becomes the owner of the schema hash passed to new(). The hash may not be modified afterwards, and no assumptions can be made regarding its content.
CLASS METHODS
new( $hash )
Returns a new Schema object.
$hash is a reference to a "SCHEMA HASH".
The newly created Schema object becomes the owner of the hash, which can no longer be modified nor reused by client code.
INSTANCE METHODS
deploy( HANDLE )
See Tangram::Deploy.
retreat( HANDLE )
See Tangram::Deploy.
SCHEMA HASH
The schema hash describes the persistent aspects of a system of classes. It is a multilevel data structure.
The first level of the hash contains information that is relevant to the system as a whole.
The second level contains information on a per-class basis.
The third level contains information about the individual fields in a class. That information depends on the type of the field and is not documented here; see "field hash" for a list of predefined persistent types.
Global properties
The first level of the schema hash describes aspects that are global to a system of persistent classes. It has the following aspect:
{
classes =>
{
Identity =>
{
table => 'IdentityState',
abstract => 1
},
NaturalPerson =>
{
bases => [ qw( Identity ) ],
},
LegalPerson =>
{
bases => [ qw( Identity ) ],
},
},
make_object => sub { ... },
set_id => sub { ... }
get_id => sub { ... }
class_table => '...'
sql => { ... },
}classes is a hash called the "class registry". It contains a description of each persistent class.
make_object contains a reference to a closure that returns a new object of a given class. This field is optional: by default, Tangram calls class method new().
set_id and get_id are used together to associate an object ID with a persistent object. By default, Tangram converts a reference to an object to a unique integer value by evaluating the expression 0 + $obj. The result is used as a key in a hash contained in the Storage object. The values in that hash are the object IDs.
If any of your classes use overloading, this approach will not work and you will need to supply your own get/set_id methods.
class_table contains the name of a database table that Tangram uses for internal bookkeeping. It defaults to 'OpalClass' (Opal is Tangram's real name).
Optional field sql contains a hash that can be used to customize some of the SQL generated by Tangram. That hash has the following fields:
default_null
id
cid
cid_size
oid
All the fields are optional.
default_null can be used to deal with those databases that don't support the explicit 'NULL' specifier in column definitions. Defaults to 'NULL'.
The other fields are related to the SQL types that Tangram uses to store meta-information.
Object ids encode the type of the object. Tangram assigns a class id to each persistent concrete class within a Schema. When an object is inserted, Tangram allocates a unique integer from a class-specific allocator, then appends the class id to it. Thus the object id for a NaturalPerson may look like 270005, where 0005 is the class id.
Field id contains the SQL type that is used to map an entire object id. It defaults to 'NUMERIC(15, 0)'.
Field cid contains the SQL type that is used to map a class id. It defaults to 'NUMERIC(5,0)'. Thus Tangram supports 99,999 distinct classes (class id 0 is not used) by default.
Field cid_size contains the number of decimal positions that the class id occupies within the object id.
Field oid contains the SQL type that is used to store the class-specific object counters that are used in the id generation process. It defaults to 'NUMERIC(10, 0)'. Thus Tangram supports 10e10 - 1 distinct objects per class (again the zero is not used).
There are several reasons why you may want to override these default.
You need more objects, more classes, or both.
You want to use more efficient SQL types (at the cost of supporting fewer objects).
Your database doesn't support the default types. PostgreSql springs to mind. PostgreSql users will have to specify something like:
$schema = Tangram::Schema->new( {
...
sql =>
{
default_null => '',
id => 'int4',
cid => 'int4',
oid => 'int4',
cid_size => 3,
}
} );class registry
The class registry is a hash containing one entry per persistent class. The key is the class name, the value is a reference to a hash called the class hash. It contains information on how to map the class.
The class hash has the following fields:
table
abstract
bases
fields
members (deprecated; use fields)
Field table sets the name of the table that Tangram should use to store the state of objects pertaining to this class. This field is optional: it defaults to the class name. If the class name is not an acceptable SQL table identifier, you will need to set this field.
Field abstract contains a boolean that should be true if the class is abstract. If this field is not present, the class is considered to be concrete.
Field bases contains a reference to an array of base classes.
Field fields contains a reference to the "field hash".
Field members is deprecated; use fields instead.
field hash
Each persistent type is identified by a 'typetag', e.g. int, string or array.
All the persistent fields of a given type are grouped together inside the field hash, where the typetag is used as a key. The individual fields are specified in an array or a hash, whose layout is type-dependant. For example:
fields =>
{
string => [ qw( firstName name ) ],
int => [ qw( age ) ],
ref => { partner => { null => 1 } },
array => { children => 'NaturalPerson' },
},The typetag not only specifies the type of a field, but also the way in which it should be mapped to SQL constructs. Sometimes the same Perl type lends itself to more than one mapping, for example there are at least two plausible ways of mapping a Perl array (see Tangram::Array and Tangram::IntrArray).
Tangram's persistent type system is extensible, allowing you to mount your own types and make them persistent. All you have to do is to register your type and provide mapping code. See Tangram::Type.
Tangram comes with built-in support for the following types:
* string, int, real: see Tangram::Scalar
* reference : see Tangram::Ref
* array : see Tangram::Array, Tangram::IntrArray
* Set::Object : see Tangram::Set, Tangram::IntrSet