NAME

MongoDBI::Document::Relative - A Relationship Wrapper Around MongoDBI Relational Documents

VERSION

version 0.0.9

SYNOPSIS

# create a relational/reference document relationship for CDDB::Album

my $tracks = MongoDBI::Document::Relative->new(
    parent => 'CDDB::Album',
    target => 'CDDB::Track',
    config => { multiple => 1 }
);

$tracks->add(...); 

DESCRIPTION

MongoDBI::Document::Relative represents a MongoDB relational/reference document and is designed to be assigned to attributes in a parent document class. MongoDBI::Document::Relative provides a standardized API for handling relationship concerns (e.g. adding, selecting, and removing related documents).

This relationship identification class is used automatically by the "has_one", "has_many", and "belongs_to" keywords provided by MongoDBI::Document::Sugar.

The purpose of using this and other relationship identification/wrapper classes is that it provides the MongoDBI serialization/deserialization mechanisms with a standard API.

ATTRIBUTES

object

The object attribute can contain an instance of the class target (or an array of instances if the "multiple" configuration variable is true. You will likely never need to access this attribute directly because access and manipulation of the object(s) are made available through method calls.

parent

The parent attribute is required and should contain the fully-qualified class name of the parent document class. Once set you will likely never need to access this attribute directly.

target

The target attribute is required and should contain the fully-qualified class name of the document class to be used as a relational document class. Once set you will likely never need to access this attribute directly.

config

The config attribute can contain a hashref of key/value arguments which control how method calls manipulate the class instance(s) stored in the object attribute.

# forces the object attribute to become an arrayref having instances
# append the object attribute

MongoDBI::Document::Relative->new(
    ...,
    config => { multiple => 1 }
);

METHODS

add

The add method expects key/value arguments which will be passed to the create method of the class defined in the target attribute, or, a single argument which must be an instance of the class defined in the target attribute.

The add method adds, replaces or appends the object attribute based on the configuration in the config attribute.

my $tracks = MongoDBI::Document::Relative->new(
    ..., config => { multiple => 1 }
);

$tracks->add(...);
$tracks->add(...);
$tracks->add(...); # we've added three tracks

my $tracks = MongoDBI::Document::Relative->new(
    ..., config => {  }
);

$tracks->add(...);
$tracks->add(...); # we've replace the original track

The arguments passed to the add method must be attributes existing on the class defined in the target attribute.

count

The count method simply returns the number of objects existing in the object attribute.

my $tracks = MongoDBI::Document::Relative->new(
    ..., config => { multiple => 1 }
);

$tracks->add(...);
$tracks->add(...);
$tracks->add(...); 

$tracks->count(); # we've added three tracks

get

The get method retrieves a particular object instance from the object attribute (store), if configured for multiple objects, it accepts an index (starting at 0) which will return the object instance at that position, or a starting and ending index which returns object instances within that range.

my $tracks = MongoDBI::Document::Relative->new(
    ..., config => { multiple => 1 }
);

$tracks->add(...);
$tracks->add(...);
$tracks->add(...);
$tracks->add(...);
$tracks->add(...);
$tracks->add(...);
$tracks->add(...);
$tracks->add(...);
$tracks->add(...); 

my $track1 = $tracks->get(0);
my @tracks_first5 = $tracks->get(0, 4);

remove

The remove method retrieves and removes a particular object instance from the object attribute (store), if configured for multiple objects, it accepts an index (starting at 0) which will delete and return the object instance at that position, or a starting and ending index which deletes and returns object instances within that range (as you would expect the native Perl splice function to operate).

my $tracks = MongoDBI::Document::Relative->new(
    ..., config => { multiple => 1 }
);

$tracks->add(...);
$tracks->add(...);
$tracks->add(...);
$tracks->add(...);
$tracks->add(...);
$tracks->add(...);
$tracks->add(...);
$tracks->add(...);
$tracks->add(...); # added 9 tracks

my $track1 = $tracks->remove(0);
my @tracks_next5 = $tracks->remove(0, 4);

print $tracks->count; # prints 3

AUTHOR

Al Newkirk <awncorp@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2011 by awncorp.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

cpanm MongoDBI

perl -MCPAN -e shell
install MongoDBI