/ 
YAWF-Object-MongoDB-0.03
River stage zero No dependents
/ YAWF::Object::MongoDB

NAME

YAWF::Object::MongoDB - Object of a MongoDB document

VERSION

Version 0.03

NOTICE

This module has been written to be compatible to the YAWF::Object methods, but it can be used as a standalone MongoDB Object relational mapper (ORM) without YAWF even installed.

SYNOPSIS

Abstraction layer for a MongoDB database

This module is used as @ISA or use base parent for object modules of your project, it won't work standalone.

package My::Project::ObjectClass;

# Typical use
use YAWF::Object::MongoDB (collection => 'my_collection',
                           keys       => ['foo', 'bar'],
                           );

my @ISA = ('YAWF::Object::MongoDB');

1;

Within your script:

use My::Project::ObjectClass;

my $object = My::Project::ObjectClass->new();
my $object = My::Project::ObjectClass->list();
[...]

Other definition options (you'll always need @ISA/use base in addition):

   # Custom database info
   use YAWF::Object::MongoDB (server     => 'localhost:28017',
                              database   => 'my_db',
                              collection => 'my_collection',
                              keys       => ['foo', 'bar'],
                              );

   # Complex key definition with sub-objects
   use YAWF::Object::MongoDB (collection => 'my_collection',
                              keys       => {
                                       foo => 1,
                                       bar => {
                                           baz  => 1, # Enables $object->bar->baz($new_value);
                                           true => sub { return 1; },
                                           }
                                  },
                              );

   # Provide server, database and collection at runtime:
   use YAWF::Object::MongoDB (keys       => ['foo', 'bar']);
   sub SERVER { return 'localhost:28017'; }    # Called at runtime during the first
   sub DATABASE { return 'my_database'; }      # access to the database, may even        
   sub COLLECTION { return 'my_collection'; }  # change during runtime.

   # MongoDB data my also be defined in yawf.yml:
   mongodb:
       server: localhost:28017
       database: My_Database
       collection: 1_collection_for_everything

   # Bad way (may harm other projects running in the same mod_perl):
   $YAWF::Object::MongoDB::DEFAULT_SERVER = 'my.custom.server:99999';

Server, database and collection can be set at different places, priority order is: * sub in class * value given at "use"-time * YAWF config value * $DEFAULT_* values in YAWF::Object::MongoDB

CLASS METHODS

list

my @objects = YAWF::Object::MongoDB->list(); # Get all items of a table (could be big!)
my @objects = YAWF::Object::MongoDB->list({ foo => bar }); # Search for a list of items

count

my $count = YAWF::Object::MongoDB->count(); # Get the number of items in this table
my $count = YAWF::Object::MongoDB->count({ foo => bar }); # Get the number of items for this search

METHODS

new

my $object = YAWF::Object::MongoDB->new(); # New item
my $object = YAWF::Object::MongoDB->new($id); # Get item by primary key
my $object = YAWF::Object::MongoDB->new(foo => 'bar'); # Search item (returns the first)
my $object = YAWF::Object::MongoDB->new(foo => 'bar',
                                        baz => 'foo'); # Search item (returns the first)

The new constructor lets you create a new YAWF::Object::MongoDB object.

The first syntax creates a new, empty item while the others return an existing item from the database or undef if nothing was found.

get_column

$object->get_column($key);

Returns the current value of any key, no matter if it has been predefined.

set_column

$object->set_column($key,$value);

Assign a new value to a key, no matter if it has been predefined. Returns the new value.

getset_column

$object->getset_column($key);
$object->getset_column($key,$value);

Returns the current value of any key, no matter if it has been predefined.

Sets the current values (and returns the new one) if a value (including undef) is given as the second argument.

changed

$object->changed($key);

Flags column $key as changed (will be flushed on next ->flush call).

id

$object->id;

Returns the unique document id.

flush

$object->flush;

Write a YAWF object into the database with automatic selection of insert or update depending on the objects state (new or existing).

Changes the variable used to call the method to the new object and also returns the new object.

delete

$object->delete;

Remove a document from the database.

to_time

my $timestamp = $object->to_time($time_column);

Convertes an database timestamp to an unixtime value.

from_time

my $timestamp = $object->from_time($time_column,$timestamp);

Inserts a timestamp into the database (converting it to database format).

INTERNAL METHODS

Advoid calling them directly unless you really know what you're doing.

import

Copy some 'use' arguments to internal structures.

_unify

Reduce the parent object to a class name.

_server_name

Get the current server name string

_server

Get a server connection handler

_database_name

Get the current database name string

_database

Get a database handler

_collection

Get a collection handler

_resolv_sort

Resolv order_by - argument of ->list

_fetchgroup

Fetch a group of fields from the database, no return value.

DEBUGGING

Set environment variable YAWF_MONGODB_TRACE to 1 to enable debug warn's to STDERR.

AUTHOR

Sebastian Willing, <sewi at cpan.org>

BUGS

Please report any bugs or feature requests to bug-yawf-object-mongodb at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=YAWF-Object-MongoDB. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc YAWF::Object::MongoDB

You can also look for information at:

ACKNOWLEDGEMENTS

LICENSE AND COPYRIGHT

Copyright 2011 Sebastian Willing.

This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.

See http://dev.perl.org/licenses/ for more information.