NAME

Perlbug::Object - Relation class

DESCRIPTION

Perlbug relation class.

Handles reading of existing, and assignment of new etc., relations between existing objects.

For inherited methods, see Perlbug::Object

SYNOPSIS

        use Perlbug::Relation;

        my $o_rel = Perlbug::Relation->new('bug', 'patch', 'from');

        my @pids  = $o_rel->read('19870502.007', '')->ids;

METHODS

new

Create new Relation object, using text indicators or the object itself, if you have it

        my $o_rel = Perlbug::Relation->new('bug', 'patch', 'to'); 

Or the other way round:

        my $o_rel = Perlbug::Relation->new('patch', 'bug', 'from');

If missing, the third argument will default to 'to'.

        my $o_rel = Perlbug::Relation->new($o_src, 'address'); # implied 'to'

Normally this won't be called directy, as you'll ask for an relation object from the object itself directly, and the object will pre-initialise the relationship, which is far more useful, like this:

        my $o_rel = $o_obj->relation('patch'); # <-- !

For more on this, see Perlbug::Object::relation() and Perlbug::Base::object()

source

Get and set Source object

        my $o_src = $o_rel->source();

target

Get and set target object

        my $o_tgt = $o_rel->target();

check

Check the relations are OK to each other

        my $i_ok = $o_rel->check();

set_source

Set source to given argument key, and objectid, used to ensure the relation object is reading/setting/etc. from the correct source/target combination.

        my $o_rel = $o_rel->set_source('status', '33');

An example of where this might be necessary or useful is when object caching is enabled from the application side, a bug and a status object have been created, and they both require a relation to one another to be handled.

Alternatively, from the command line, one can do this, noting that at the return of relation() and assign() the source is by default set to the creating object, in this case the bug, and to read the patch record, we need to set_source() the relation:

        perl -MPerlbug::Base -e "\
                print Perlbug::Object::Bug->new(\
                )->read('20000801.007')->relation('patch')->assign(\
                [('12', '1', '2', '4', '5')])->set_source('patch'\
                )->read('2')->format('A')\
                " 
Enjoy :-)

key

get source or target primary (relation) key(), default is source

        my $s_key = $o_obj->key;

        my $t_key = $o_obj->key('target');

oid

Wrapper to get and set self and source objectid.

        my $rel_oid = $o_rel->oid($id);

ids

Returns list of target ids, restrained by optionally supplied object or sql where statement:

        my @all_ids  = $o_rel->ids();

        my @rel_ids  = $o_obj->ids($o_rel, [$further_restrained_by_sql]);

        my @selected = $o_rel->ids($where);

reinit

Reset relation to default values

For more info see Perlbug::Object::reinit()

RECORDS

Record handling methods for Perlbug::Relation::\w+'s

These all return the object reference, so calls may be chained.

assign

Assign these ids (additionally), ie; non-prejudicial to other ids.

        $o_rel->assign(\@new_ids);

ASSIGNED

Returns 0|1 depending on whether object has been succesfully assigned to

        my $i_isok = $o_obj->ASSIGNED;

_assign

Wraps assign() to allow usage of name instead of id.

        $o_rel->_assign(\@names);

store

Assign these target ids (only) to the source, (given at new())

A bit like assign(), but very prejudicial against non-mentioned ids.

        $o_rel->store(\@ids);

Warning: this will remove all relative ids that are not mentioned! If in doubt use assign().

_store

Wraps store() to allow usage of name instead of id.

        $o_rel->_store(\@names);

delete

Delete these target ids

        $o_rel->delete(@unwanted_ids);

_delete

Wraps delete() to allow usage of name instead of id

        $o_rel->_delete(\@names);

create_target

Create these target ids - note that there is no implicit assign() here, if you want that, see _assign()

Input is expected to be the non-internally known identifier itself, rather than the system known id().

        $o_rel->create_target(\@names);                         # eg; changeids|versions|...

        $o_rel->assign([$o_rel->name2id(\@names)]); # then?

AUTHOR

Richard Foley perlbug@rfi.net 2000 2001