=head1 NAME

Tangram::Schema - describe a system of persistent classes

=head1 SYNOPSIS

   use Tangram;

   $schema = Tangram::Schema->new( $hashref );

   Tangram::Relational->connect( $schema, ... );

   # write SQL to FILE
   $schema->deploy( \*FILE );

   # write SQL to STDOUT
   $schema->deploy();

=head1 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.

B<note>: No corresponding Perl classes are generated from calling
C<Tangram::Schema-E<gt>new>.  If you want that, and like the behaviour
of the seperately distributed C<Class::Tangram> module, then you
should pass the C<$hashref> in the above example to the
C<Class::Tangram::Generator-E<gt>new()> constructor.  See
L<Class::Tangram::Generator> for more information.

=head1 CLASS METHODS

=head2 new

   $schema = Tangram::Schema->new( $hash );

Returns a new Schema object.

The newly created Schema object becomes the owner of the hash,
which can no longer be modified nor reused by client code.

The schema hash describes the persistent aspects of a system of
classes. It is a multilevel data structure.

=over 4

=item 1

The first level of the hash contains information that is relevant to
the system as a whole.

=item 2

The second level contains information on a per-class basis.

=item 3

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 L<field hash> for a list of predefined
persistent types.

=back

=head2 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 { ... }
      normalize => sub { ... },

      control => '...'

      sql => { ... },
   }

C<classes> is an array called the L<class registry>. It contains a
description of each persistent class.

C<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().

C<set_id> and C<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 C<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.

C<control> is the name of a table that has a single row, containing
the major and minor version numbers of the Tangram that created
the storage, and the highest allocated object id. It defaults
to 'Tangram'.

Optional field C<normalize> contains a subroutine that's called to
transform classnames and fieldnames into table and column names. The
function is called with two arguments; the name to be transformed, and
a 'type' argument (currently one of 'tablename' or 'fieldname'). The
return value should be the transformed string.

Note that it is expected that the normalize sub will return identical
strings with identical arguments, that
C<normalize(normalize($string, $flag), $flag) eq normalize($string, $flag)> 

Optional field C<sql> contains a hash that can be used to customize
some of the SQL generated by Tangram.  The available options are:

=over 4

=item * default_null

C<default_null> can be used to deal with those databases that don't
support the explicit 'NULL' specifier in column definitions.  Defaults
to 'NULL'.  Note that this does not get automatically appended to
attributes that have a SQL type explicitly declared.

=item * id

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 C<270005>, where C<0005> is the class id.

Field C<id> contains the SQL type that is used to map the rowid part
of the object id. It defaults to 'INTEGER'.

=item * oid_sequence

If set, this is the name of a I<sequence> to use as the default OID
generator, should a particular class not define one.

Sequences are an alternate way of generating unique identifiers for
rows.  They are more scalable when you have high concurrency, but most
people won't notice that.

It is also possible to define an OID sequence on a per-class level;
see below for details.

Sequences are emulated on pretend databases like MySQL.

=item * make_id

This is a I<closure> that is expected to return an unique ID.  It is
called like this:

   $make_id->($class_id, $storage)

Where C<$class_id> is the Class identifier for_the newly created
object, and C<$storage> is the B<Tangram::Storage> object.

=item * cid

Field C<cid> contains the SQL type that is used to map the class id
part of the object id. It defaults to 'INTEGER'.

=item * cid_size

Field C<cid_size> contains the number of decimal positions that the
class id occupies within the object id. It defaults to '4'.  B<This
does not affect the database, only the in-memory representation of
object IDs>.

=item * oid

Historical spurious documentation bug.  Documentation described the
function that the C<id> option performs.

=item * table_type

Field C<table_type> is a string that if set, will be appended to all
CREATE TABLE commands with TYPE=x.  For instance, to use transactions
with a MySQL database with InnoDB enabled, set C<table_type> to
C<InnoDB>, and (re)deploy your database.

=item * dumper

This field sets the default mechanism by which arbitrary structures
are serialised to columns, in the absence of a portion of the Tangram
schema covering their mapping.

The default value is C<Storable> (see L<Storable>), seeing as Storable
is something like the "native" serialisation mechanism for Perl.
Currently, this setting only applies to the B<idbif> mapping type (see
L<Tangram::Type::Dump::Any>).

It would make more sense for the default to be C<YAML>, but
unfortunately YAML doesn't support dumping the entire range of native
Perl data types, which sucks immensely.

=back

The other fields are related to the SQL types that Tangram uses to
store meta-information.

=head2 class registry

The class registry is an array containing one entry per persistent
class.  The array contains a list of C<key =E<gt> value> pairs.
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 can have the following fields:

=over 4

=item * abstract

=item * bases

=item * fields

=item * table

=item * table_type

=item * id

=item * oid_sequence

=item * make_id

=back

Field C<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 C<bases> contains a reference to an array of base classes.

Field C<fields> contains a reference to the L<field hash>.

Field C<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 C<table_type> sets the type of the table, for instance, the
storage back-end to the RDBMS or storage format; it specifies on a
per-table basis what the C<table_type> attribute of the schema
defines.  You almost certainly don't want to set this on a per-table
basis.

Field C<id> contains an integer identifier for this class. That
identifier must be unique within the same schema. If this field
is not present, Tangram sets it to the last class id plus one.

Fields C<oid_sequence> and C<make_id> are per-class versions of their
schema-wide versions documented above.  These should be inherited by
their subclasses, but currently (as of 2.07_06) aren't.  To be safe,
until this documentation is fixed, define them in all subclasses.

=head2 field hash

Each persistent type is identified by a 'typetag', e.g. C<int>, C<string>
or C<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 L<Tangram::Type::Array::FromMany> and L<Tangram::Type::Array::FromOne>).

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 L<Tangram::Type>.

Tangram comes with built-in support for the following types:

* string, int, real: see L<Tangram::Type::Scalar>

* reference : see L<Tangram::Type::Ref::FromMany>

* array : see L<Tangram::Type::Array::FromMany>, L<Tangram::Type::Array::FromOne>

* Set::Object : see L<Tangram::Type::Set::FromMany>, L<Tangram::Type::Set::FromOne>

=head1 INSTANCE METHODS

=head2 deploy

This method is deprecated. See L<Tangram::Relational>.

=head2 retreat

This method is deprecated. See L<Tangram::Relational>.