package MongoDBx::Class;
BEGIN {
  $MongoDBx::Class::VERSION = '0.5';
}

# ABSTRACT: Flexible ORM for MongoDB databases

use Moose;
use Moose::Util::TypeConstraints;
use namespace::autoclean;
use MongoDB 0.40;
use MongoDBx::Class::Connection;
use MongoDBx::Class::Database;
use MongoDBx::Class::Collection;
use MongoDBx::Class::Cursor;
use MongoDBx::Class::Reference;
use MongoDBx::Class::Meta::AttributeTraits;
use Carp;

# let's set some internal subtypes we can use to automatically coerce
# objects when expanding documents.
subtype 'MongoDBx::Class::CoercedReference'
	=> as 'MongoDBx::Class::Reference';

subtype 'ArrayOfMongoDBx::Class::CoercedReference'
	=> as 'ArrayRef[MongoDBx::Class::Reference]';

coerce 'MongoDBx::Class::CoercedReference'
	=> from 'Object'
	=> via { $_->isa('MongoDBx::Class::Reference') ? $_ : MongoDBx::Class::Reference->new(ref_coll => $_->_collection->name, ref_id => $_->_id, _collection => $_->_collection, _class => 'MongoDBx::Class::Reference') };

coerce 'ArrayOfMongoDBx::Class::CoercedReference'
	=> from 'ArrayRef[Object]'
	=> via {
		my @arr;
		foreach my $i (@$_) {
			push(@arr, $i->isa('MongoDBx::Class::Reference') ? $i : MongoDBx::Class::Reference->new(ref_coll => $i->_collection->name, ref_id => $i->_id, _collection => $i->_collection, _class => 'MongoDBx::Class::Reference'));
		}
		return \@arr;
	};

=head1 NAME

MongoDBx::Class - Flexible ORM for MongoDB databases

=head1 VERSION

version 0.5

=head1 SYNOPSIS

	use MongoDBx::Class;

	# create a new instance of the module and load a model schema
	my $dbx = MongoDBx::Class->new(namespace => 'MyApp::Model::DB');

	# connect to a MongoDB server
	$dbx->connect(host => 'localhost', port => 27017);

	# be safe by default
	$dbx->conn->safe(1);

	# get a MongoDB database
	my $db = $dbx->conn->get_database('people');

	# insert a person
	my $person = $db->insert({ name => 'Some Guy', birth_date => '1984-06-12', _class => 'Person' });

	print "Created person ".$person->name." (".$person->id.")\n";

	$person->update({ name => 'Some Smart Guy' });

	$person->delete;

=head1 DESCRIPTION

WARNING: THIS IS ALPHA SOFTWARE.

L<MongoDBx::Class> is a flexible object relational mapper (ORM) for
L<MongoDB> databases. Given a schema-like collection of document classes,
MongoDBx::Class expands MongoDB objects (hash-refs in Perl) from the
database into objects of those document classes, and collapses such objects
back to the database.

MongoDBx::Class takes advantage of the fact that Perl's L<MongoDB> driver
is L<Moose>-based to extend and tweak the driver's behavior, instead of
wrapping it. This means MongoDBx::Class does not define its own syntax,
so you simply use it exactly as you would the L<MongoDB> driver directly.
That said, MongoDBx::Class adds some sugar that enhances and simplifies
the syntax unobtrusively (either use it or don't). Thus, it is relatively
easy to convert your current L<MongoDB> applications to MongoDBx::Class.
A collection in MongoDBx::Class C<isa('MongoDB::Collection')>, a database
in MongoDBx::Class C<isa('MongoDB::Database')>, etc.

As opposed to other ORMs (even non-MongoDB ones), MongoDBx::Class attempts
to stay as close as possible to MongoDB's non-schematic nature. While most
ORMs enforce using a single collection (or table in the SQL world) for
every object class, MongoDBx::Class allows you to store documents of
different classes in different collections (and even databases). A collection
can hold documents of many different classes. Not only that, as MongoDBx::Class
is Moose based, you can easily create very flexible schemas by using
concepts such as inheritance and L<roles|Moose::Role>. For example, say
you have a collection called 'people' with documents representing, well,
people, but these people can either be teachers or students. Also, students
may assume the role "hall monitor". With MongoDBx::Class, you can create
a common base class, say "People", and two more classes that extend it - 
"Teacher" and "Student" with attributes that are only relevant to each one.
You also create a role called "HallMonitor", possibly with some methods
of its own. You can save all these "people documents" into a single
MongoDB collection, and when fetching documents from that collection,
they will be properly expanded to their correct classes (though you will
have to apply roles yourself - at least for now).

=head2 COMPARISON WITH OTHER MongoDB ORMs

As MongoDB is rather young, there aren't many options out there, though
CPAN has some pretty good ones, and will probably have more as MongoDB
popularity rises.

The first MongoDB ORM in CPAN was L<Mongoose>, and while it's a very good
ORM, MongoDBx::Class was mainly written to overcome some limitations of
Mongoose. The biggest of these limitations is that in order to provide a
more comfortable syntax than MongoDB's native syntax, Mongoose makes the
unfortunate decision of being implemented as a L<singleton|MooseX::Singleton>,
meaning only one instance of a Mongoose-based schema can be used in an
application. That essentially kills multithreaded applications. Say you
have a L<Plack>-based (doesn't have to be Plack-based though) web application
deployed via L<Starman> (or any other web server for that matter), which
is a pre-forking web server - you're pretty much doomed. As
L<MongoDB's driver|MongoDB::Connection/"Multithreading"> states, it doesn't
support connection pooling, so every fork has to have its own connection
to the MongoDB server. Mongoose being a singleton means your threads will
not have a connection to the server, and you're screwed. MongoDBx::Class
does not suffer this limitation. You can start as many connections as you
like. If you're running in a pre-forking environment, you don't have to
worry about it at all.

Other differences from Mongoose include:

=over

=item * Mongoose creates its own syntax, MongoDBx::Class doesn't, you
use L<MongoDB>'s syntax directly.

=item * A document class in Mongoose is connected to a single collection
only, and a collection can only have documents of that class. MongoDBx::Class
doesn't have that limitation. Do what you like.

=item * Mongoose has limited support for multiple database usage.
With MongoDBx::Class, you can use as many databases as you want.

=item * MongoDBx::Class is way faster. While I haven't performed any real
benchmarks, an application converted from Mongoose to MongoDBx::Class
showed an increase of speed in orders of magnitude.

=item * In Mongoose, your document class attributes are expected to be
read-write (i.e. C<< is => 'rw' >> in Moose), otherwise expansion will fail.
This is not the case with MongoDBx::Class, your attributes can safely be
read-only.

=back

Another ORM for MongoDB is L<Mongrel>, which doesn't use Moose and is thus
lighter (though as L<MongoDB> is already Moose-based, I see no benefit here).
It uses L<Oogly> for data validation (while Moose has its own type validation),
and seems to define its own syntax as well. Unfortunately, documentation
is currently lacking, and I haven't given it a try, so I can't draw
specific comparisons here.

Even before Mongoose was born, you could use MongoDB as a backend for
L<KiokuDB>, by using L<KiokuDB::Backend::MongoDB>. However, KiokuDB is
considered a database of its own and uses some conventions which doesn't
fit well with MongoDB. L<Mongoose::Intro|Mongoose::Intro/"Why not use KiokuDB?">
already gives a pretty convincing case when and why you should or shouldn't
want to use KiokuDB.

=head2 CAVEATS AND THINGS TO CONSIDER

There are a few caveats and important facts to take note of when using
MongoDBx::Class as of today:

=over 4

=item * It's alpha software. This is an early release, and bugs are found
(and fixed) all the time. Don't rely on it for production use yet. You have
been warned.

=item * MongoDBx::Class's flexibility is dependant on its ability to recognize
which class a document in a MongoDB collection expands to. Currently,
MongoDBx::Class requires every document to have an attribute called "_class"
that contains the name of the document class to use. This isn't very
comfortable, but works. I'm still thinking of ways to expand documents
without this. This pretty much means that you will have to perform
some preparations to use existing MongoDB database with MongoDBx::Class - 
you will have to update every document in the database with the "_class"
attribute.

=item * References (representing joins) are expected to be in the DBRef
format, as defined in L<http://www.mongodb.org/display/DOCS/Database+References>.
If your database references aren't in this format, you'll have to convert
them first.

=item * The '_id' attribute of all your documents has to be an internally
generated L<MongoDB::OID>. This limitation may or may not be lifted in
the future.

=back

=head2 TUTORIAL

To start using MongoDBx::Class, please read L<MongoDBx::Class::Tutorial>.
It also contains a list of frequently asked questions.

=head1 ATTRIBUTES

=cut

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

has 'conn' => (is => 'ro', isa => 'MongoDB::Connection', predicate => 'is_connected', writer => '_set_conn', clearer => '_clear_conn');

has 'doc_classes' => (is => 'ro', isa => 'HashRef', default => sub { {} });

=head2 namespace

A string representing the namespace of the MongoDB schema used (e.g.
C<MyApp::Schema>). Your document classes, structurally speaking, should be
descendants of this namespace (e.g. C<MyApp::Schema::Article>,
C<MyApp::Schema::Post>).

=head2 conn

The object's connection to a MongoDB server. This is a L<MongoDBx::Class::Connection>
object (which extends L<MongoDB::Connection>). This is set only after the
C<connect()> method is called.

=head2 doc_classes

A hash-ref of document classes found when loading the schema.

=head1 CLASS METHODS

=head2 new( namespace => $namespace )

Creates a new instance of this module. Requires the namespace of the
database schema to use. The schema will be immediately loaded, but no
connection to a MongoDB server is made yet.

=head1 OBJECT METHODS

=head2 connect( [ host => $host, [ port => $port ] ] )

Initiates a new connection to a MongoDB server running on a certain host
and listening to a certain port. If a host is not provided, 'localhost'
is used. If a port is not provided, 27017 (MongoDB's default port) is
used. The database name is required. The created L<MongoDBx::Connection>
object is both returned, and also saved in the calling object's 'conn'
attribute.

=cut

sub connect {
	my ($self, %opts) = @_;

	$opts{host} ||= 'localhost';
	$opts{port} ||= 27017;

	my $conn = MongoDBx::Class::Connection->new(host => $opts{host}, port => $opts{port}, namespace => $self->namespace, doc_classes => $self->doc_classes);

	$self->_set_conn($conn);

	return $conn;
}

=head1 INTERNAL METHODS

The following methods are only to be used internally.

=head2 BUILD()

Automatically called when creating a new instance of this module. This
loads the schema and saves a hash-ref of document classes found in the object.
Automatic loading courtesy of L<Module::Pluggable>.

=cut

sub BUILD {
	my $self = shift;

	# load the classes
	require Module::Pluggable;
	Module::Pluggable->import(search_path => [$self->namespace], require => 1, sub_name => '_doc_classes');
	foreach ($self->_doc_classes) {
		my $name = $_;
		$name =~ s/$self->{namespace}:://;
		$self->doc_classes->{$name} = $_;
	}
}

=head1 TODO

=over 6

=item * Improve the tests.

=item * Make the C<isa> option in L<MongoDBx::Class::Moose>'s relationship
types consistent. Either use the full package names or the short class names.

=item * Add support for the L<AnyMongo> driver.

=item * Add support for document attributes which are not to be saved in the database.

=item * Try to find a way to not require documents to have the _class attribute.

=back

=head1 AUTHOR

Ido Perlmuter, C<< <ido at ido50.net> >>

=head1 BUGS

Please report any bugs or feature requests to C<bug-mongodbx-class at rt.cpan.org>, or through
the web interface at L<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=MongoDBx-Class>. I will be notified, and then you'll
automatically be notified of progress on your bug as I make changes.

=head1 SUPPORT

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

	perldoc MongoDBx::Class

You can also look for information at:

=over 4

=item * RT: CPAN's request tracker

L<http://rt.cpan.org/NoAuth/Bugs.html?Dist=MongoDBx::Class>

=item * AnnoCPAN: Annotated CPAN documentation

L<http://annocpan.org/dist/MongoDBx::Class>

=item * CPAN Ratings

L<http://cpanratings.perl.org/d/MongoDBx::Class>

=item * Search CPAN

L<http://search.cpan.org/dist/MongoDBx::Class/>

=back

=head1 SEE ALSO

L<MongoDB>, L<Mongoose>, L<Mongrel>, L<KiokuDB::Backend::MongoDB>.

=head1 ACKNOWLEDGEMENTS

Rodrigo de Oliveira, author of L<Mongoose>, whose code greatly assisted
me in writing MongoDBx::Class.

=head1 LICENSE AND COPYRIGHT

Copyright 2010 Ido Perlmuter.

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.

=cut

__PACKAGE__->meta->make_immutable;