package MongoDB::DBRef;

# ABSTRACT: Native DBRef support

use Moose;
use Carp 'croak';

# no type constraint since an _id can be anything
has id => (
    is        => 'rw',
    required  => 1 
);

has ref => (
    is        => 'rw',
    isa       => 'Str',
    required  => 1
);

has db => ( 
    is        => 'rw',
    isa       => 'Str',
    required  => 0
);

has client => (
    is        => 'ro',
    isa       => 'MongoDB::MongoClient',
    required  => 0
);

sub fetch { 
    my $self = shift;

    croak "Can't fetch DBRef without a MongoClient. Specify a 'client' attribute."
      unless $self->client;

    


1;


__END__

=head1 NAME

MongoDB::DBRef - A MongoDB database reference

=head1 SYNOPSIS

    my $dbref = MongoDB::DBRef->new( ref => 'my_collection', id => 123 );
    $coll->insert( { foo => 'bar', other_doc => $dbref } );

    my $other_doc = $coll->find_one( { foo => 'bar' } )->{other_doc}->fetch;

=head1 DESCRIPTION

This module provides support for database references (DBRefs) in the Perl 
MongoDB driver. A DBRef is a special embedded document which points to 
another document in the database. DBRefs are not the same as foreign keys
and do not provide any referential integrity or constraint checking. For example,
a DBRef may point to a document that no longer exists (or never existed.)

=head1 ATTRIBUTES

=head2 db

Optional. The database in which the referenced document lives. If this 
attribute is not specified, the current database is assumed.

=head2 ref

The collection in which the referenced document lives. This attribute is required.

=head2 id

The C<_id> value of the referenced document. This attribute is required. If the 
C<_id> is an ObjectID, then you must use a L<MongoDB::OID> object.

=head2 client

Optional. A L<MongoDB::MongoClient> object to be used to fetch the referenced document
from the database. You must supply this attribute if you want to use the C<fetch> method.

When you retrieve a document from MongoDB, any DBRefs will automatically be inflated
into C<MongoDB::DBRef> objects with the C<client> attribute automatically populated.

It is not necessary to specify a C<client> if you are just making DBRefs to insert
in the database as part of a larger document.