NAME

DESCRIPTION

NOMENCLATURE

This makes it difficult to describe a meta-model which has components, or meta-components, which themselves are really just ordinary Perl objects.

Thus we could end up talking about instances of the Oryx::Value::String class being associated with an instance of the Oryx::Attribute class when mentioning how they relate to our persistant objects - which are themselves Oryx::Class derived instances. All of which can be tricky for the brain (well mine, at any rate) to keep a grip on.

So to make this slightly more coherent, we'll stick to the following nomenclature throughout this document:

class

When we say "class" we mean a subclass of "Oryx::Class" which you can instantiate into "objects" which are persistable in some storage backend - usually a database of sorts.

object

When we refer to "objects" we mean our persistent objects - that is, instances of subclasses of Oryx::Class which we're interested in storing in our database.

meta-type

We'll use "meta-type" when talking about meta classes of which Oryx::Attribute and Oryx::Association are two examples (not to be confused with instances of these described under meta-instances below).

meta-instance

These are actually objects themselves (but not of the kind described above under "object") and are considered meta data of the "class" in that they hold descriptive information about the "classes". Examples are instances of Oryx::Attribute and Oryx::Association.

meta-attribute

When we say: "meta-attribute", what we mean varies. To explain: two methods are available for accessing these and are inherited by all meta-types from Oryx::MetaClass. The methods are "getMetaAttribute" and "setMetaAttribute". Exactly what these access depends on the context, that is to say, the term "meta" here is relative to the meta-type on which the method is called. So if we say:

    CMS::Page->attributes->{number}->getMetaAttribute('type');
    

We will get a string representing the type of the value which may be stored in this field of the object, most likely an 'Integer' in this case. On the other hand, if we say:

    CMS::Page->association->{paragraphs}->getMetaAttribute('class');
    

We will get the name of the target class of the 'paragraphs' association, probably "CMS::Paragraph" in this case, which is a class name - in fact a subclass of Oryx::Class - which is not an Oryx meta-type, but in this context, it is meta-data which this association needs in order to perform its duty.

ABSTRACT METAMODEL

This abstract metamodel consist of four base meta-types namely: Oryx::Attribute, Oryx::Association, Oryx::Parent and Oryx::Class. Oryx::Class can be regarded as a special case meta-type in that it is the level at which our meta-model joins Perl's own built-in object model.

When a persistent class inherits from Oryx::Class, it doesn't have the implementation to be persisted in any given storage back-end, that is, the methods for creating, retrieving, updating, etc. are just stubs and will raise an exception if invoked. During a call to "Oryx->connect(...)", however, Oryx looks at the connection arguments and determines which concrete meta-types will be used thereafter. This is done by simply pushing either Class::DBI::Class or Class::DBM::Class onto @Oryx::Class::ISA, thereby effectively doing dynamic, run-time inheritance. So for example, if we say:

    use Oryx;
    use CMS::Page;
     
    UNIVERSAL::isa(CMS::Page, 'Oryx::Class')            # true
    UNIVERSAL::isa(CMS::Page, 'Oryx::DBI::Class')       # false
     
    Oryx->connect('dbi:Pg:dbnam=foo', $user, $pass);
    
    UNIVERSAL::isa(CMS::Page, 'Oryx::DBI::Class')       # true

whereas if we:

    Oryx->connect('dbm:Deep:datapath=/path/to/data');
    
    UNIVERSAL::isa(CMS::Page, 'Oryx::DBM::Class')       # true

From this point onwards, the correct concrete meta-types are used and constructed from the class metadata defined in the class' $schema. This happens in the class's "import" hook, but is usually deferred to happen at run-time (instead of compile-time); so in the first case above this would be Oryx::DBI::Association, Oryx::DBI::Attribute and Oryx::DBI::Parent. The actual "connect()" call is then delegated to the appropriate storage class: Oryx::DBI or Oryx::DBM, as the case may be. These storage classes handle low level connection, pinging the DB and caching database handles (indirectly via Ima::DBI) where applicable.

Each Oryx::Class derivative (or subclass) has any number of instances of the concrete meta-types associated with it. At the Oryx::Class level, this is done with inheritable class data using Class::Data::Inheritable (of all things!) for creating accessors (or "named closures"), typically by inspecting the $schema class variable, or, in the case of Oryx::Parent meta-instances, by inspecting the class' @ISA array.

From our class, we can access the meta-instances as folows:

    @attribs = values %{CMS::Page->attributes};            # all the attributes
    $assoc  = CMS::Page->associations->{paragraphs};       # single association

Oryx::Parent meta-instances are stored in an array ref, so this access looks a little different:

    @parents = @{CMS::Page->parents};      # all parents

Alternatively you can get all the meta-instances as an array using the convenient "members" method:

    @members = CMS::Page->members;

This will then contain a list of all the meta-instances describing our "CMS::Page" class.

NOTE: The meta-instances are constructed using "import", so they'll be there after you "use" the class, but not if you just "require" it.

COMMON INTERFACE

  sub create {
      # take some action to create the record
      $_->create(...) foreach $class->members;
      # finish up, store the data, return
  }

create

This method is called to create a new record in storage.

retrieve

This method is called to fetch an object from storage by the object's identifier.

update

After making changes to the object, this method records those changes to storage.

delete

This method deletes the object. The object is invalid after this method is called and should not be referred to anymore.

search

This method is responsible for searching by field and returning an array of matching objects.

construct

When searching and retrieving, both instantiate each instance returned using this method.

Each delegated class has a chance to modify the object as necessary during each of these calls.

CLASSES

Each of the following headings describe each group of classes used by Oryx.

ACKNOLWEDGEMENTS

AUTHOR

LICENSE