| Rose::DB::Object::MakeMethods::Generic(3pm) | User Contributed Perl Documentation | Rose::DB::Object::MakeMethods::Generic(3pm) |
Rose::DB::Object::MakeMethods::Generic - Create generic object methods for Rose::DB::Object-derived objects.
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;
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.
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.
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.
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
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.
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.
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
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.
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
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 '
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
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
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.)
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.)
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:
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.)
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:
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.)
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:
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.)
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:
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.
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:
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;
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.)
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.)
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:
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.)
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:
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.)
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:
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.)
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:
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.
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:
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.
This parameter conflicts with the "required" parameter. Only one of the two should be passed.
This parameter conflicts with the "referential_integrity" parameter. Only one of the two should be passed.
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.
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.
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:
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.
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:
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.
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:
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;
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
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.
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.
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
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'
John C. Siracusa (siracusa@gmail.com)
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.
| 2022-08-26 | perl v5.28.1 |