NAME

       Tangram::Type::Extending - teaching Tangram about new types

DESCRIPTION

       Tangram::Type is the root of a hierarchy of classes that are responsible mapping individual field to SQL
       entities (columns in the simplest cases). There is one Type object per persistent field.

       Adding support for new types amounts to adding subclasses to Tangram::Type.

WRITING NEW TYPES

       Tangram is organized in several subsystems, described below.

       Schema is the repository for information about all the persistent aspects of a system: classes,
       inheritance relationships, fields, etc. It also contains graph-traversal algorithms, which are not
       currently documented.

       Storage deals with objects as a whole: insertion, updating, multiple load detection, cycle handling,
       transactions, connections. It also serves as an entry point in the system. Storage does not manipulate
       fields directly.

       Cursor deals with polymorphic retrieval of objects. It builds SELECT statements on the basis of the
       information in the hash. Cursor does not manipulate fields directly either.

       The Type hierarchy deals with individual fields, and not with entire objects. More about it in a moment.

       The Expr hierarchy deals with entities on the remote side; this includes expressions proper, Filters and
       Remotes.

       Types are responsible for performing the mapping between a field of a given Perl type and a relational
       entity. The simplest Types merely transfer between one Perl field and one column. Sometimes it makes
       sense to have several mappings (and hence several Types) for the same Perl type; for example, Perl arrays
       can be mapped either using a link table, or one or several columns that live on the element's table.

       Users don't deal with Type objects directly: they indicate that a series of fields should be mapped in a
       certain way by putting the fields under a given 'typetag' in the field hash. The type registers itself
       with Tangram by adding a typetag in the %Tangram::Schema::TYPES hash. The value is the Type object. Up to
       now all Types have been singletons, but this is not a rule.

       Anybody who's planning to write new Types should examine Scalar.pm first. It contains very simple
       mappings between one field and one column.

       A Type must implement the methods described below. Keep the following facts in mind while reading
       further:

       1. A Type is responsible for transferring all the *direct* fields for a given *class*. This excludes
       inherited fields. OTOH, the same Type can be called more than once for the same object, because the same
       Type may be used in several classes that appear in a particular object's inheritance graph.

INSTANCE METHODS

   reschema
          reschema($self, $members, $class)

       This method is called when the schema hash is being converted into a Schema object. The Type finds all
       the fields it is responsible for mapping in the Perl structure refered by $members. The Type decides the
       exact format of this structure.

   get_export_cols
               get_export_cols($self, $context)

       Called when building INSERT and UPDATE statements; the Type returns a list of columns to be inserted in
       the statement.

   get_exporter
               get_exporter($self, $context)

       Called when building a function for reading the state of an object: the Type may return either a string
       or a closure.

   get_import_cols
               get_import_cols($self, $context)

       Called when building SELECT statements; the Type returns a list of columns to be inserted in the
       statement.

   get_importer
               get_importer($self, $context)

       Called when building a function for setting the state of an object: the Type may return either a string
       or a closure.

   remote_expr
               remote_expr($self, $obj, $tid, $storage)

       Called when building a Remote. The Type returns an Expr object.

HANDLING ASSOCIATIONS

       Ref and Collections have in common that they don't load their controlled fields upfront. Their importer
       method ties the controlled fields to a package that will demand-load the final value of the field - if
       it's ever needed. The exact procedure for achieving this is not imposed by Tangram itself, in fact, a
       Type has the liberty of doing just anything it sees fit, if it can manage it with the arguments that it
       gets passed by the higher layer. Ref ties a field to the Lazy::Ref package, and Collections tie to
       Lazy::Coll.

       Ref and those collections that contain references to other objects must deal cycles. This can be done
       quite easily but I don't have to go into those details right now.

       Collections (of references of or values (the so-called 'flat' collections)) typically save their state
       when the demand-load is triggered. Later, when the collection is saved, the Collection compares the
       current field state (iow collection content) with the state at load time, and updates the database
       accordingly.

       Types that need to remember field state at load time should store it under
       $storage->{scratch}{TYPE_CLASS}, and typically under $storage->{scratch}{TYPE_CLASS}{OBJECT_ID}{FIELD}.
       Coll defines two utility functions to help manage load-time state:

       * set_load_state($self, $storage, $obj, $field, $state)

       Remember $state of the $field of $obj, retrieved from $storage.

       * get_load_state($self, $storage, $obj, $member)

       Retrieve that state.