NAME

MongoDBI::Document::GridFile - A GridFS Wrapper Around MongoDBI File Documents

VERSION

version 0.0.4

SYNOPSIS

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

my $mp3s = MongoDBI::Document::GridFile->new(
    parent => 'CDDB::Track',
    config => { multiple => 1 }
);

$mp3s->add($path_or_io, ...); # 1st arg can be file_path or IO::File obj

DESCRIPTION

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

This relationship identification class is used automatically by the "file" keyword 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 a MongoDB::OID (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.

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::GridFile->new(
    ...,
    config => { multiple => 1 }
);

METHODS

add

The add method requires an absolute file path and optional key/value parameters which will be saved along-side of the gridfs document.

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

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

$mp3s->add($file1, ...);
$mp3s->add($file2, ...);
$mp3s->add($file3, ...); # we've added three files

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

$mp3s->add($file1, ...);
$mp3s->add($file2, ...); # we've replace the original file

The optional arguments passed to the add method can be arbitrary and will be saved in the gridfs along-side the file. It is important that you understand that those arbitrary parameters will not be saved on the parent document. Querying for the file based on those arbitrary parameters must be done on the gridfs collection related to the parent.

count

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

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

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

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

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 $mp3s = MongoDBI::Document::GridFile->new(
    ..., config => { multiple => 1 }
);

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

my $mp31 = $mp3s->get(0);
my @mp3s_first5 = $mp3s->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 $mp3s = MongoDBI::Document::Relative->new(
    ..., config => { multiple => 1 }
);

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

my $mp31 = $mp3s->remove(0);
my @mp3s_next5 = $mp3s->remove(0, 4);

print $mp3s->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