Provided by: libur-perl_0.410-1_all bug

NAME

       UR::Manual::Cookbook - Recepies for getting things working

Database Changes

   Synchronizing your classes to the database schema
       From under your application's Namespace directory, use the command-line tool

         ur update classes

       This will load all the data sources under the DataSource subdirectory of the Namespace,
       find out what has changed between the last time you ran update classes (possibly never)
       and now, save the current database schema information in the Namespace's MetaDB, and
       update the class definitions for any changed entities.

   Possible conflicts
       Avoid tables called 'type' or 'types'.  It will conflict with the class metadata class
       names where their class names end in '::Type'.  The 'ur update classes' tool will rename
       the class to 'YourNamespace::TypeTable' to avoid the conflict, while keeping the
       table_name the same.

       A table with multiple primary keys should not have one of them called 'id'.  This will
       result in a conflict with the requirement that a class must have have a property called
       'id' that uniquely identifies a member.

Relationships

       Class relationships provide a way to describe how one class links to another.  They are
       added to a class by creating a property that lists how the class' properties relate to
       each other.

       There are two basic kinds of relationships: forward and reverse, Forward relationships are
       used to model the has-a condition, where the primary class holds the ID of the related
       class's instance. Reverse relationships are used when the related class has a property
       pointing back to the primary class.  They are usually used to model a has-many situation
       where the related class holds the ID of which primary class instance it is related to.

   Has-a (One-to-one)
       The container class/table has a foreign key pointing to a contained class/table as in

         table Container
         column          type        constraint
         ----------------------------------------
         container_id    Integer     primary key
         value           Varchar     not null
         contained_id    Integer     references contained(contained_id)

         table Contained
         column          type        constraint
         ----------------------------------------
         contained_id    Integer     primary key
         contained_value Varchar   not null

       Adding a forward relationship involves creating a property where the 'is' is the name of
       the related class, and an 'id_by' indicating which property on the primary class provides
       the foreign key with the related class' ID.

       The class definition for the container would look like this:

         class TheNamespace::Container {
            table_name => 'container',
            id_by => [
                container_id => { is => 'Integer' },
            ],
            has => [
                value => { is => 'Varchar' },
            ],
            has_optional => [
                contained_id => { is => 'Integer' },
                contained => { is => 'TheNamespace::Contained',
                               id_by => 'contained_id' },
            ],
            data_source => 'TheNamespace::DataSource::TheDatabase',
         };

       If there was a NOT NULL constraint on the contained_id column, then the contained_id and
       contained properties should go in the "has" section.

       And now for the contained class. We'll also include a reverse relationship pointing back
       to the container it's a part of.

         class TheNamespace::Contained {
            table_name => 'contained',
            id_by => [
                contained_id => { is => 'Integer' },
            ],
            has => [
                container => { is => 'TheNamespace::Container',
                               reverse_as => 'contained',
                               is_many => 1 },
                contained_value => { is => 'Varchar' },
            ],
            data_source => 'TheNamsapce::DataSource::TheDatabase',
         };

       Note that the reverse_as parameter of the container property actually points to the object
       accessor, not the id accessor. It doesn't make sense, but that's how it is for now.
       Hopefully we'll come up with a better syntax.

   Has-many
       The contained class/table has a foreign key pointing to the container it's a part of.

         table Container
         column          type        constraint
         ------------------------------------------
         container_id    Integer     primary key
         value           Varchar     not null

         table Contained
         column          type        constraint
         ------------------------------------------
         contained_id    Integer     primary key
         contained_value Varchar     not null
         container_id    Integer     references container(container_id)

       To create a reverse relationship, you must first create a forward relationship on the
       related class pointing back to the primary class. Then, creating the reverse relationship
       involves adding a property where the 'is' is the name of the related class, and a
       'reverse_as' indicating which property on the related class describes the forward
       relationship between that related class and the primary class.

         class TheNamespace::Container {
            table_name => 'container',
            id_by => [
                container_id => { is => 'Integer' },
            ],
            has => [
                value => { is => 'Varchar' },
                containeds => { is => 'TheNamespace::Contained',
                                reverse_as => 'container',
                                is_many => 1 },
            ],
            data_source => 'TheNamespace::DataSource::TheDatabase',
         };

         class TheNamespace::Contained {
            table_name => 'contained',
            id_by => [
                contained_id => { is => 'Integer' },
            ],
            has => [
                contained_value => { is => 'Varchar' },
                container_id => { is => 'Integer' },
                container => { is => 'TheNamespace::Container',
                               id_by => 'container_id' },
            ],
            data_source => 'TheNamespace::DataSource::TheDatabase',
         };

   Many-to-many
       Storing a has-many relationship requires a bridge table between the two main entities.

         table Container
         column          type        constraint
         --------------------------------------------
         container_id    Integer     primary key
         value           Varchar     not null

         table Contained
         column          type        constraint
         --------------------------------------------
         contained_id    Integer     primary key
         contained_value Varchar     not null
         container_id    Integer     references container(container_id)

         table Bridge
         column          type        constraint
         --------------------------------------------
         container_id    Integer     references container(container_id)
         contained_id    Integer     references contained(contained_id)
         primary key(container_id,contained_id)

       Here, both the Container and Contained classes have accessors to return a list of all the
       objects satisfying the relationship through the bridge table.

         class TheNamespace::Container {
            id_by => [
                container_id => { is => 'Integer' },
            ],
            has => [
                value => { is => 'Varchar' },
            ],
            has_many => [
                bridges =>    { is => 'TheNamespace::Bridge',
                                reverse_as => 'container' },
                containeds => { is => 'TheNamespace::Contained',
                                via => 'bridge',
                                to => 'contained' },
            ],
            table_name => 'container',
            data_source => 'TheNamespace::DataSource::TheDatabase',
         };

         class TheNamespace::Bridge {
            id_by => [
                container_id => { is => 'Integer' },
                contained_id => { is => 'Integer' },
            ],
            has => [
                container => { is => 'TheNamespace::Container',
                               id_by => 'container_id' },
                contained => { is => 'TheNamespace::Contained',
                               id_by => 'contained_id' },
            ],
            table_name => 'bridge',
            data_source => 'TheNamespace::DataSource::TheDatabase',
         };

         class TheNamespace::Contained {
            id_by => [
                container_id => { is => 'Integer' },
            ],
            has => [
                contained_value => { is => 'Varchar' },
            ],
            has_many => [
                bridges =>    { is => 'TheNamespace::Bridge',
                                reverse_as => 'contained' },
                containers => { is => 'TheNamespace::Container',
                                via => 'bridge',
                                to => 'container' },
            ],
            table_name => 'container',
            data_source => 'TheNamespace::DataSource::TheDatabase',
         };

Indirect Properties

       Indirect properties are used to add a property to a class where the data is actually
       stored in a direct property of a related class.

   Singly-indirect
       As in the has-a relationship, and the container class wants to have a property actually
       stored on the contained class. Using the same schema in the has-a relationship above, and
       we want the contained_value property to be accessible from the container class.

         class TheNamespace::Container {
            id_by => [
                container_id => { is => 'Integer' },
            ],
            has => [
                # This implies a contained_id property, too
                contained       => { is => 'TheNamespace::Contained',
                                     id_by => 'contained_id' },
                contained_value => { via => 'contained',
                                     to => 'contained_value' },
            ],
            table_name => 'container',
            data_source => 'TheNamespace::DataSource::TheDatabase',
         };

       You can now use "contained_value" as an accessor on TheNamespace::Container objects.  You
       can also use "contained_value" as a parameter in "get()", and the underlying data source
       will use a join if possible in the SQL query.

   Many Singly-indirect
       As in the singly-indirect recipe, but the container-contained relationship is has-many

         class Container {
            id_by => [
                container_id => { is => 'Integer' },
            ],
            has => [
                containeds => { is => 'TheNamespace::Contained',
                                reverse_as => 'container',
                                is_many => 1 },
                contained_values => { via => 'containeds',
                                      to => 'container_value',
                                      is_many => 1 },
            ],
            table_name => 'container',
            data_source => 'TheNamespace::DataSource::TheDatabase',
         };

   Doubly-indirect
       If you have a normal has-a relationship between a container and a contained item, and the
       contained item also has-a third-level contained thing, and you'd like to have a property
       of the innermost class available to the first container:

         class Container {
            id_by => [
                container_id => { is => 'Integer' },
            ],
            has => [
                contained       => { is => 'TheNamsepace::Contained',
                                     id_by => 'contained_id '},
                inner_contained => { is => 'TheNamespace::InnerContained,
                                     via => 'contained',
                                     to => 'inner_contained_id' },
                inner_contained_value => { via => 'inner_contained',
                                           to => 'inner_contained_value' },
            ],
            table_name => 'container',
            data_source => 'TheNamespace::DataSource::TheDatabase',
         };

   Many doubly-indirect
       Combining the has-many relationship and the doubly indirect recipe

         class Container {
            id_by => [
                container_id => { is => 'Integer' },
            ],
            has => [
                containeds       => { is => 'TheNamsepace::Contained',
                                      reverse_as => 'container',
                                      is_many => 1},
                inner_containeds => { is => 'TheNamespace::InnerContained,
                                      via => 'contained',
                                      to => 'contained',
                                      is_many => 1 },
                inner_contained_values => { via => 'inner_containeds',
                                            to => 'inner_contained_value',
                                            is_many => 1 },
            ],
            table_name => 'container',
            data_source => 'TheNamespace::DataSource::TheDatabase',
         };

       And then you get an accessor inner_containeds to return a list of inner-contained objects,
       and another accessor inner_contained_values to return a list of their values.