NAME¶
Rose::DB::Object::MakeMethods::Generic - Create generic object methods for
Rose::DB::Object-derived objects.
SYNOPSIS¶
package MyDBObject;
our @ISA = qw(Rose::DB::Object);
use Rose::DB::Object::MakeMethods::Generic
(
scalar =>
[
'type' =>
{
with_init => 1,
check_in => [ qw(AA AAA C D) ],
},
'set_type' => { hash_key => 'type' },
],
character =>
[
code => { length => 6 }
],
varchar =>
[
name => { length => 10 }
],
boolean =>
[
'is_red',
'is_happy' => { default => 1 },
],
);
sub init_type { 'C' }
...
$obj = MyDBObject->new(...);
print $obj->type; # C
$obj->name('Bob'); # set
$obj->set_type('C'); # set
$obj->type('AA'); # set
$obj->set_type; # Fatal error: no argument passed to "set" method
$obj->name('C' x 40); # truncate on set
print $obj->name; # 'CCCCCCCCCC'
$obj->code('ABC'); # pad on set
print $obj->code; # 'ABC '
eval { $obj->type('foo') }; # fatal error: invalid value
print $obj->name, ' is ', $obj->type; # get
$obj->is_red; # returns undef
$obj->is_red('true'); # returns 1 (assuming "true" a
# valid boolean literal according to
# $obj->db->parse_boolean('true'))
$obj->is_red(''); # returns 0
$obj->is_red; # returns 0
$obj->is_happy; # returns 1
...
package Person;
our @ISA = qw(Rose::DB::Object);
...
use Rose::DB::Object::MakeMethods::Generic
(
scalar => 'name',
set =>
[
'nicknames',
'parts' => { default => [ qw(arms legs) ] },
],
# See the Rose::DB::Object::Metadata::Relationship::ManyToMany
# documentation for a more complete example
objects_by_map =>
[
friends =>
{
map_class => 'FriendMap',
manager_args => { sort_by => Friend->meta->table . '.name' },
},
],
);
...
@parts = $person->parts; # ('arms', 'legs')
$parts = $person->parts; # [ 'arms', 'legs' ]
$person->nicknames('Jack', 'Gimpy'); # set with list
$person->nicknames([ 'Slim', 'Gip' ]); # set with array ref
print join(', ', map { $_->name } $person->friends);
...
package Program;
our @ISA = qw(Rose::DB::Object);
...
use Rose::DB::Object::MakeMethods::Generic
(
objects_by_key =>
[
bugs =>
{
class => 'Bug',
key_columns =>
{
# Map Program column names to Bug column names
id => 'program_id',
version => 'version',
},
manager_args =>
{
sort_by => Bug->meta->table . '.date_submitted DESC',
},
query_args => [ state => { ne => 'closed' } ],
},
]
);
...
$prog = Program->new(id => 5, version => '3.0', ...);
$bugs = $prog->bugs;
# Calls (essentially):
#
# Rose::DB::Object::Manager->get_objects(
# db => $prog->db, # share_db defaults to true
# object_class => 'Bug',
# query =>
# {
# program_id => 5, # value of $prog->id
# version => '3.0', # value of $prog->version
# state => { ne => 'closed' },
# },
# sort_by => 'date_submitted DESC');
...
package Product;
our @ISA = qw(Rose::DB::Object);
...
use Rose::DB::Object::MakeMethods::Generic
(
object_by_key =>
[
category =>
{
class => 'Category',
key_columns =>
{
# Map Product column names to Category column names
category_id => 'id',
},
},
]
);
...
$product = Product->new(id => 5, category_id => 99);
$category = $product->category;
# $product->category call is roughly equivalent to:
#
# $cat = Category->new(id => $product->category_id,
# db => $prog->db);
#
# $ret = $cat->load;
# return $ret unless($ret);
# return $cat;
DESCRIPTION¶
Rose::DB::Object::MakeMethods::Generic is a method maker that inherits from
Rose::Object::MakeMethods. See the Rose::Object::MakeMethods documentation to
learn about the interface. The method types provided by this module are
described below.
All method types defined by this module are designed to work with objects that
are subclasses of (or otherwise conform to the interface of) Rose::DB::Object.
In particular, the object is expected to have a db method that returns a
Rose::DB-derived object. See the Rose::DB::Object documentation for more
details.
METHODS TYPES¶
- array
- Create get/set methods for "array" attributes. A
"array" column in a database table contains an ordered list of
values. Not all databases support an "array" column type. Check
the Rose::DB documentation for your database type.
- Options
- default VALUE
- Determines the default value of the attribute. The value
should be a reference to an array.
- hash_key NAME
- The key inside the hash-based object to use for the storage
of this attribute. Defaults to the name of the method.
- interface NAME
- Choose the interface. The default is
"get_set".
- Interfaces
- get_set
- Creates a get/set method for a "array" object
attribute. A "array" column in a database table contains an
ordered list of values.
When setting the attribute, the value is passed through the parse_array
method of the object's db attribute.
When saving to the database, if the attribute value is defined, the method
will pass the attribute value through the format_array method of the
object's db attribute before returning it.
When not saving to the database, the method returns the array as a list in
list context, or as a reference to the array in scalar context.
- get
- Creates an accessor method for a "array" object
attribute. A "array" column in a database table contains an
ordered list of values.
When saving to the database, if the attribute value is defined, the method
will pass the attribute value through the format_array method of the
object's db attribute before returning it.
When not saving to the database, the method returns the array as a list in
list context, or as a reference to the array in scalar context.
- set
- Creates a mutator method for a "array" object
attribute. A "array" column in a database table contains an
ordered list of values.
When setting the attribute, the value is passed through the parse_array
method of the object's db attribute.
When saving to the database, if the attribute value is defined, the method
will pass the attribute value through the format_array method of the
object's db attribute before returning it.
When not saving to the database, the method returns the array as a list in
list context, or as a reference to the array in scalar context.
If called with no arguments, a fatal error will occur.
Example:
package Person;
our @ISA = qw(Rose::DB::Object);
...
use Rose::DB::Object::MakeMethods::Generic
(
array =>
[
'nicknames',
set_nicks => { interface => 'set', hash_key => 'nicknames' },
parts => { default => [ qw(arms legs) ] },
],
);
...
@parts = $person->parts; # ('arms', 'legs')
$parts = $person->parts; # [ 'arms', 'legs' ]
$person->nicknames('Jack', 'Gimpy'); # set with list
$person->nicknames([ 'Slim', 'Gip' ]); # set with array ref
$person->set_nicks('Jack', 'Gimpy'); # set with list
$person->set_nicks([ 'Slim', 'Gip' ]); # set with array ref
- bitfield
- Create get/set methods for bitfield attributes.
- Options
- default VALUE
- Determines the default value of the attribute.
- hash_key NAME
- The key inside the hash-based object to use for the storage
of this attribute. Defaults to the name of the method.
- interface NAME
- Choose the interface. The default is
"get_set".
- intersects NAME
- Set the name of the "intersects" method. (See
"with_intersects" below.) Defaults to the bitfield attribute
method name with "_intersects" appended.
- bits INT
- The number of bits in the bitfield. Defaults to 32.
- with_intersects BOOL
- This option is only applicable with the "get_set"
interface.
If true, create an "intersects" helper method in addition to the
"get_set" method. The intersection method name will be the
attribute method name with "_intersects" appended, or the value
of the "intersects" option, if it is passed.
The "intersects" method will return true if there is any
intersection between its arguments and the value of the bitfield attribute
(i.e., if Bit::Vector's Intersection method returns a value greater than
zero), false (but defined) otherwise. Its argument is passed through the
parse_bitfield method of the object's db attribute before being tested for
intersection. Returns undef if the bitfield is not defined.
- Interfaces
- get_set
- Creates a get/set method for a bitfield attribute. When
setting the attribute, the value is passed through the parse_bitfield
method of the object's db attribute before being assigned.
When saving to the database, the method will pass the attribute value
through the format_bitfield method of the object's db attribute before
returning it. Otherwise, the value is returned as-is.
- get
- Creates an accessor method for a bitfield attribute. When
saving to the database, the method will pass the attribute value through
the format_bitfield method of the object's db attribute before returning
it. Otherwise, the value is returned as-is.
- set
- Creates a mutator method for a bitfield attribute. When
setting the attribute, the value is passed through the parse_bitfield
method of the object's db attribute before being assigned.
When saving to the database, the method will pass the attribute value
through the format_bitfield method of the object's db attribute before
returning it. Otherwise, the value is returned as-is.
If called with no arguments, a fatal error will occur.
Example:
package MyDBObject;
our @ISA = qw(Rose::DB::Object);
use Rose::DB::Object::MakeMethods::Generic
(
bitfield =>
[
'flags' => { size => 32, default => 2 },
'bits' => { size => 16, with_intersects => 1 },
],
);
...
print $o->flags->to_Bin; # 00000000000000000000000000000010
$o->bits('101');
$o->bits_intersects('100'); # true
$o->bits_intersects('010'); # false
- boolean
- Create get/set methods for boolean attributes.
- Options
- default VALUE
- Determines the default value of the attribute.
- hash_key NAME
- The key inside the hash-based object to use for the storage
of this attribute. Defaults to the name of the method.
- interface NAME
- Choose the interface. The default is
"get_set".
- Interfaces
- get_set
- Creates a get/set method for a boolean attribute. When
setting the attribute, if the value is "true" according to
Perl's rules, it is compared to a list of "common" true and
false values: 1, 0, 1.0 (with any number of zeros), 0.0 (with any number
of zeros), t, true, f, false, yes, no. (All are case-insensitive.) If the
value matches, then it is set to true (1) or false (0) accordingly.
If the value does not match any of those, then it is passed through the
parse_boolean method of the object's db attribute. If parse_boolean
returns true (1) or false (0), then the attribute is set accordingly. If
parse_boolean returns undef, a fatal error will occur. If the value is
"false" according to Perl's rules, the attribute is set to zero
(0).
When saving to the database, the method will pass the attribute value
through the format_boolean method of the object's db attribute before
returning it. Otherwise, the value is returned as-is.
- get
- Creates an accessor method for a boolean attribute. When
saving to the database, the method will pass the attribute value through
the format_boolean method of the object's db attribute before returning
it. Otherwise, the value is returned as-is.
- set
- Creates a mutator method for a boolean attribute. When
setting the attribute, if the value is "true" according to
Perl's rules, it is compared to a list of "common" true and
false values: 1, 0, 1.0 (with any number of zeros), 0.0 (with any number
of zeros), t, true, f, false, yes, no. (All are case-insensitive.) If the
value matches, then it is set to true (1) or false (0) accordingly.
If the value does not match any of those, then it is passed through the
parse_boolean method of the object's db attribute. If parse_boolean
returns true (1) or false (0), then the attribute is set accordingly. If
parse_boolean returns undef, a fatal error will occur. If the value is
"false" according to Perl's rules, the attribute is set to zero
(0).
If called with no arguments, a fatal error will occur.
Example:
package MyDBObject;
our @ISA = qw(Rose::DB::Object);
use Rose::DB::Object::MakeMethods::Generic
(
boolean =>
[
'is_red',
'is_happy' => { default => 1 },
'set_happy' => { interface => 'set', hash_key => 'is_happy' },
],
);
$obj->is_red; # returns undef
$obj->is_red('true'); # returns 1 (assuming "true" a
# valid boolean literal according to
# $obj->db->parse_boolean('true'))
$obj->is_red(''); # returns 0
$obj->is_red; # returns 0
$obj->is_happy; # returns 1
$obj->set_happy(0); # returns 0
$obj->is_happy; # returns 0
- character
- Create get/set methods for fixed-length character string
attributes.
- Options
- check_in ARRAYREF
- A reference to an array of valid values. When setting the
attribute, if the new value is not equal (string comparison) to one of the
valid values, a fatal error will occur.
- default VALUE
- Determines the default value of the attribute.
- hash_key NAME
- The key inside the hash-based object to use for the storage
of this attribute. Defaults to the name of the method.
- init_method NAME
- The name of the method to call when initializing the value
of an undefined attribute. Defaults to the method name with the prefix
"init_" added. This option implies "with_init".
- interface NAME
- Choose the interface. The default is
"get_set".
- length INT
- The number of characters in the string. Any strings shorter
than this will be padded with spaces to meet the length requirement. If
length is omitted, the string will be left unmodified.
- overflow BEHAVIOR
- Determines the behavior when the value is greater than the
number of characters specified by the "length" option. Valid
values for BEHAVIOR are:
- fatal
- Throw an exception.
- truncate
- Truncate the value to the correct length.
- warn
- Print a warning message.
- with_init BOOL
- Modifies the behavior of the "get_set" and
"get" interfaces. If the attribute is undefined, the method
specified by the "init_method" option is called and the
attribute is set to the return value of that method.
- Interfaces
- get_set
- Creates a get/set method for a fixed-length character
string attribute. When setting, any strings longer than "length"
will be truncated, and any strings shorter will be padded with spaces to
meet the length requirement. If "length" is omitted, the string
will be left unmodified.
- get
- Creates an accessor method for a fixed-length character
string attribute.
- set
- Creates a mutator method for a fixed-length character
string attribute. Any strings longer than "length" will be
truncated, and any strings shorter will be padded with spaces to meet the
length requirement. If "length" is omitted, the string will be
left unmodified.
Example:
package MyDBObject;
our @ISA = qw(Rose::DB::Object);
use Rose::DB::Object::MakeMethods::Generic
(
character =>
[
'name' => { length => 3 },
],
);
...
$o->name('John'); # truncates on set
print $o->name; # 'Joh'
$o->name('A'); # pads on set
print $o->name; # 'A '
- enum
- Create get/set methods for enum attributes.
- Options
- default VALUE
- Determines the default value of the attribute.
- values ARRAYREF
- A reference to an array of the enum values. This attribute
is required. When setting the attribute, if the new value is not equal
(string comparison) to one of the enum values, a fatal error will
occur.
- hash_key NAME
- The key inside the hash-based object to use for the storage
of this attribute. Defaults to the name of the method.
- init_method NAME
- The name of the method to call when initializing the value
of an undefined attribute. Defaults to the method name with the prefix
"init_" added. This option implies "with_init".
- interface NAME
- Choose the interface. The "get_set" interface is
the default.
- with_init BOOL
- Modifies the behavior of the "get_set" and
"get" interfaces. If the attribute is undefined, the method
specified by the "init_method" option is called and the
attribute is set to the return value of that method.
- Interfaces
- get_set
- Creates a get/set method for an enum attribute. When called
with an argument, the value of the attribute is set. If the value is
invalid, a fatal error will occur. The current value of the attribute is
returned.
- get
- Creates an accessor method for an object attribute that
returns the current value of the attribute.
- set
- Creates a mutator method for an object attribute. When
called with an argument, the value of the attribute is set. If the value
is invalid, a fatal error will occur. If called with no arguments, a fatal
error will occur.
Example:
package MyDBObject;
our @ISA = qw(Rose::DB::Object);
use Rose::DB::Object::MakeMethods::Generic
(
enum =>
[
type => { values => [ qw(main aux extra) ], default => 'aux' },
stage => { values => [ qw(new std old) ], with_init => 1 },
],
);
sub init_stage { 'new' }
...
$o = MyDBObject->new(...);
print $o->type; # aux
print $o->stage; # new
$o->type('aux'); # set
$o->stage('old'); # set
eval { $o->type('foo') }; # fatal error: invalid value
print $o->type, ' is at stage ', $o->stage; # get
- integer
- Create get/set methods for integer attributes.
- Options
- default VALUE
- Determines the default value of the attribute.
- hash_key NAME
- The key inside the hash-based object to use for the storage
of this attribute. Defaults to the name of the method.
- init_method NAME
- The name of the method to call when initializing the value
of an undefined attribute. Defaults to the method name with the prefix
"init_" added. This option implies "with_init".
- interface NAME
- Choose the interface. The "get_set" interface is
the default.
- with_init BOOL
- Modifies the behavior of the "get_set" and
"get" interfaces. If the attribute is undefined, the method
specified by the "init_method" option is called and the
attribute is set to the return value of that method.
- Interfaces
- get_set
- Creates a get/set method for an integer object attribute.
When called with an argument, the value of the attribute is set. The
current value of the attribute is returned.
- get
- Creates an accessor method for an integer object attribute
that returns the current value of the attribute.
- set
- Creates a mutator method for an integer object attribute.
When called with an argument, the value of the attribute is set. If called
with no arguments, a fatal error will occur.
Example:
package MyDBObject;
our @ISA = qw(Rose::DB::Object);
use Rose::DB::Object::MakeMethods::Generic
(
integer =>
[
code => { default => 99 },
type => { with_init => 1 }
],
);
sub init_type { 123 }
...
$o = MyDBObject->new(...);
print $o->code; # 99
print $o->type; # 123
$o->code(8675309); # set
$o->type(42); # set
- objects_by_key
- Create get/set methods for an array of
Rose::DB::Object-derived objects fetched based on a key formed from
attributes of the current object.
- Options
- class CLASS
- The name of the Rose::DB::Object-derived class of the
objects to be fetched. This option is required.
- hash_key NAME
- The key inside the hash-based object to use for the storage
of the fetched objects. Defaults to the name of the method.
- key_columns HASHREF
- A reference to a hash that maps column names in the current
object to those in the objects to be fetched. This option is
required.
- manager_args HASHREF
- A reference to a hash of arguments passed to the
"manager_class" when fetching objects. If
"manager_class" defaults to Rose::DB::Object::Manager, the
following argument is added to the "manager_args" hash:
"object_class => CLASS", where CLASS is the value of the
"class" option (see above). If "manager_args" includes
a "sort_by" argument, be sure to prefix each column name with
the appropriate table name. (See the synopsis for examples.)
- manager_class CLASS
- The name of the Rose::DB::Object::Manager-derived class
used to fetch the objects. The "manager_method" class method is
called on this class. Defaults to Rose::DB::Object::Manager.
- manager_method NAME
- The name of the class method to call on
"manager_class" in order to fetch the objects. Defaults to
"get_objects".
- manager_count_method NAME
- The name of the class method to call on
"manager_class" in order to count the objects. Defaults to
"get_objects_count".
- interface NAME
- Choose the interface. The "get_set" interface is
the default.
- relationship OBJECT
- The Rose::DB::Object::Metadata::Relationship object that
describes the "key" through which the "objects_by_key"
are fetched. This is required when using the "add_now",
"add_on_save", and "get_set_on_save" interfaces.
- share_db BOOL
- If true, the db attribute of the current object is shared
with all of the objects fetched. Defaults to true.
- query_args ARRAYREF
- A reference to an array of arguments added to the value of
the "query" parameter passed to the call to
"manager_class"'s "manager_method" class method.
- Interfaces
- count
- Creates a method that will attempt to count
Rose::DB::Object-derived objects based on a key formed from attributes of
the current object, plus any additional parameters passed to the method
call. Note that this method counts the objects in the database at the
time of the call. This may be different than the number of objects
attached to the current object or otherwise in memory.
Since the objects counted are partially determined by the arguments passed
to the method, the count is not retained. It is simply returned. Each call
counts the specified objects again, even if the arguments are the same as
the previous call.
If the first argument is a reference to a hash or array, it is converted to
a reference to an array (if necessary) and taken as the value of the
"query" parameter. All arguments are passed on to the
"manager_class"'s "manager_count_method" method,
augmented by the key formed from attributes of the current object. Query
parameters are added to the existing contents of the "query"
parameter. Other parameters replace existing parameters if the existing
values are simple scalars, or augment existing parameters if the existing
values are references to hashes or arrays.
The count may fail for several reasons. The count will not even be attempted
if any of the key attributes in the current object are undefined. Instead,
undef (in scalar context) or an empty list (in list context) will be
returned. If the call to "manager_class"'s
"manager_count_method" method returns undef, the behavior is
determined by the metadata object's error_mode. If the mode is
"return", that false value (in scalar context) or an empty list
(in list context) is returned.
If the count succeeds, the number is returned. (If the count finds zero
objects, the count will be 0. This is still considered success.)
- find
- Creates a method that will attempt to fetch
Rose::DB::Object-derived objects based on a key formed from attributes of
the current object, plus any additional parameters passed to the method
call. Since the objects fetched are partially determined by the arguments
passed to the method, the list of objects is not retained. It is simply
returned. Each call fetches the requested objects again, even if the
arguments are the same as the previous call.
If the first argument is a reference to a hash or array, it is converted to
a reference to an array (if necessary) and taken as the value of the
"query" parameter. All arguments are passed on to the
"manager_class"'s "manager_method" method, augmented
by the key formed from attributes of the current object. Query parameters
are added to the existing contents of the "query" parameter.
Other parameters replace existing parameters if the existing values are
simple scalars, or augment existing parameters if the existing values are
references to hashes or arrays.
The fetch may fail for several reasons. The fetch will not even be attempted
if any of the key attributes in the current object are undefined. Instead,
undef (in scalar context) or an empty list (in list context) will be
returned. If the call to "manager_class"'s
"manager_method" method returns false, the behavior is
determined by the metadata object's error_mode. If the mode is
"return", that false value (in scalar context) or an empty list
(in list context) is returned.
If the fetch succeeds, a list (in list context) or a reference to the array
of objects (in scalar context) is returned. (If the fetch finds zero
objects, the list or array reference will simply be empty. This is still
considered success.)
- iterator
- Behaves just like find but returns an iterator
rather than an array or arrayref.
- get_set
- Creates a method that will attempt to fetch
Rose::DB::Object-derived objects based on a key formed from attributes of
the current object.
If passed a single argument of undef, the "hash_key" used to store
the objects is set to undef. Otherwise, the argument(s) must be a list or
reference to an array containing items in one or more of the following
formats:
- •
- An object of type "class".
- •
- A reference to a hash containing method name/value
pairs.
- •
- A single scalar primary key value.
The latter two formats will be used to construct an object of type
"class". A single primary key value is only a valid argument format
if the "class" in question has a single-column primary key. A hash
reference argument must contain sufficient information for the object to be
uniquely identified.
The list of object is assigned to "hash_key". Note that these objects
are
not added to the database. Use the "get_set_now" or
"get_set_on_save" interface to do that.
If called with no arguments and the hash key used to store the list of objects
is defined, the list (in list context) or a reference to that array (in scalar
context) of objects is returned. Otherwise, the objects are fetched.
The fetch may fail for several reasons. The fetch will not even be attempted if
any of the key attributes in the current object are undefined. Instead, undef
(in scalar context) or an empty list (in list context) will be returned. If
the call to "manager_class"'s "manager_method" method
returns false, the behavior is determined by the metadata object's error_mode.
If the mode is "return", that false value (in scalar context) or an
empty list (in list context) is returned.
If the fetch succeeds, a list (in list context) or a reference to the array of
objects (in scalar context) is returned. (If the fetch finds zero objects, the
list or array reference will simply be empty. This is still considered
success.)
- get_set_now
- Creates a method that will attempt to fetch
Rose::DB::Object-derived objects based on a key formed from attributes of
the current object, and will also save the objects to the database when
called with arguments. The objects do not have to already exist in the
database; they will be inserted if needed.
If passed a single argument of undef, the list of objects is set to undef,
causing it to be reloaded the next time the method is called with no
arguments. (Pass a reference to an empty array to cause all of the
existing objects to be deleted from the database.) Any pending
"set_on_save" or "add_on_save" actions are discarded.
Otherwise, the argument(s) must be a list or reference to an array
containing items in one or more of the following formats:
- •
- An object of type "class".
- •
- A reference to a hash containing method name/value
pairs.
- •
- A single scalar primary key value.
The latter two formats will be used to construct an object of type
"class". A single primary key value is only a valid argument format
if the "class" in question has a single-column primary key. A hash
reference argument must contain sufficient information for the object to be
uniquely identified.
The list of object is assigned to "hash_key", the old objects are
deleted from the database, and the new ones are added to the database. Any
pending "set_on_save" or "add_on_save" actions are
discarded.
When adding each object, if the object does not already exists in the database,
it will be inserted. If the object was previously loaded from or saved to the
database, it will be updated. Otherwise, it will be loaded.
The parent object must have been loaded or saved prior to setting the list of
objects. If this method is called with arguments before the object has been
loaded or saved, a fatal error will occur.
If called with no arguments and the hash key used to store the list of objects
is defined, the list (in list context) or a reference to that array (in scalar
context) of objects is returned. Otherwise, the objects are fetched.
The fetch may fail for several reasons. The fetch will not even be attempted if
any of the key attributes in the current object are undefined. Instead, undef
(in scalar context) or an empty list (in list context) will be returned. If
the call to "manager_class"'s "manager_method" method
returns false, the behavior is determined by the metadata object's error_mode.
If the mode is "return", that false value (in scalar context) or an
empty list (in list context) is returned.
If the fetch succeeds, a list (in list context) or a reference to the array of
objects (in scalar context) is returned. (If the fetch finds zero objects, the
list or array reference will simply be empty. This is still considered
success.)
- get_set_on_save
- Creates a method that will attempt to fetch
Rose::DB::Object-derived objects based on a key formed from attributes of
the current object, and will also save the objects to the database when
the "parent" object is saved. The objects do not have to already
exist in the database; they will be inserted if needed.
If passed a single argument of undef, the list of objects is set to undef,
causing it to be reloaded the next time the method is called with no
arguments. (Pass a reference to an empty array to cause all of the
existing objects to be deleted from the database when the parent is
saved.)
Otherwise, the argument(s) must be a list or reference to an array
containing items in one or more of the following formats:
- •
- An object of type "class".
- •
- A reference to a hash containing method name/value
pairs.
- •
- A single scalar primary key value.
The latter two formats will be used to construct an object of type
"class". A single primary key value is only a valid argument format
if the "class" in question has a single-column primary key. A hash
reference argument must contain sufficient information for the object to be
uniquely identified.
The list of object is assigned to "hash_key". The old objects are
scheduled to be deleted from the database and the new ones are scheduled to be
added to the database when the parent is saved. Any pending
"set_on_save" or "add_on_save" actions are discarded.
When adding each object when the parent is saved, if the object does not already
exists in the database, it will be inserted. If the object was previously
loaded from or saved to the database, it will be updated. Otherwise, it will
be loaded.
If called with no arguments and the hash key used to store the list of objects
is defined, the list (in list context) or a reference to that array (in scalar
context) of objects is returned. Otherwise, the objects are fetched.
The fetch may fail for several reasons. The fetch will not even be attempted if
any of the key attributes in the current object are undefined. Instead, undef
(in scalar context) or an empty list (in list context) will be returned. If
the call to "manager_class"'s "manager_method" method
returns false, the behavior is determined by the metadata object's error_mode.
If the mode is "return", that false value (in scalar context) or an
empty list (in list context) is returned.
If the fetch succeeds, a list (in list context) or a reference to the array of
objects (in scalar context) is returned. (If the fetch finds zero objects, the
list or array reference will simply be empty. This is still considered
success.)
- add_now
- Creates a method that will add to a list of
Rose::DB::Object-derived objects that are related to the current object by
a key formed from attributes of the current object. The objects do not
have to already exist in the database; they will be inserted if needed.
This method returns the list of objects added when called in list context,
and the number of objects added when called in scalar context. If one or
more objects could not be added, undef (in scalar context) or an empty
list (in list context) is returned and the parent object's error attribute
is set.
If passed an empty list, the method does nothing and the parent object's
error attribute is set.
If passed any arguments, the parent object must have been loaded or saved
prior to adding to the list of objects. If this method is called with a
non-empty list as an argument before the parent object has been loaded or
saved, a fatal error will occur.
The argument(s) must be a list or reference to an array containing items in
one or more of the following formats:
- •
- An object of type "class".
- •
- A reference to a hash containing method name/value
pairs.
- •
- A single scalar primary key value.
The latter two formats will be used to construct an object of type
"class". A single primary key value is only a valid argument format
if the "class" in question has a single-column primary key. A hash
reference argument must contain sufficient information for the object to be
uniquely identified.
These objects are linked to the parent object (by setting the appropriate key
attributes) and then added to the database.
When adding each object, if the object does not already exists in the database,
it will be inserted. If the object was previously loaded from or saved to the
database, it will be updated. Otherwise, it will be loaded.
The parent object's list of related objects is then set to undef, causing the
related objects to be reloaded from the database the next time they're
needed.
- add_on_save
- Creates a method that will add to a list of
Rose::DB::Object-derived objects that are related to the current object by
a key formed from attributes of the current object. The objects will be
added to the database when the parent object is saved. The objects do not
have to already exist in the database; they will be inserted if needed.
This method returns the list of objects to be added when called in list
context, and the number of items to be added when called in scalar
context.
If passed an empty list, the method does nothing and the parent object's
error attribute is set.
Otherwise, the argument(s) must be a list or reference to an array
containing items in one or more of the following formats:
- •
- An object of type "class".
- •
- A reference to a hash containing method name/value
pairs.
- •
- A single scalar primary key value.
The latter two formats will be used to construct an object of type
"class". A single primary key value is only a valid argument format
if the "class" in question has a single-column primary key. A hash
reference argument must contain sufficient information for the object to be
uniquely identified.
These objects are linked to the parent object (by setting the appropriate key
attributes, whether or not they're defined in the parent object) and are
scheduled to be added to the database when the parent object is saved. They
are also added to the parent object's current list of related objects, if the
list is defined at the time of the call.
When adding each object when the parent is saved, if the object does not already
exists in the database, it will be inserted. If the object was previously
loaded from or saved to the database, it will be updated. Otherwise, it will
be loaded.
Example setup:
# CLASS DB TABLE
# ------- --------
# Program programs
# Bug bugs
package Program;
our @ISA = qw(Rose::DB::Object);
...
# You will almost never call the method-maker directly
# like this. See the Rose::DB::Object::Metadata docs
# for examples of more common usage.
use Rose::DB::Object::MakeMethods::Generic
(
objects_by_key =>
[
find_bugs =>
{
interface => 'find',
class => 'Bug',
key_columns =>
{
# Map Program column names to Bug column names
id => 'program_id',
version => 'version',
},
manager_args => { sort_by => 'date_submitted DESC' },
},
bugs =>
{
interface => '...', # get_set, get_set_now, get_set_on_save
class => 'Bug',
key_columns =>
{
# Map Program column names to Bug column names
id => 'program_id',
version => 'version',
},
manager_args => { sort_by => 'date_submitted DESC' },
query_args => { state => { ne => 'closed' } },
},
add_bugs =>
{
interface => '...', # add_now or add_on_save
class => 'Bug',
key_columns =>
{
# Map Program column names to Bug column names
id => 'program_id',
version => 'version',
},
manager_args => { sort_by => 'date_submitted DESC' },
query_args => { state => { ne => 'closed' } },
},
]
);
...
Example - find interface:
# Read from the programs table
$prog = Program->new(id => 5)->load;
# Read from the bugs table
$bugs = $prog->find_bugs;
# Calls (essentially):
#
# Rose::DB::Object::Manager->get_objects(
# db => $prog->db, # share_db defaults to true
# object_class => 'Bug',
# query =>
# [
# program_id => 5, # value of $prog->id
# version => '3.0', # value of $prog->version
# ],
# sort_by => 'date_submitted DESC');
# Augment query
$bugs = $prog->find_bugs({ state => 'open' });
# Calls (essentially):
#
# Rose::DB::Object::Manager->get_objects(
# db => $prog->db, # share_db defaults to true
# object_class => 'Bug',
# query =>
# [
# program_id => 5, # value of $prog->id
# version => '3.0', # value of $prog->version
# state => 'open',
# ],
# sort_by => 'date_submitted DESC');
...
# Augment query and replace sort_by value
$bugs = $prog->find_bugs(query => [ state => 'defunct' ],
sort_by => 'name');
# Calls (essentially):
#
# Rose::DB::Object::Manager->get_objects(
# db => $prog->db, # share_db defaults to true
# object_class => 'Bug',
# query =>
# [
# program_id => 5, # value of $prog->id
# version => '3.0', # value of $prog->version
# state => 'defunct',
# ],
# sort_by => 'name');
...
Example - get_set interface:
# Read from the programs table
$prog = Program->new(id => 5)->load;
# Read from the bugs table
$bugs = $prog->bugs;
# Calls (essentially):
#
# Rose::DB::Object::Manager->get_objects(
# db => $prog->db, # share_db defaults to true
# object_class => 'Bug',
# query =>
# [
# program_id => 5, # value of $prog->id
# version => '3.0', # value of $prog->version
# state => { ne => 'closed' },
# ],
# sort_by => 'date_submitted DESC');
...
$prog->version($new_version); # Does not hit the db
$prog->bugs(@new_bugs); # Does not hit the db
# @new_bugs can contain any mix of these types:
#
# @new_bugs =
# (
# 123, # primary key value
# { id => 456 }, # method name/value pairs
# Bug->new(id => 789), # object
# );
# Write to the programs table only. The bugs table is not
# updated. See the get_set_now and get_set_on_save method
# types for ways to write to the bugs table.
$prog->save;
Example - get_set_now interface:
# Read from the programs table
$prog = Program->new(id => 5)->load;
# Read from the bugs table
$bugs = $prog->bugs;
$prog->name($new_name); # Does not hit the db
# Writes to the bugs table, deleting existing bugs and
# replacing them with @new_bugs (which must be an array
# of Bug objects, either existing or new)
$prog->bugs(@new_bugs);
# @new_bugs can contain any mix of these types:
#
# @new_bugs =
# (
# 123, # primary key value
# { id => 456 }, # method name/value pairs
# Bug->new(id => 789), # object
# );
# Write to the programs table
$prog->save;
Example - get_set_on_save interface:
# Read from the programs table
$prog = Program->new(id => 5)->load;
# Read from the bugs table
$bugs = $prog->bugs;
$prog->name($new_name); # Does not hit the db
$prog->bugs(@new_bugs); # Does not hit the db
# @new_bugs can contain any mix of these types:
#
# @new_bugs =
# (
# 123, # primary key value
# { id => 456 }, # method name/value pairs
# Bug->new(id => 789), # object
# );
# Write to the programs table and the bugs table, deleting any
# existing bugs and replacing them with @new_bugs (which must be
# an array of Bug objects, either existing or new)
$prog->save;
Example - add_now interface:
# Read from the programs table
$prog = Program->new(id => 5)->load;
# Read from the bugs table
$bugs = $prog->bugs;
$prog->name($new_name); # Does not hit the db
# Writes to the bugs table, adding @new_bugs to the current
# list of bugs for this program
$prog->add_bugs(@new_bugs);
# @new_bugs can contain any mix of these types:
#
# @new_bugs =
# (
# 123, # primary key value
# { id => 456 }, # method name/value pairs
# Bug->new(id => 789), # object
# );
# Read from the bugs table, getting the full list of bugs,
# including the ones that were added above.
$bugs = $prog->bugs;
# Write to the programs table only
$prog->save;
Example - add_on_save interface:
# Read from the programs table
$prog = Program->new(id => 5)->load;
# Read from the bugs table
$bugs = $prog->bugs;
$prog->name($new_name); # Does not hit the db
$prog->add_bugs(@new_bugs); # Does not hit the db
$prog->add_bugs(@more_bugs); # Does not hit the db
# @new_bugs and @more_bugs can contain any mix of these types:
#
# @new_bugs =
# (
# 123, # primary key value
# { id => 456 }, # method name/value pairs
# Bug->new(id => 789), # object
# );
# Write to the programs table and the bugs table, adding
# @new_bugs to the current list of bugs for this program
$prog->save;
- objects_by_map
- Create methods that fetch Rose::DB::Object-derived objects
via an intermediate Rose::DB::Object-derived class that maps between two
other Rose::DB::Object-derived classes. See the
Rose::DB::Object::Metadata::Relationship::ManyToMany documentation for a
more complete example of this type of method in action.
- Options
- hash_key NAME
- The key inside the hash-based object to use for the storage
of the fetched objects. Defaults to the name of the method.
- interface NAME
- Choose the interface. The "get_set" interface is
the default.
- manager_args HASHREF
- A reference to a hash of arguments passed to the
"manager_class" when fetching objects. If
"manager_args" includes a "sort_by" argument, be sure
to prefix each column name with the appropriate table name. (See the
synopsis for examples.)
- manager_class CLASS
- The name of the Rose::DB::Object::Manager-derived class
that the "map_class" will use to fetch records. Defaults to
Rose::DB::Object::Manager.
- manager_method NAME
- The name of the class method to call on
"manager_class" in order to fetch the objects. Defaults to
"get_objects".
- manager_count_method NAME
- The name of the class method to call on
"manager_class" in order to count the objects. Defaults to
"get_objects_count".
- map_class CLASS
- The name of the Rose::DB::Object-derived class that maps
between the other two Rose::DB::Object-derived classes. This class must
have a foreign key and/or "many to one" relationship for each of
the two tables that it maps between.
- map_from NAME
- The name of the "many to one" relationship or
foreign key in "map_class" that points to the object of the
class that this relationship exists in. Setting this value is only
necessary if the "map_class" has more than one foreign key or
"many to one" relationship that points to one of the classes
that it maps between.
- map_to NAME
- The name of the "many to one" relationship or
foreign key in "map_class" that points to the
"foreign" object to be fetched. Setting this value is only
necessary if the "map_class" has more than one foreign key or
"many to one" relationship that points to one of the classes
that it maps between.
- relationship OBJECT
- The Rose::DB::Object::Metadata::Relationship object that
describes the "key" through which the "objects_by_key"
are fetched. This option is required.
- share_db BOOL
- If true, the db attribute of the current object is shared
with all of the objects fetched. Defaults to true.
- query_args ARRAYREF
- A reference to an array of arguments added to the value of
the "query" parameter passed to the call to
"manager_class"'s "manager_method" class method.
- Interfaces
- count
- Creates a method that will attempt to count
Rose::DB::Object-derived objects that are related to the current object
through the "map_class", plus any additional parameters passed
to the method call. Note that this method counts the objects in the
database at the time of the call. This may be different than the
number of objects attached to the current object or otherwise in memory.
Since the objects counted are partially determined by the arguments passed
to the method, the count is not retained. It is simply returned. Each call
counts the specified objects again, even if the arguments are the same as
the previous call.
If the first argument is a reference to a hash or array, it is converted to
a reference to an array (if necessary) and taken as the value of the
"query" parameter. All arguments are passed on to the
"manager_class"'s "manager_count_method" method,
augmented by the mapping to the current object. Query parameters are added
to the existing contents of the "query" parameter. Other
parameters replace existing parameters if the existing values are simple
scalars, or augment existing parameters if the existing values are
references to hashes or arrays.
The count may fail for several reasons. The count will not even be attempted
if any of the key attributes in the current object are undefined. Instead,
undef (in scalar context) or an empty list (in list context) will be
returned. If the call to "manager_class"'s
"manager_count_method" method returns undef, the behavior is
determined by the metadata object's error_mode. If the mode is
"return", that false value (in scalar context) or an empty list
(in list context) is returned.
If the count succeeds, the number is returned. (If the count finds zero
objects, the count will be 0. This is still considered success.)
- find
- Creates a method that will attempt to fetch
Rose::DB::Object-derived that are related to the current object through
the "map_class", plus any additional parameters passed to the
method call. Since the objects fetched are partially determined by the
arguments passed to the method, the list of objects is not retained. It is
simply returned. Each call fetches the requested objects again, even if
the arguments are the same as the previous call.
If the first argument is a reference to a hash or array, it is converted to
a reference to an array (if necessary) and taken as the value of the
"query" parameter. All arguments are passed on to the
"manager_class"'s "manager_method" method, augmented
by the mapping to the current object. Query parameters are added to the
existing contents of the "query" parameter. Other parameters
replace existing parameters if the existing values are simple scalars, or
augment existing parameters if the existing values are references to
hashes or arrays.
The fetch may fail for several reasons. The fetch will not even be attempted
if any of the key attributes in the current object are undefined. Instead,
undef (in scalar context) or an empty list (in list context) will be
returned. If the call to "manager_class"'s
"manager_method" method returns false, the behavior is
determined by the metadata object's error_mode. If the mode is
"return", that false value (in scalar context) or an empty list
(in list context) is returned.
If the fetch succeeds, a list (in list context) or a reference to the array
of objects (in scalar context) is returned. (If the fetch finds zero
objects, the list or array reference will simply be empty. This is still
considered success.)
- iterator
- Behaves just like find but returns an iterator
rather than an array or arrayref.
- get_set
- Creates a method that will attempt to fetch
Rose::DB::Object-derived objects that are related to the current object
through the "map_class".
If passed a single argument of undef, the "hash_key" used to store
the objects is set to undef. Otherwise, the argument(s) must be a list or
reference to an array containing items in one or more of the following
formats:
- •
- An object of type "class".
- •
- A reference to a hash containing method name/value
pairs.
- •
- A single scalar primary key value.
The latter two formats will be used to construct an object of type
"class". A single primary key value is only a valid argument format
if the "class" in question has a single-column primary key. A hash
reference argument must contain sufficient information for the object to be
uniquely identified.
The list of object is assigned to "hash_key". Note that these objects
are
not added to the database. Use the "get_set_now" or
"get_set_on_save" interface to do that.
If called with no arguments and the hash key used to store the list of objects
is defined, the list (in list context) or a reference to that array (in scalar
context) of objects is returned. Otherwise, the objects are fetched.
When fetching objects from the database, if the call to
"manager_class"'s "manager_method" method returns false,
that false value (in scalar context) or an empty list (in list context) is
returned.
If the fetch succeeds, a list (in list context) or a reference to the array of
objects (in scalar context) is returned. (If the fetch finds zero objects, the
list or array reference will simply be empty. This is still considered
success.)
- get_set_now
- Creates a method that will attempt to fetch
Rose::DB::Object-derived objects that are related to the current object
through the "map_class", and will also save objects to the
database and map them to the parent object when called with arguments. The
objects do not have to already exist in the database; they will be
inserted if needed.
If passed a single argument of undef, the list of objects is set to undef,
causing it to be reloaded the next time the method is called with no
arguments. (Pass a reference to an empty array to cause all of the
existing objects to be "unmapped"--that is, to have their
entries in the mapping table deleted from the database.) Any pending
"set_on_save" or "add_on_save" actions are discarded.
Otherwise, the argument(s) must be a list or reference to an array
containing items in one or more of the following formats:
- •
- An object of type "class".
- •
- A reference to a hash containing method name/value
pairs.
- •
- A single scalar primary key value.
The latter two formats will be used to construct an object of type
"class". A single primary key value is only a valid argument format
if the "class" in question has a single-column primary key. A hash
reference argument must contain sufficient information for the object to be
uniquely identified.
The list of object is assigned to "hash_key", the old entries are
deleted from the mapping table in the database, and the new objects are added
to the database, along with their corresponding mapping entries. Any pending
"set_on_save" or "add_on_save" actions are discarded.
When adding each object, if the object does not already exists in the database,
it will be inserted. If the object was previously loaded from or saved to the
database, it will be updated. Otherwise, it will be loaded.
The parent object must have been loaded or saved prior to setting the list of
objects. If this method is called with arguments before the object has been
loaded or saved, a fatal error will occur.
If called with no arguments and the hash key used to store the list of objects
is defined, the list (in list context) or a reference to that array (in scalar
context) of objects is returned. Otherwise, the objects are fetched.
When fetching, if the call to "manager_class"'s
"manager_method" method returns false, that false value (in scalar
context) or an empty list (in list context) is returned.
If the fetch succeeds, a list (in list context) or a reference to the array of
objects (in scalar context) is returned. (If the fetch finds zero objects, the
list or array reference will simply be empty. This is still considered
success.)
- get_set_on_save
- Creates a method that will attempt to fetch
Rose::DB::Object-derived objects that are related to the current object
through the "map_class", and will also save objects to the
database and map them to the parent object when the "parent"
object is saved. The objects do not have to already exist in the database;
they will be inserted if needed.
If passed a single argument of undef, the list of objects is set to undef,
causing it to be reloaded the next time the method is called with no
arguments. (Pass a reference to an empty array to cause all of the
existing objects to be "unmapped"--that is, to have their
entries in the mapping table deleted from the database.) Any pending
"set_on_save" or "add_on_save" actions are discarded.
Otherwise, the argument(s) must be a list or reference to an array
containing items in one or more of the following formats:
- •
- An object of type "class".
- •
- A reference to a hash containing method name/value
pairs.
- •
- A single scalar primary key value.
The latter two formats will be used to construct an object of type
"class". A single primary key value is only a valid argument format
if the "class" in question has a single-column primary key. A hash
reference argument must contain sufficient information for the object to be
uniquely identified.
The list of object is assigned to "hash_key". The mapping table
records that mapped the old objects to the parent object are scheduled to be
deleted from the database and new ones are scheduled to be added to the
database when the parent is saved. Any previously pending
"set_on_save" or "add_on_save" actions are discarded.
When adding each object when the parent is saved, if the object does not already
exists in the database, it will be inserted. If the object was previously
loaded from or saved to the database, it will be updated. Otherwise, it will
be loaded.
If called with no arguments and the hash key used to store the list of objects
is defined, the list (in list context) or a reference to that array (in scalar
context) of objects is returned. Otherwise, the objects are fetched.
When fetching, if the call to "manager_class"'s
"manager_method" method returns false, that false value (in scalar
context) or an empty list (in list context) is returned.
If the fetch succeeds, a list (in list context) or a reference to the array of
objects (in scalar context) is returned. (If the fetch finds zero objects, the
list or array reference will simply be empty. This is still considered
success.)
- add_now
- Creates a method that will add to a list of
Rose::DB::Object-derived objects that are related to the current object
through the "map_class", and will also save objects to the
database and map them to the parent object. The objects do not have to
already exist in the database; they will be inserted if needed.
This method returns the list of objects added when called in list context,
and the number of objects added when called in scalar context. If one or
more objects could not be added, undef (in scalar context) or an empty
list (in list context) is returned and the parent object's error attribute
is set.
If passed an empty list, the method does nothing and the parent object's
error attribute is set.
If passed any arguments, the parent object must have been loaded or saved
prior to adding to the list of objects. If this method is called with a
non-empty list as an argument before the parent object has been loaded or
saved, a fatal error will occur.
The argument(s) must be a list or reference to an array containing items in
one or more of the following formats:
- •
- An object of type "class".
- •
- A reference to a hash containing method name/value
pairs.
- •
- A single scalar primary key value.
The latter two formats will be used to construct an object of type
"class". A single primary key value is only a valid argument format
if the "class" in question has a single-column primary key. A hash
reference argument must contain sufficient information for the object to be
uniquely identified.
The parent object's list of related objects is then set to undef, causing the
related objects to be reloaded from the database the next time they're
needed.
- add_on_save
- Creates a method that will add to a list of
Rose::DB::Object-derived objects that are related to the current object
through the "map_class", and will also save objects to the
database and map them to the parent object when the "parent"
object is saved. The objects and map records will be added to the database
when the parent object is saved. The objects do not have to already exist
in the database; they will be inserted if needed.
This method returns the list of objects to be added when called in list
context, and the number of items to be added when called in scalar
context.
If passed an empty list, the method does nothing and the parent object's
error attribute is set.
Otherwise, the argument(s) must be a list or reference to an array
containing items in one or more of the following formats:
- •
- An object of type "class".
- •
- A reference to a hash containing method name/value
pairs.
- •
- A single scalar primary key value.
The latter two formats will be used to construct an object of type
"class". A single primary key value is only a valid argument format
if the "class" in question has a single-column primary key. A hash
reference argument must contain sufficient information for the object to be
uniquely identified.
These objects are scheduled to be added to the database and mapped to the parent
object when the parent object is saved. They are also added to the parent
object's current list of related objects, if the list is defined at the time
of the call.
For a complete example of this method type in action, see the
Rose::DB::Object::Metadata::Relationship::ManyToMany documentation.
- object_by_key
- Create a get/set methods for a single
Rose::DB::Object-derived object loaded based on a primary key formed from
attributes of the current object.
- Options
- class CLASS
- The name of the Rose::DB::Object-derived class of the
object to be loaded. This option is required.
- foreign_key OBJECT
- The Rose::DB::Object::Metadata::ForeignKey object that
describes the "key" through which the "object_by_key"
is fetched. This (or the "relationship" parameter) is required
when using the "delete_now", "delete_on_save", and
"get_set_on_save" interfaces.
- hash_key NAME
- The key inside the hash-based object to use for the storage
of the object. Defaults to the name of the method.
- if_not_found CONSEQUENCE
- This setting determines what happens when the key_columns
have defined values, but the foreign object they point to is not found.
Valid values for CONSEQUENCE are "fatal", which will throw an
exception if the foreign object is not found, and "ok" which
will merely cause the relevant method(s) to return undef. The default is
"fatal".
- key_columns HASHREF
- A reference to a hash that maps column names in the current
object to those of the primary key in the object to be loaded. This option
is required.
- interface NAME
- Choose the interface. The default is
"get_set".
- relationship OBJECT
- The Rose::DB::Object::Metadata::Relationship-derived object
that describes the relationship through which the object is fetched. This
(or the "foreign_key" parameter) is required when using the
"delete_now", "delete_on_save", and
"get_set_on_save" interfaces.
- referential_integrity BOOL
- If true, then a fatal error will occur when a method in one
of the "get*" interfaces is called and no related object is
found. The default is determined by the referential_integrity attribute of
the "foreign_key" object, or true if no "foreign_key"
parameter is passed.
This parameter conflicts with the "required" parameter. Only one
of the two should be passed.
- required BOOL
- If true, then a fatal error will occur when a method in one
of the "get*" interfaces is called and no related object is
found. The default is determined by the required attribute of the
"relationship" object, or true if no "relationship"
parameter is passed.
This parameter conflicts with the "referential_integrity"
parameter. Only one of the two should be passed.
- share_db BOOL
- If true, the db attribute of the current object is shared
with the object loaded. Defaults to true.
- Interfaces
- delete_now
- Deletes a Rose::DB::Object-derived object from the database
based on a primary key formed from attributes of the current object. If
"referential_integrity" or "required" is true, then
the "parent" object will have all of its attributes that refer
to the "foreign" object (except any columns that are also part
of the primary key) set to null , and it will be saved into the database.
This needs to be done first because a database that enforces referential
integrity will not allow a row to be deleted if it is still referenced by
a foreign key in another table.
Any previously pending "get_set_on_save" action is discarded.
The entire process takes place within a transaction if the database supports
it. If not currently in a transaction, a new one is started and then
committed on success and rolled back on failure.
Returns true if the foreign object was deleted successfully or did not exist
in the database, false if any of the keys that refer to the foreign object
were undef, and triggers the normal Rose::DB::Object error handling in the
case of any other kind of failure.
- delete_on_save
- Deletes a Rose::DB::Object-derived object from the database
when the "parent" object is saved, based on a primary key formed
from attributes of the current object. If
"referential_integrity" or "required" is true, then
the "parent" object will have all of its attributes that refer
to the "foreign" object (except any columns that are also part
of the primary key) set to null immediately, but the actual delete will
not be done until the parent is saved.
Any previously pending "get_set_on_save" action is discarded.
The entire process takes place within a transaction if the database supports
it. If not currently in a transaction, a new one is started and then
committed on success and rolled back on failure.
Returns true if the foreign object was deleted successfully or did not exist
in the database, false if any of the keys that refer to the foreign object
were undef, and triggers the normal Rose::DB::Object error handling in the
case of any other kind of failure.
- get_set
- Creates a method that will attempt to create and load a
Rose::DB::Object-derived object based on a primary key formed from
attributes of the current object.
If passed a single argument of undef, the "hash_key" used to store
the object is set to undef. If "referential_integrity" or
"required" is true, then the columns that participate in the key
are set to undef. (If any key column is part of the primary key, however,
it is not set to undef.) Otherwise, the argument must be one of the
following:
- •
- An object of type "class"
- •
- A list of method name/value pairs.
- •
- A reference to a hash containing method name/value
pairs.
- •
- A single scalar primary key value.
The latter three argument types will be used to construct an object of type
"class". A single primary key value is only valid if the
"class" in question has a single-column primary key. A hash
reference argument must contain sufficient information for the object to be
uniquely identified.
The object is assigned to "hash_key" after having its
"key_columns" set to their corresponding values in the current
object.
If called with no arguments and the "hash_key" used to store the
object is defined, the object is returned. Otherwise, the object is created
and loaded.
The load may fail for several reasons. The load will not even be attempted if
any of the key attributes in the current object are undefined. Instead, undef
will be returned.
If the call to the newly created object's load method returns false, then the
normal Rose::DB::Object error handling is triggered. The false value returned
by the call to the load method is returned (assuming no exception was raised).
If the load succeeds, the object is returned.
- get_set_now
- Creates a method that will attempt to create and load a
Rose::DB::Object-derived object based on a primary key formed from
attributes of the current object, and will also save the object to the
database when called with an appropriate object as an argument.
If passed a single argument of undef, the "hash_key" used to store
the object is set to undef. If "referential_integrity" or
"required" is true, then the columns that participate in the key
are set to undef. (If any key column is part of the primary key, however,
it is not set to undef.) Otherwise, the argument must be one of the
following:
- •
- An object of type "class"
- •
- A list of method name/value pairs.
- •
- A reference to a hash containing method name/value
pairs.
- •
- A single scalar primary key value.
The latter three argument types will be used to construct an object of type
"class". A single primary key value is only a valid argument format
if the "class" in question has a single-column primary key. A hash
reference argument must contain sufficient information for the object to be
uniquely identified.
The object is assigned to "hash_key" after having its
"key_columns" set to their corresponding values in the current
object. The object is then immediately saved to the database.
If the object does not already exists in the database, it will be inserted. If
the object was previously loaded from or saved to the database, it will be
updated. Otherwise, it will be loaded.
The parent object must have been loaded or saved prior to setting the list of
objects. If this method is called with arguments before the object has been
loaded or saved, a fatal error will occur.
If called with no arguments and the "hash_key" used to store the
object is defined, the object is returned. Otherwise, the object is created
and loaded.
The load may fail for several reasons. The load will not even be attempted if
any of the key attributes in the current object are undefined. Instead, undef
will be returned.
If the call to the newly created object's load method returns false, then the
normal Rose::DB::Object error handling is triggered. The false value returned
by the call to the load method is returned (assuming no exception was raised).
If the load succeeds, the object is returned.
- get_set_on_save
- Creates a method that will attempt to create and load a
Rose::DB::Object-derived object based on a primary key formed from
attributes of the current object, and save the object when the
"parent" object is saved.
If passed a single argument of undef, the "hash_key" used to store
the object is set to undef. If "referential_integrity" or
"required" is true, then the columns that participate in the key
are set to undef. (If any key column is part of the primary key, however,
it is not set to undef.) Otherwise, the argument must be one of the
following:
- •
- An object of type "class"
- •
- A list of method name/value pairs.
- •
- A reference to a hash containing method name/value
pairs.
- •
- A single scalar primary key value.
The latter three argument types will be used to construct an object of type
"class". A single primary key value is only a valid argument format
if the "class" in question has a single-column primary key. A hash
reference argument must contain sufficient information for the object to be
uniquely identified.
The object is assigned to "hash_key" after having its
"key_columns" set to their corresponding values in the current
object. The object will be saved into the database when the "parent"
object is saved. Any previously pending "get_set_on_save" action is
discarded.
If the object does not already exists in the database, it will be inserted. If
the object was previously loaded from or saved to the database, it will be
updated. Otherwise, it will be loaded.
If called with no arguments and the "hash_key" used to store the
object is defined, the object is returned. Otherwise, the object is created
and loaded from the database.
The load may fail for several reasons. The load will not even be attempted if
any of the key attributes in the current object are undefined. Instead, undef
will be returned.
If the call to the newly created object's load method returns false, then the
normal Rose::DB::Object error handling is triggered. The false value returned
by the call to the load method is returned (assuming no exception was raised).
If the load succeeds, the object is returned.
Example setup:
# CLASS DB TABLE
# ------- --------
# Product products
# Category categories
package Product;
our @ISA = qw(Rose::DB::Object);
...
# You will almost never call the method-maker directly
# like this. See the Rose::DB::Object::Metadata docs
# for examples of more common usage.
use Rose::DB::Object::MakeMethods::Generic
(
object_by_key =>
[
category =>
{
interface => 'get_set',
class => 'Category',
key_columns =>
{
# Map Product column names to Category column names
category_id => 'id',
},
},
]
);
...
Example - get_set interface:
$product = Product->new(id => 5, category_id => 99);
# Read from the categories table
$category = $product->category;
# $product->category call is roughly equivalent to:
#
# $cat = Category->new(id => $product->category_id
# db => $prog->db);
#
# $ret = $cat->load;
# return $ret unless($ret);
# return $cat;
# Does not write to the db
$product->category(Category->new(...));
$product->save; # writes to products table only
Example - get_set_now interface:
# Read from the products table
$product = Product->new(id => 5)->load;
# Read from the categories table
$category = $product->category;
# Write to the categories table:
# (all possible argument formats show)
# Object argument
$product->category(Category->new(...));
# Primary key value
$product->category(123);
# Method name/value pairs in a hashref
$product->category(id => 123);
# Method name/value pairs in a hashref
$product->category({ id => 123 });
# Write to the products table
$product->save;
Example - get_set_on_save interface:
# Read from the products table
$product = Product->new(id => 5)->load;
# Read from the categories table
$category = $product->category;
# These do not write to the db:
# Object argument
$product->category(Category->new(...));
# Primary key value
$product->category(123);
# Method name/value pairs in a hashref
$product->category(id => 123);
# Method name/value pairs in a hashref
$product->category({ id => 123 });
# Write to both the products and categories tables
$product->save;
Example - delete_now interface:
# Read from the products table
$product = Product->new(id => 5)->load;
# Write to both the categories and products tables
$product->delete_category();
Example - delete_on_save interface:
# Read from the products table
$product = Product->new(id => 5)->load;
# Does not write to the db
$product->delete_category();
# Write to both the products and categories tables
$product->save;
- scalar
- Create get/set methods for scalar attributes.
- Options
- default VALUE
- Determines the default value of the attribute.
- check_in ARRAYREF
- A reference to an array of valid values. When setting the
attribute, if the new value is not equal (string comparison) to one of the
valid values, a fatal error will occur.
- hash_key NAME
- The key inside the hash-based object to use for the storage
of this attribute. Defaults to the name of the method.
- init_method NAME
- The name of the method to call when initializing the value
of an undefined attribute. Defaults to the method name with the prefix
"init_" added. This option implies "with_init".
- interface NAME
- Choose the interface. The "get_set" interface is
the default.
- length INT
- The maximum number of characters in the string.
- overflow BEHAVIOR
- Determines the behavior when the value is greater than the
number of characters specified by the "length" option. Valid
values for BEHAVIOR are:
- fatal
- Throw an exception.
- truncate
- Truncate the value to the correct length.
- warn
- Print a warning message.
- with_init BOOL
- Modifies the behavior of the "get_set" and
"get" interfaces. If the attribute is undefined, the method
specified by the "init_method" option is called and the
attribute is set to the return value of that method.
- Interfaces
- get_set
- Creates a get/set method for an object attribute. When
called with an argument, the value of the attribute is set. The current
value of the attribute is returned.
- get
- Creates an accessor method for an object attribute that
returns the current value of the attribute.
- set
- Creates a mutator method for an object attribute. When
called with an argument, the value of the attribute is set. If called with
no arguments, a fatal error will occur.
Example:
package MyDBObject;
our @ISA = qw(Rose::DB::Object);
use Rose::DB::Object::MakeMethods::Generic
(
scalar =>
[
name => { default => 'Joe' },
type =>
{
with_init => 1,
check_in => [ qw(AA AAA C D) ],
}
set_type =>
{
check_in => [ qw(AA AAA C D) ],
}
],
);
sub init_type { 'C' }
...
$o = MyDBObject->new(...);
print $o->name; # Joe
print $o->type; # C
$o->name('Bob'); # set
$o->type('AA'); # set
eval { $o->type('foo') }; # fatal error: invalid value
print $o->name, ' is ', $o->type; # get
- set
- Create get/set methods for "set" attributes. A
"set" column in a database table contains an unordered group of
values. Not all databases support a "set" column type. Check the
Rose::DB documentation for your database type.
- Options
- default ARRAYREF
- Determines the default value of the attribute. The value
should be a reference to an array.
- hash_key NAME
- The key inside the hash-based object to use for the storage
of this attribute. Defaults to the name of the method.
- interface NAME
- Choose the interface. The default is
"get_set".
- values ARRAYREF
- A reference to an array of valid values for the set. If
present, attempting to use an invalid value will cause a fatal error.
- Interfaces
- get_set
- Creates a get/set method for a "set" object
attribute. A "set" column in a database table contains an
unordered group of values. On the Perl side of the fence, an ordered list
(an array) is used to store the values, but keep in mind that the order is
not significant, nor is it guaranteed to be preserved.
When setting the attribute, the value is passed through the parse_set method
of the object's db attribute.
When saving to the database, if the attribute value is defined, the method
will pass the attribute value through the format_set method of the
object's db attribute before returning it.
When not saving to the database, the method returns the set as a list in
list context, or as a reference to the array in scalar context.
- get
- Creates an accessor method for a "set" object
attribute. A "set" column in a database table contains an
unordered group of values. On the Perl side of the fence, an ordered list
(an array) is used to store the values, but keep in mind that the order is
not significant, nor is it guaranteed to be preserved.
When saving to the database, if the attribute value is defined, the method
will pass the attribute value through the format_set method of the
object's db attribute before returning it.
When not saving to the database, the method returns the set as a list in
list context, or as a reference to the array in scalar context.
- set
- Creates a mutator method for a "set" object
attribute. A "set" column in a database table contains an
unordered group of values. On the Perl side of the fence, an ordered list
(an array) is used to store the values, but keep in mind that the order is
not significant, nor is it guaranteed to be preserved.
When setting the attribute, the value is passed through the parse_set method
of the object's db attribute.
When saving to the database, if the attribute value is defined, the method
will pass the attribute value through the format_set method of the
object's db attribute before returning it.
When not saving to the database, the method returns the set as a list in
list context, or as a reference to the array in scalar context.
Example:
package Person;
our @ISA = qw(Rose::DB::Object);
...
use Rose::DB::Object::MakeMethods::Generic
(
set =>
[
'nicknames',
'set_nicks' => { interface => 'set', hash_key => 'nicknames' },
'parts' => { default => [ qw(arms legs) ] },
],
);
...
@parts = $person->parts; # ('arms', 'legs')
$parts = $person->parts; # [ 'arms', 'legs' ]
$person->nicknames('Jack', 'Gimpy'); # set with list
$person->nicknames([ 'Slim', 'Gip' ]); # set with array ref
$person->set_nicks('Jack', 'Gimpy'); # set with list
$person->set_nicks([ 'Slim', 'Gip' ]); # set with array ref
- varchar
- Create get/set methods for variable-length character string
attributes.
- Options
- default VALUE
- Determines the default value of the attribute.
- hash_key NAME
- The key inside the hash-based object to use for the storage
of this attribute. Defaults to the name of the method.
- init_method NAME
- The name of the method to call when initializing the value
of an undefined attribute. Defaults to the method name with the prefix
"init_" added. This option implies "with_init".
- interface NAME
- Choose the interface. The "get_set" interface is
the default.
- length INT
- The maximum number of characters in the string.
- overflow BEHAVIOR
- Determines the behavior when the value is greater than the
number of characters specified by the "length" option. Valid
values for BEHAVIOR are:
- fatal
- Throw an exception.
- truncate
- Truncate the value to the correct length.
- warn
- Print a warning message.
- with_init BOOL
- Modifies the behavior of the "get_set" and
"get" interfaces. If the attribute is undefined, the method
specified by the "init_method" option is called and the
attribute is set to the return value of that method.
- Interfaces
- get_set
- Creates a get/set accessor method for a fixed-length
character string attribute. When setting, any strings longer than
"length" will be truncated. If "length" is omitted,
the string will be left unmodified.
Example:
package MyDBObject;
our @ISA = qw(Rose::DB::Object);
use Rose::DB::Object::MakeMethods::Generic
(
varchar =>
[
'name' => { length => 3 },
],
);
...
$o->name('John'); # truncates on set
print $o->name; # 'Joh'
AUTHOR¶
John C. Siracusa (siracusa@gmail.com)
LICENSE¶
Copyright (c) 2010 by John C. Siracusa. All rights reserved. This program is
free software; you can redistribute it and/or modify it under the same terms
as Perl itself.