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.