/usr/share/perl5/UR/Manual/Cookbook.pod is in libur-perl 0.440-1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 | =pod
=head1 NAME
UR::Manual::Cookbook - Recepies for getting things working
=head1 Database Changes
=head2 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.
=head2 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.
=head1 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.
=head2 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.
=head2 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',
};
=head2 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',
};
=head1 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.
=head2 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 C<contained_value> as an accessor on TheNamespace::Container
objects. You can also use C<contained_value> as a parameter in C<get()>,
and the underlying data source will use a join if possible in the SQL query.
=head2 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',
};
=head2 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',
};
=head2 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.
|