/ 
Couchbase-2.0.0_3
River stage zero No dependents
/ Couchbase::Document

NAME

Couchbase::Document - Object represnting an item in the cluster.

SYNOPSIS

my $doc = Couchbase::Document->new("id_string", ["content"]);

DESCRIPTION

A document is the basic unit of the API and corresponds with an item as it is stored in the cluster. A newly created document exists only locally in the application, and must be submitted to the cluster via one of the methods in Couchbase::Bucket

CONSTRUCTORS

new($id)

new($id, $value, $options)

Creates a new document object. A document object must have a non-empty ID which is used to associate this object with the relevant item on the cluster. If you desire to store the document on the cluster, you will also need to supply a value for the document.

Additional options may also be specified in the $options hashref. The value for the options may also be set individually by accessor methods documented below.

PROPERTIES

id()

Gets/Sets the ID for this document. The ID should only be set during creation of the document object.

value()

value($new_value)

Gets or sets the new value of the document. The value may be anything that can be encoded according to the document's "format()" property.

When retrieving a document (via the get() method of Couchbase::Bucket), this field will be updated with the value stored on the server, if successful.

format()

format($format)

Get and set the storage format for the item's value on the cluster. Typical applications will not need to modify this value, but it may be desirable to use a special format for performance reasons, or to store values which are not representable in the default format.

Formats may be set either by specifying their numeric constants, or using a string alias. The following formats are recognized:

COUCHBASE_FMT_JSON, "json"

Stores the item as JSON. This is the default format and allows the value to be indexed by view queries. The value for the document must be something encodable as JSON, thus hashes, arrays, and simple scalars are acceptable, while references to strings, numbers, and similar are not.

COUCHBASE_FMT_STORABLE, "storable"

Encodes the value using the freeze method of Storable. Use this format only for values which cannot be encoded as JSON. Do not use this format if you wish this value to be readable by non-Perl applications.

COUCHBASE_FMT_RAW, "raw"

Stores the item as is, and marks it as an opaque string of bytes.

COUCHBASE_FMT_UTF8, "utf8"

Stores the string as is, but flags it on the server as UTF-8. Note that no client-side validation is made to ensure the value is indeed a legal UTF-8 sequence.

The goal of this format is mainly to indicate to other languages (for example, Python or Java) which distinguish between bytes and strings that the stored value is a string. For Perl this is effectively like the COUCHBASE_FMT_RAW format, except that when retrieving the value, the utf8 flag is set on the scalar.

expiry()

expiry($seconds)

Specify the expiration value to be associated with the document. This value is only read from and never written to, and is used to determine the "Time to live" for the document. See "touch($doc)" in Couchbase::Document

ERROR CHECKING

is_ok()

Returns a boolean indicating whether the last operation performed on the cluster was successful or not. You may inspect the actual error code (and message) by using the "errnum()" and "errstr()" methods.

errnum()

Returns the numerical error code of the last operation. An error code of 0 means the operation was successful. Other codes indicate other errors. There are also some convenient methods (below) to check for common error conditions.

Some of the error codes are documented in Couchbase::Constants.

errstr()

Returns a textual description of the error. This should be used for informational purposes only

is_not_found()

Returns true if the last operation failed because the document did not exist on the cluster

is_cas_mismatch()

Returns true if the last operation failed because the local document contains a stale state. If this is true, the value should typically be retrieved, or the ignore_cas option should be used in the operation.

is_already_exists()

Returns true if the last operation failed because the item already existed in the cluster. Check this on an insert operation.