NAME

Meerkat::Role::Document - Enhances a Moose object with Meerkat methods and metadata

VERSION

version 0.016

SYNOPSIS

Your model class:

package My::Model::Person;

use Moose;

with 'Meerkat::Role::Document';

has name => (
    is       => 'ro',
    isa      => 'Str',
    required => 1,
);

has likes => (
    is      => 'ro',
    isa     => 'Num',
    default => 0,
);

has tags => (
    is      => 'ro',
    isa     => 'ArrayRef',
    default => sub { [] },
);

1;

In your code:

use Meerkat;

my $meerkat = Meerkat->new(
    model_namespace => "My::Model",
    database_name => "test"
);

my $person = $meerkat->collection("Person"); # My::Model::Person

# create a document
my $obj = $person->create( name => "Larry" );

# change document in the database and update object
$obj->update_set( name => "Moe" );
$obj->update_inc( likes => 1 );
$obj->update_push( tags => qw/cool hot trendy/ );

# get any other updates from the database
$obj->sync;

# delete it
$obj->remove;

DESCRIPTION

This role enhances a Moose class with attributes and methods needed to operate in tandem with a Meerkat::Collection.

The resulting object is a projection of the document state in the database. Update methods change the state atomically in the database and synchronize the object with the new state in the database (potentially including other changes from other sources).

Consuming the role

When you apply this role to your Moose class, it provides and manages the _id attribute for you. This attribute is meant to be public, but keeps the leading underscore for consistency with MongoDB classes.

The attributes you define should be read-only. Modifying attributes directly in the object will not be reflected in the database and will be lost the next time you synchronize.

Objects are serialized with MooseX::Storage. Any attributes that should not be serialized must have the DoNotSerialize trait:

has 'expensive' => (
    traits => [ 'DoNotSerialize' ],
    is     => 'lazy',
    isa    => 'HeavyObject',
);

Attributes with embedded objects are not well supported. See the Meerkat::Cookbook for more.

Working with objects

Create objects from an associated Meerkat::Collection, not with new.

my $obj = $person->create( %attributes );

That will construct the object, instantiate all lazy attributes (except those marked DoNoSerialize) and store the new document into the database.

Then, use the various update methods to modify state if you need to. Use sync to refresh the object with any remote changes from the database.

METHODS

new

Don't call this directly! Create objects through the Meerkat::Collection or they won't be added to the database.

my $obj = $person->create( name => "Joe" );

update

$obj->update( { '$set' => { 'name' => "Moe" } } );

Executes a MongoDB update command on the associated document and updates the object's attributes. You must only use MongoDB update operators to modify the document's fields.

Returns true if the updates are applied and synchronized. If the document has been removed, the method returns false and the object is marked as removed; subsequent update, sync or remove calls will do nothing and return false.

This command is intended for custom updates with unusual logic or operators. Many typical updates can be accomplished with the update_* methods described below.

For all update methods, you can use a MongoDB nested field label to modify values deep into a data structure. For example parents.father refers to $obj->parents->{father}.

update_set

$obj->update_set( name => "Luke Skywalker" );

Sets a field to a value. This is the MongoDB $set operator.

The field must be undefined or else the existing value and the new value must be of similar types (e.g. scalar or array or hash). For the purpose of this check, an object (e.g. a DateTime) is treated (opaquely) as a scalar value. If the types do not match, an error will be thrown.

Note this means that you can't set a defined value to undefined. To remove a field entirely, see "update_clear". If you need to make other structural changes, do it manually with the "update" method.