NAME

CouchDB::Client::Doc - CouchDB::Client document

SYNOPSIS

        $doc->data->{foo} = 'new bar';
        $doc->addAttachment('file.xml', 'application/xml', '<foo/>);
        $doc->update;
        $doc->delete;

DESCRIPTION

This module represents documents in the CouchDB database.

We don't yet deal with a number of options such as retrieving revisions and revision status.

METHODS

new

Constructor. Takes a hash or hashref of options: db which is the parent CouchDB::Client::DB object and is required; the document's id and rev if known; a hashref of data being the content; and a hashref of attachements if present.

The id field must be a valid document name (CouchDB accepts anything, but things that are not URI safe have not been tested yet).

The rev field must be a valid CouchDB revision, it is recommended that you only touch it if you know what you're doing.

The data field is a normal Perl hashref that can have nested content. Its keys must not contain fields that being with an underscore (_) as those are reserved for CouchDB.

The attachments field must be structured in the manner that CouchDB expects. It is a hashref with attachment names as its keys and hashrefs as values. The latter have content_type and data fields which are the MIME media type of the content, and the data in single-line Base64. It is recommended that you manipulate this through the helpers instead.

It is not recommended that this constructor be used directly, but rather that <<CouchDB::Client::DB-newDoc>>> be used instead.

id

Read-only accessor for the ID.

rev

Read-only accessor for the revision.

data

Read-write accessor for the content. See above for the constraints on this hasref. Note that this only changes the data on the client side, you have to create/update the object for it to be stored.

attachments

Read-write accessor for the attachments. See above for the constraints on this hasref. Note that this only changes the attachments on the client side, you have to create/update the object for it to be stored.

uriName

Returns the path part for this object (if it has an ID, otherwise undef).

create

Causes the document to be created in the DB. It will throw an exception if the object already has a revision (since that would indicate that it's already in the DB) or if the actual storage operation fails.

If the object has an ID it will PUT it to the URI, otherwise it will POST it and set its ID based on the result. It returns itself, with the rev field updated.

contentForSubmit

A helper that returns a data structure matching that of the JSON that will be submitted as part of a create/update operation.

retrieve

Loads the document from the database, initialising all its fields in the process. Will throw an exception if the document cannot be found, or for connection issues. It returns the object.

Note that the attachments field if defined will contain stubs and not the full content. Retrieving the actual data is done using fetchAttachment.

update

Same as create but only operates on documents already in the DB.

delete

Deletes the document and resets the object (updating its rev). Returns the object (which is still perfectly usable). Throws an exception if the document isn't found, or for connection issues.

fetchAttachment $NAME

Fetches the attachment with the given name and returns its content. Throws an exception if the attachment cannot be retrieved, or if the object had no knowledge of such an attachment.

addAttachment $NAME, $CONTENT_TYPE, $DATA

Adds an attachment to the document with a given name, MIME media type, and data. The data is the original, not the Base64 version which is handled internally. The object is returned.

deleteAttachment $NAME

Deletes an attachment from the document. Note that this only removes the attachment on the client side, you have to update the object for it to be removed from the DB.

Throws an exception if the document does not contain an attachment by that name.

toBase64 $DATA

A simple helper that returns data in Base64 of a form acceptable to CouchDB (on a single line).

retrieveFromRev $REV

Fetches a specific revision of a document, and returns it as a new Doc object. This is to avoid destroying your own Doc object. Throws exceptions if it can't connect or find the document.

revisionsInfo

Returns an arrayref or hashresf indicating the rev of previous revisions and their status (being disk, missing, deleted). Throws exceptions if it can't connect or find the document.

TODO

Handling of attachments could be improved by not forcing the data into memory at all times. Also, an option to turn the attachments into stubs after they have been saved would be good.

AUTHOR

Robin Berjon, <robin @t berjon d.t com> Maverick Edwards, <maverick @t smurfbane d.t org> (current maintainer)

BUGS

Please report any bugs or feature requests to bug-couchdb-client at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=CouchDB-Client.

COPYRIGHT & LICENSE

Copyright 2008 Robin Berjon, all rights reserved.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.8 or, at your option, any later version of Perl 5 you may have available.