NAME

MongoDBx::Protocol - pure perl implementation of MongoDB protocol

VERSION

version 0.03

SYNOPSIS

    my $p = MongoDBx::Protocol->new;
    my $msg = $p->insert({
        header => { requestID => 3, responseTo => 2 },
        fullCollectionName => 'test.test',
        documents => [ { a => b }, { c => d } ],
    });
    my $sock = IO::Socket::INET->new(
        PeerAddr => 'localhost', PeerPort => 27017, Proto => 'tcp'
    );
    $sock->print($msg);

DESCRIPTION

This is a pure perl implementation of MongoDB protocol as described at http://www.mongodb.org/display/DOCS/Mongo+Wire+Protocol. Such modules as MongoDB and AnyMongo haven't public API for dealing with MongoDB protocol at low level. Using MongoDBx::Protocol you can encode/decode messages which you can send/recieve to/from MongoDB.

This module doesn't try to work very effectively, for this purposes you should use some XS code from MongoDB module.

For encoding and decoding BSON documents this module uses BSON module.

METHODS

All encoding/decoding methods takes/returns hashref. See the key names for hashes and detailed description of this keys at MongoDB site.

new()

Creates new instance of MongoDBx::Protocol.

update($options)

Returns binary string that represents updating a documents in MongoDB.

$options is a hashref that contains following keys:

header (optional)

Hashref with requestID and responseTo keys. Default value for this keys is 0.

flags (optional)

Hashref with possible flags Upsert, MultiUpdate.

fullCollectionName

Fully qualified name of colllection (for example, "foo.bar").

selector

Hashref that will be passed to BSON module for encoding to BSON document.

This hashref represents the query to select the document.

update

Hashref with specification of the update to perform.

insert($options)

$options contains:

header (optional)

flags (optional)

Possible flag is ContinueOnError.

fullCollectionName

documents

Arrayref of documents that will be encoded to BSON.

query($options)

$options contains:

header (optional)

flags (optional)

Possible flags are: TailableCursor, SlaveOk, OplogReplay, NoCursorTimeout, AwaitData, Exhaust, Partial.

fullCollectionName

numberToSkip (optional)

Default is 0.

numberToReturn (optional)

Default is 1.

query

returnFieldSelector (optional)

Which fields will be returned.

getmore($options)

$options contains:

header(optional)

fullCollectionName

numberToReturn (optional)

Default is 1.

cursorID

64-bit cursorID recieved from MongoDB during OP_QUERY.

delete($options)

$options contains:

header (optional)

fullCollectionName

flags (optional)

Possible flag is SingleRemove.

selector

kill_cursors($options)

$options contains:

header (optional)

cursorIDs

Arrayref of cursorIDs.

msg($options)

$options contains:

header (optional)

message

String with message.

MongoDB docs marked this method as deprecated for clients.

reply($options)

$options contains:

header (optional);

responseFlags (optional)

Possible flags are: CursorNotFound, QueryFailure, ShardConfigStale, AwaitCapable.

cursorID

startingFrom (optional)

Default is 0.

documents

Arrayref of documents.

decode($data, $options)

Opposite to encode methods. Takes binary string $data and returns hashref with parsed data in the same format as it uses to encode.

$options is a hashref. Now it can contain ixhash flag, it says that documents should be returned as Tie::IxHash for preserving keys order in the hash.

KNOWN BUGS

Works only on 64-bit Perl. I'll fix it soon.

SEE ALSO

http://www.mongodb.org/display/DOCS/Mongo+Wire+Protocol

BSON, MongoDB, AnyMongo

AUTHOR

Yury Zavarin <yury.zavarin@gmail.com>

COPYRIGHT AND LICENSE

This software is copyright (c) 2011 by Yury Zavarin.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.