Provided by: libur-perl_0.470+ds-2_all 
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.