.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "UR::Manual::Cookbook 3pm"
.TH UR::Manual::Cookbook 3pm "2014-07-04" "perl v5.18.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
UR::Manual::Cookbook \- Recepies for getting things working
.SH "Database Changes"
.IX Header "Database Changes"
.SS "Synchronizing your classes to the database schema"
.IX Subsection "Synchronizing your classes to the database schema"
From under your application's Namespace directory, use the command-line tool
.PP
.Vb 1
\&  ur update classes
.Ve
.PP
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.
.SS "Possible conflicts"
.IX Subsection "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.
.PP
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.
.SH "Relationships"
.IX Header "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.
.PP
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 \s-1ID\s0 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 \s-1ID\s0 of which primary class instance it is related to.
.SS "Has-a (One-to-one)"
.IX Subsection "Has-a (One-to-one)"
The container class/table has a foreign key pointing to a contained class/table as in
.PP
.Vb 6
\&  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
.Ve
.PP
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' \s-1ID. \s0
.PP
The class definition for the container would look like this:
.PP
.Vb 10
\&  class TheNamespace::Container {
\&     table_name => \*(Aqcontainer\*(Aq,
\&     id_by => [
\&         container_id => { is => \*(AqInteger\*(Aq },
\&     ],
\&     has => [ 
\&         value => { is => \*(AqVarchar\*(Aq },
\&     ],
\&     has_optional => [
\&         contained_id => { is => \*(AqInteger\*(Aq },
\&         contained => { is => \*(AqTheNamespace::Contained\*(Aq,
\&                        id_by => \*(Aqcontained_id\*(Aq },
\&     ],
\&     data_source => \*(AqTheNamespace::DataSource::TheDatabase\*(Aq,
\&  };
.Ve
.PP
If there was a \s-1NOT NULL\s0 constraint on the contained_id column, then the
contained_id and contained properties should go in the \*(L"has\*(R" section.
.PP
And now for the contained class. We'll also include a reverse relationship
pointing back to the container it's a part of.
.PP
.Vb 10
\&  class TheNamespace::Contained {
\&     table_name => \*(Aqcontained\*(Aq,
\&     id_by => [
\&         contained_id => { is => \*(AqInteger\*(Aq },
\&     ],
\&     has => [
\&         container => { is => \*(AqTheNamespace::Container\*(Aq,
\&                        reverse_as => \*(Aqcontained\*(Aq,
\&                        is_many => 1 },
\&         contained_value => { is => \*(AqVarchar\*(Aq },
\&     ],
\&     data_source => \*(AqTheNamsapce::DataSource::TheDatabase\*(Aq,
\&  };
.Ve
.PP
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.
.SS "Has-many"
.IX Subsection "Has-many"
The contained class/table has a foreign key pointing to the container it's a part of.
.PP
.Vb 5
\&  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)
.Ve
.PP
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.
.PP
.Vb 10
\&  class TheNamespace::Container {
\&     table_name => \*(Aqcontainer\*(Aq,
\&     id_by => [
\&         container_id => { is => \*(AqInteger\*(Aq },
\&     ],
\&     has => [
\&         value => { is => \*(AqVarchar\*(Aq },
\&         containeds => { is => \*(AqTheNamespace::Contained\*(Aq,
\&                         reverse_as => \*(Aqcontainer\*(Aq,
\&                         is_many => 1 },
\&     ],
\&     data_source => \*(AqTheNamespace::DataSource::TheDatabase\*(Aq,
\&  };
\&  
\&  class TheNamespace::Contained {
\&     table_name => \*(Aqcontained\*(Aq,
\&     id_by => [
\&         contained_id => { is => \*(AqInteger\*(Aq },
\&     ],
\&     has => [
\&         contained_value => { is => \*(AqVarchar\*(Aq },
\&         container_id => { is => \*(AqInteger\*(Aq },
\&         container => { is => \*(AqTheNamespace::Container\*(Aq,
\&                        id_by => \*(Aqcontainer_id\*(Aq },
\&     ],
\&     data_source => \*(AqTheNamespace::DataSource::TheDatabase\*(Aq,
\&  };
.Ve
.SS "Many-to-many"
.IX Subsection "Many-to-many"
Storing a has-many relationship requires a bridge table between the two main entities.
.PP
.Vb 5
\&  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)
.Ve
.PP
Here, both the Container and Contained classes have accessors to return a
list of all the objects satisfying the relationship through the bridge table.
.PP
.Vb 10
\&  class TheNamespace::Container {
\&     id_by => [
\&         container_id => { is => \*(AqInteger\*(Aq },
\&     ],
\&     has => [
\&         value => { is => \*(AqVarchar\*(Aq },
\&     ],
\&     has_many => [
\&         bridges =>    { is => \*(AqTheNamespace::Bridge\*(Aq,
\&                         reverse_as => \*(Aqcontainer\*(Aq },
\&         containeds => { is => \*(AqTheNamespace::Contained\*(Aq,
\&                         via => \*(Aqbridge\*(Aq,
\&                         to => \*(Aqcontained\*(Aq },
\&     ],
\&     table_name => \*(Aqcontainer\*(Aq,
\&     data_source => \*(AqTheNamespace::DataSource::TheDatabase\*(Aq,
\&  };
\&  
\&  class TheNamespace::Bridge {
\&     id_by => [
\&         container_id => { is => \*(AqInteger\*(Aq },
\&         contained_id => { is => \*(AqInteger\*(Aq },
\&     ],
\&     has => [
\&         container => { is => \*(AqTheNamespace::Container\*(Aq,
\&                        id_by => \*(Aqcontainer_id\*(Aq },
\&         contained => { is => \*(AqTheNamespace::Contained\*(Aq,
\&                        id_by => \*(Aqcontained_id\*(Aq },
\&     ],
\&     table_name => \*(Aqbridge\*(Aq,
\&     data_source => \*(AqTheNamespace::DataSource::TheDatabase\*(Aq,
\&  };
\&  
\&  class TheNamespace::Contained {
\&     id_by => [
\&         container_id => { is => \*(AqInteger\*(Aq },
\&     ],
\&     has => [
\&         contained_value => { is => \*(AqVarchar\*(Aq },
\&     ],
\&     has_many => [
\&         bridges =>    { is => \*(AqTheNamespace::Bridge\*(Aq,
\&                         reverse_as => \*(Aqcontained\*(Aq },
\&         containers => { is => \*(AqTheNamespace::Container\*(Aq,
\&                         via => \*(Aqbridge\*(Aq,
\&                         to => \*(Aqcontainer\*(Aq },
\&     ],
\&     table_name => \*(Aqcontainer\*(Aq,
\&     data_source => \*(AqTheNamespace::DataSource::TheDatabase\*(Aq,
\&  };
.Ve
.SH "Indirect Properties"
.IX Header "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.
.SS "Singly-indirect"
.IX Subsection "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.
.PP
.Vb 10
\&  class TheNamespace::Container {
\&     id_by => [
\&         container_id => { is => \*(AqInteger\*(Aq },
\&     ],
\&     has => [
\&         # This implies a contained_id property, too
\&         contained       => { is => \*(AqTheNamespace::Contained\*(Aq,
\&                              id_by => \*(Aqcontained_id\*(Aq },
\&         contained_value => { via => \*(Aqcontained\*(Aq,
\&                              to => \*(Aqcontained_value\*(Aq },
\&     ],
\&     table_name => \*(Aqcontainer\*(Aq,
\&     data_source => \*(AqTheNamespace::DataSource::TheDatabase\*(Aq,
\&  };
.Ve
.PP
You can now use \f(CW\*(C`contained_value\*(C'\fR as an accessor on TheNamespace::Container
objects.  You can also use \f(CW\*(C`contained_value\*(C'\fR as a parameter in \f(CW\*(C`get()\*(C'\fR,
and the underlying data source will use a join if possible in the \s-1SQL\s0 query.
.SS "Many Singly-indirect"
.IX Subsection "Many Singly-indirect"
As in the singly-indirect recipe, but the container-contained relationship
is has-many
.PP
.Vb 10
\&  class Container {
\&     id_by => [
\&         container_id => { is => \*(AqInteger\*(Aq },
\&     ],
\&     has => [
\&         containeds => { is => \*(AqTheNamespace::Contained\*(Aq,
\&                         reverse_as => \*(Aqcontainer\*(Aq,
\&                         is_many => 1 },
\&         contained_values => { via => \*(Aqcontaineds\*(Aq,
\&                               to => \*(Aqcontainer_value\*(Aq,
\&                               is_many => 1 },
\&     ],
\&     table_name => \*(Aqcontainer\*(Aq,
\&     data_source => \*(AqTheNamespace::DataSource::TheDatabase\*(Aq,
\&  };
.Ve
.SS "Doubly-indirect"
.IX Subsection "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:
.PP
.Vb 10
\&  class Container {
\&     id_by => [
\&         container_id => { is => \*(AqInteger\*(Aq },
\&     ],
\&     has => [
\&         contained       => { is => \*(AqTheNamsepace::Contained\*(Aq,
\&                              id_by => \*(Aqcontained_id \*(Aq},
\&         inner_contained => { is => \*(AqTheNamespace::InnerContained,
\&                              via => \*(Aqcontained\*(Aq,
\&                              to => \*(Aqinner_contained_id\*(Aq },
\&         inner_contained_value => { via => \*(Aqinner_contained\*(Aq,
\&                                    to => \*(Aqinner_contained_value\*(Aq },
\&     ],
\&     table_name => \*(Aqcontainer\*(Aq,
\&     data_source => \*(AqTheNamespace::DataSource::TheDatabase\*(Aq,
\&  };
.Ve
.SS "Many doubly-indirect"
.IX Subsection "Many doubly-indirect"
Combining the has-many relationship and the doubly indirect recipe
.PP
.Vb 10
\&  class Container {
\&     id_by => [
\&         container_id => { is => \*(AqInteger\*(Aq },
\&     ],
\&     has => [
\&         containeds       => { is => \*(AqTheNamsepace::Contained\*(Aq,
\&                               reverse_as => \*(Aqcontainer\*(Aq,
\&                               is_many => 1},
\&         inner_containeds => { is => \*(AqTheNamespace::InnerContained,
\&                               via => \*(Aqcontained\*(Aq,
\&                               to => \*(Aqcontained\*(Aq,
\&                               is_many => 1 },
\&         inner_contained_values => { via => \*(Aqinner_containeds\*(Aq,
\&                                     to => \*(Aqinner_contained_value\*(Aq,
\&                                     is_many => 1 },
\&     ],
\&     table_name => \*(Aqcontainer\*(Aq,
\&     data_source => \*(AqTheNamespace::DataSource::TheDatabase\*(Aq,
\&  };
.Ve
.PP
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.