view release on metacpan or  search on metacpan

lib/MongoDBx/Class/Connection.pm  view on Meta::CPAN

MongoDBx::Class::Connection - A connection to a MongoDB server

=head1 VERSION

version 1.030002

=head1 EXTENDS

L<MongoDB::Connection>

=head1 SYNOPSIS

	# connect to a MongoDB server
	my $conn = $mongodbx->connect(host => '10.10.10.10', port => 27017);

	# the connection object is automatically saved to the 'conn'
	# attribute of the L<MongoDBx::Class> object (C<$mongodbx> above)

	$conn->get_database('people');

=head1 DESCRIPTION

MongoDBx::Class::Connection extends L<MongoDB::Connection>. This class
provides the document expansion and collapsing methods that are used
internally by other MongoDBx::Class classes.

Note that a L<MongoDBx::Class> object can only have one connection at a
time. Connection is only made via the C<connect()> method in MongoDBx::Class.

=head1 ATTRIBUTES

Aside for attributes provided by L<MongoDB::Connection>, the following
special attributes are added:

=head2 namespace

A string representing the namespace of document classes to load (e.g.
MyApp::Schema). This is a required attribute (automatically received from
the MongoDBx::Class object).

=head2 doc_classes

A hash-ref of document classes loaded. This is a required attribute
(automatically received from the MongoDBx::Class object).

=head2 safe

A boolean value indicating whether to use safe operations (e.g. inserts
and updates) by default - without the need to pass C<< { safe => 1 } >> to
relevant methods - or not. False by default.

=head2 is_backup

This boolean attribute is used by L<MongoDBx::Class::ConnectionPool> objects
that use a backup connection.

=cut

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

has 'doc_classes' => (is => 'ro', isa => 'HashRef', required => 1);

has 'safe' => (is => 'rw', isa => 'Bool', default => 0);

has 'is_backup' => (is => 'ro', isa => 'Bool', default => 0);

=head1 OBJECT METHODS

Aside from the methods provided by L<MongoDB::Connection>, the following
methods and modifications are added:

=head2 get_database( $name )

Returns a L<MongoDBx::Class::Database> object representing the MongoDB
database named C<$name>.

=cut

override 'get_database' => sub {
	my $conn_key = version->parse($MongoDB::VERSION) < v0.502.0 ? '_connection' : '_client';

	MongoDBx::Class::Database->new($conn_key => shift, name => shift);
};

=head2 safe( $boolean )

Overrides the current value of the safe attribute with a new boolean value.

=head2 expand( $coll_ns, \%doc )

Receives the full name (a.k.a namespace) of a collection (that is the database
name, followed by a dot, and the collection name), and a document hash-ref,
and attempts to expand it according to the '_class' attribute that should
exist in the document. If it doesn't exist, the document is returned as
is.

This is mostly used internally and you don't have to worry about expansion,
it's done automatically.

=cut

sub expand {
	my ($self, $coll_ns, $doc) = @_;

	# make sure we've received the namespace and a hash-ref document
	return unless $coll_ns && $doc && ref $doc eq 'HASH';

	# extract the database name and the collection name from the namespace
	my ($db_name, $coll_name) = ($coll_ns =~ m/^([^.]+)\.(.+)$/);

	# get the collection
	my $coll = $self->get_database($db_name)->get_collection($coll_name);

	# return the document as is if it doesn't have a _class attribute
	return $doc unless $doc->{_class};

	# remove the schema namespace from the document class (we do not
	# use the full package name internally) and attempt to find that
	# document class. return the document as is if class isn't found
	my $dc_name = $doc->{_class};
	my $ns = $self->namespace;