Object.php

<?php

namespace riiak;

use \CComponent,
    \CJSON,
    \Exception,
    \Yii;

/**
 * The Object holds meta information about a Riak object, plus the
 * object's data.
 * @package riiak
 *
 * Magic properties
 *
 * @property string $contentType
 * @property mixed $data
 * @property bool $exists
 * @property array[string]string $meta
 * @property array[string][int]string|int $indexes
 * @property array[string]string $autoIndexes
 * @property array[int]string $siblings
 *
 * @property-read int $httpCode Status code of response
 * @property-read string $httpStatus Status msg response
 * @property-read bool $hasSiblings
 * @property-read int $siblingCount
 * @property-read array[int]Link $links
 * @property-read MapReduce $mapReduce
 * @property-read string $vclock
 */
class Object extends CComponent {

    /**
     * Client instance
     *
     * @var Riiak
     */
    public $client;

    /**
     * Bucket
     *
     * @var Bucket
     */
    public $bucket;

    /**
     * Key
     *
     * @var string
     */
    public $key;

    /**
     * Whether or not to treat object as json
     *
     * @var bool
     */
    public $jsonize = true;

    /**
     * @var array
     */
    public $headers = array();

    /**
     * Array of Links
     *
     * @var array[int]Link
     */
    protected $_links = array();

    /**
     * Array of vtags
     *
     * @var array[int]string
     */
    protected $_siblings = array();

    /**
     * Whether the object exists
     *
     * @var bool
     */
    protected $_exists = false;

    /**
     * If constructed by newBinary|getBinary, returns string.
     * If not a string, will be JSON encoded when stored
     *
     * @var mixed
     */
    protected $_data;

    /**
     * @var array[string]string
     */
    protected $_meta = array();

    /**
     * @var array[string][int]string|int
     */
    protected $_indexes = array();

    /**
     * @var array[string]string
     */
    protected $_autoIndexes = array();

    /**
     * Construct a new Object
     *
     * @param Riiak $client A Riiak object
     * @param Bucket $bucket A Bucket object
     * @param string $key Optional - If empty, generated upon store()
     */
    public function __construct(Riiak $client, Bucket $bucket, $key = null) {
        $this->client = $client;
        $this->bucket = $bucket;
        $this->key = $key;
    }

    /**
     * Returns HTTP status code of last operation
     *
     * @return int
     */
    public function getHttpCode() {
        return $this->headers['http_code'];
    }

    /**
     * Returns HTTP status msg of last operation
     *
     * @return string
     */
    public function getHttpStatus() {
        return $this->headers['http_status'];
    }

    /**
     * Returns the object's content type
     *
     * @return string
     */
    public function getContentType() {
        return $this->headers['content-type'];
    }

    /**
     * Set the object's content type
     *
     * @param string $contentType The new content type
     * @return Object
     */
    public function setContentType($contentType) {
        $this->headers['content-type'] = $contentType;
        return $this;
    }

    /**
     * Returns the object's data
     *
     * @return mixed
     */
    public function getData() {
        return $this->_data;
    }

    /**
     * Set the object's data
     *
     * @param mixed $data The new data value
     * @return Object
     */
    public function setData($data) {
        $this->_data = $data;
        return $this;
    }

    /**
     * Get whether the object exists
     *
     * @return bool
     */
    public function getExists() {
        return $this->_exists;
    }

    /**
     * Set whether the object exists
     *
     * @param bool $bool
     * @return Object
     */
    public function setExists($bool) {
        $this->_exists = (bool) $bool;
        return $this;
    }

    /**
     * Add a link to a Object
     *
     * @param Link|Object $obj Either Object or Link
     * @param string $tag optional link tag. Default: bucket name. Ignored for Link
     * @return Object
     */
    public function addLink($obj, $tag = null) {
        if ($obj instanceof Link)
            $newlink = $obj;
        else
            $newlink = new Link($obj->bucket->name, $obj->key, $tag);

        $this->removeLink($newlink);
        $this->_links[] = $newlink;

        return $this;
    }

    /**
     * Remove a link to a Object
     *
     * @param Link|Object $obj Either Object or Link
     * @param string $tag optional link tag. Default: bucket name. Ignored for Link
     * @return Object
     */
    public function removeLink($obj, $tag = null) {
        if ($obj instanceof Link)
            $oldlink = $obj;
        else
            $oldlink = new Link($obj->bucket->name, $obj->key, $tag);

        foreach ($this->_links as $k => $link)
            if (!$link->isEqual($oldlink))
                unset($this->_links[$k]);

        return $this;
    }

    /**
     * Return an array of Link objects
     *
     * @return array
     */
    public function getLinks() {
        /**
         * Set the clients before returning
         */
        foreach ($this->_links as $link)
            $link->client = $this->client;

        return $this->_links;
    }

    /** @section Indexes */

    /**
     * @param array $array
     * @param string $name
     * @param string|int $value
     * @param 'int'|'bin' $type optional
     * @return Object
     */
    protected function _addIndex(array &$array, $name, $value, $type = null) {
        $index = strtolower($name . ($type !== null ? '_' . $type : ''));
        if (!isset($array[$index]))
            $array[$index] = array();

        /**
         * Riak de-dupes, but _addIndex is also used for autoIndex management
         */
        if (!in_array($value, $array[$index]))
            $array[$index][] = $value;

        return $this;
    }

    /**
     * @param array $array
     * @param string $name
     * @param array|string|int $value
     * @param 'int'|'bin' $type optional
     * @return Object
     */
    protected function _setIndex(array &$array, $name, $value, $type = null) {
        $index = strtolower($name . ($type !== null ? '_' . $type : ''));

        $array[$index] = $value;

        return $this;
    }

    /**
     * @param array $array
     * @param string $name
     * @param 'int'|'bin' $type optional
     * @return bool
     */
    protected function _hasIndex(array &$array, $name, $type = null) {
        $index = strtolower($name . ($type !== null ? '_' . $type : ''));
        return isset($array[$index]);
    }

    /**
     * @param array $array
     * @param string $name
     * @param 'int'|'bin' $type optional
     * @return array|string|int
     */
    protected function _getIndex(array &$array, $name, $type = null) {
        $index = strtolower($name . ($type !== null ? '_' . $type : ''));

        if (!isset($array[$index]))
            return null;

        return $array[$index];
    }

    /**
     * @param array $array
     * @param string $name
     * @param 'int'|'bin' $type optional
     * @param string|int $value optional Explicit value to remove
     * @return Object
     */
    protected function _removeIndex(array &$array, $name, $type = null, $value = null) {
        $index = strtolower($name . ($type !== null ? '_' . $type : ''));

        if (isset($array[$index]))
            if ($value !== null) {
                if (is_array($array[$index]) && false !== ($position = array_search($value, $array[$index])))
                    unset($array[$index][$position]);
            }else{
                unset($array[$index]);
            }

        return $this;
    }

    /**
     * @param array $array
     * @param string $name
     * @param 'int'|'bin' $type optional
     * @return Object
     */
    protected function _removeAllIndexes(array &$array, $name = null, $type = null) {
        if ($name === null)
            $array = array();
        else if ($type !== null)
            unset($array[strtolower($name . '_' . $type)]);
        else {
            $name = strtolower($name);
            unset($array[$name . '_int']);
            unset($array[$name . '_bin']);
        }

        return $this;
    }

    /**
     * Adds a secondary index to the object
     * This will create the index if it does not exist, or will
     * append an additional value if the index already exists and
     * does not contain the provided value.
     *
     * @param string $name
     * @param 'int'|'bin' $type optional
     * @param string|int $explicitValue optional If provided, uses this
     * value explicitly.  If not provided, this will search the object's
     * data for a data field named $name, and use it's value.
     * @return $this
     */
    public function addIndex($name, $type = null, $explicitValue = null) {
        if ($explicitValue === null)
            return $this->addAutoIndex($name, $type);

        return $this->_addIndex($this->_indexes, $name, $explicitValue, $type);
    }

    /**
     * Sets a given index to a specific value or set of values
     *
     * @param string $name
     * @param array|string|int $value
     * @param 'int'|'bin' $type optional
     * @return $this
     */
    public function setIndex($name, $value, $type = null) {
        return $this->_setIndex($this->_indexes, $name, (array) $value, $type);
    }

    /**
     * @param string $name
     * @param 'int'|'bin' $type optional
     * @return bool
     */
    public function hasIndex($name, $type = null) {
        return $this->_hasIndex($this->_indexes, $name, $type);
    }

    /**
     * Gets the current values for the identified index
     * Note, the NULL value has special meaning - when the object is
     * ->store()d, this value will be replaced with the current value
     * the value of the field matching $indexName from the object's data
     *
     * @param string $name
     * @param 'int'|'bin' $type optional
     *
     * @return array
     */
    public function getIndex($name, $type = null) {
        return $this->_getIndex($this->_indexes, $name, $type);
    }

    /**
     * @param array[string][int]string|int $value
     * @return Object
     */
    public function setIndexes(array $value) {
        $this->_indexes = $value;
        return $this;
    }

    /**
     * @return array[string][int]string|int
     */
    public function getIndexes() {
        return $this->_indexes;
    }

    /**
     * Removes a specific value from a given index
     *
     * @param string $name
     * @param 'int'|'bin' $type optional
     * @param string|int $explicitValue optional
     * @return $this
     */
    public function removeIndex($name, $type = null, $explicitValue = null) {
        return $this->_removeIndex($this->_indexes, $name, $type, $explicitValue);
    }

    /**
     * Bulk index removal
     * If $indexName and $indexType are provided, all values for the
     * identified index are removed.
     * If just $indexName is provided, all values for all types of
     * the identified index are removed
     * If neither is provided, all indexes are removed from the object
     *
     * Note that this function will NOT affect auto indexes
     *
     * @param string $name optional
     * @param 'int'|'bin' $type optional
     *
     * @return $this
     */
    public function removeAllIndexes($name = null, $type = null) {
        return $this->_removeAllIndexes($this->_indexes, $name, $type);
    }

    /** @section Auto Indexes */

    /**
     * Adds an automatic secondary index to the object
     * The value of an automatic secondary index is determined at
     * time of ->store() by looking for an $fieldName key
     * in the object's data.
     *
     * @param string $name
     * @param 'int'|'bin' $type optional
     *
     * @return $this
     */
    public function addAutoIndex($name, $type = null) {
        return $this->_setIndex($this->_autoIndexes, $name, $name, $type);
    }

    /**
     * Returns whether the object has a given auto index
     *
     * @param string $name
     * @param 'int'|'bin' $type optional
     *
     * @return boolean
     */
    public function hasAutoIndex($name, $type = null) {
        return $this->_hasIndex($this->_autoIndexes, $name, $type);
    }

    /**
     * @param array[string]string $value
     * @return Object
     */
    public function setAutoIndexes(array $value) {
        $this->_autoIndexes = $value;
        return $this;
    }

    /**
     * @return array[string]string
     */
    public function getAutoIndexes() {
        return $this->_autoIndexes;
    }

    /**
     * Removes a given auto index from the object
     *
     * @param string $name
     * @param 'int'|'bin' $type optional
     *
     * @return $this
     */
    public function removeAutoIndex($name, $type = null) {
        return $this->_removeIndex($this->_autoIndexes, $name, $type);
    }

    /**
     * Removes all auto indexes
     * If $fieldName is not provided, all auto indexes on the
     * object are stripped, otherwise just indexes on the given field
     * are stripped.
     * If $indexType is not provided, all types of index for the
     * given field are stripped, otherwise just a given type is stripped.
     *
     * @param string $name
     * @param 'int'|'bin' $type optional
     *
     * @return $this
     */
    public function removeAllAutoIndexes($name = null, $type = null) {
        return $this->_removeAllIndexes($this->_autoIndexes, $name, $type);
    }

    /** @section Meta Data */

    /**
     * Gets a given metadata value
     * Returns null if no metadata value with the given name exists
     *
     * @param string $metaName
     *
     * @return string|null
     */
    public function getMetaValue($metaName) {
        $metaName = strtolower($metaName);
        if (isset($this->_meta[$metaName]))
            return $this->_meta[$metaName];
        return null;
    }

    /**
     * Sets a given metadata value, overwriting an existing
     * value with the same name if it exists.
     * @param string $metaName
     * @param string $value
     * @return $this
     */
    public function setMetaValue($metaName, $value) {
        $this->_meta[strtolower($metaName)] = $value;
        return $this;
    }

    /**
     * Removes a given metadata value
     * @param string $metaName
     * @return $this
     */
    public function removeMetaValue($metaName) {
        unset($this->_meta[strtolower($metaName)]);
        return $this;
    }

    /**
     * Gets all metadata values
     * @return array[string]string
     */
    public function getMeta() {
        return $this->_meta;
    }

    /**
     * @param array $value
     * @return Object
     */
    public function setMeta(array $value) {
        $this->_meta = $value;
        return $this;
    }

    /**
     * Strips all metadata values
     * @return $this
     */
    public function removeMeta() {
        $this->_meta = array();
        return $this;
    }

    /**
     * Store the object in Riak. Upon completion, object could contain new
     * metadata, and possibly new data if Riak contains a newer version of
     * the object according to the object's vector clock.
     *
     * @param int $w optional W-Value: X partitions must respond before returning
     * @param int $dw optional DW-Value: X partitions must confirm write before returning
     * @return Object
     */
    public function store($w = null, $dw = null) {
        $params = array('returnbody' => 'true', 'w' => $this->bucket->getW($w), 'dw' => $this->bucket->getDW($dw));
        $response = $this->client->transport->storeObject($this, $params);
        return self::populateResponse($this, $response);
    }

    /**
     * Reload the object from Riak. When this operation completes, the object
     * could contain new metadata and a new value, if the object was updated
     * in Riak since it was last retrieved.
     *
     * @param int $r optional R-Value: X partitions must respond before returning
     * @return Object
     */
    public function reload($r = null) {
        /**
         * Do the request
         */
        $params = array('r' => $this->bucket->getR($r));
        Yii::trace('Reloading object "' . $this->key . '" from bucket "' . $this->bucket->name . '"', 'ext.riiak.Object');
        $response = $this->client->transport->fetchObject($this->bucket, $this->key, $params);
        return self::populateResponse($this, $response);
    }

    /**
     * @param Riiak $client
     * @param array $objects
     * @param int $r optional
     * @return array[string]Object
     */
    public static function reloadMulti(Riiak $client, array $objects, $r = null) {
        Yii::trace('Reloading multiple objects', 'ext.riiak.Object');
        $objects = array_combine(array_map(array('self', 'buildReloadUrl'), $objects, array_fill(0, count($objects), $r)), $objects);

        /**
         * Get (fetch) multiple objects
         */
        $responses = $client->transport->multiGet(array_keys($objects));
        array_walk($objects, function($object, $url)use(&$responses) {
                    Object::populateResponse($object, $responses[$url]);
                });
        return $objects;
    }

    /**
     * @param Object $object
     * @param int $r optional
     * @return string
     */
    protected static function buildReloadUrl(Object $object, $r = null) {
        $params = array('r' => $object->bucket->getR($r));
        return $object->client->transport->buildBucketKeyPath($object->bucket, $object->key, null, $params);
    }

    /**
     * @static
     * @param Object $object
     * @param array $response
     * @return Object
     */
    public static function populateResponse(Object $object, $response) {
        $object->client->transport->populate($object, $response);

        /**
         * Parse the index and metadata headers
         */
        foreach ($object->headers as $key => $val) {
            if (preg_match('~^x-riak-([^-]+)-(.+)$~', $key, $matches)) {
                switch ($matches[1]) {
                    case 'index':
                        $index = substr($matches[2], 0, strrpos($matches[2], '_'));
                        $type = substr($matches[2], strlen($index) + 1);
                        $object->setIndex($index, array_map('urldecode', explode(', ', $val)), $type);
                        break;
                    case 'meta':
                        $object->setMetaValue($matches[2], $val);
                        break;
                }
            }
        }

        /**
         * If there are siblings, load the data for the first one by default
         */
        if ($object->getHasSiblings()) {
            $sibling = $object->getSibling(0);
            $object->data = $sibling->data;
        }

        /**
         * Look for auto indexes and deindex explicit values if appropriate
         */
        if (isset($object->meta['client-autoindex'])) {
            /**
             * dereference the autoindexes
             */
            $object->autoIndexes = CJSON::decode($object->meta['client-autoindex']);
            $collisions = isset($object->meta['client-autoindexcollision']) ? CJSON::decode($object->meta['client-autoindexcollision']) : array();

            if (is_array($object->autoIndexes) && is_array($object->data))
                foreach ($object->autoIndexes as $index => $fieldName) {
                    $value = null;

                    if (isset($object->data[$fieldName])) {
                        $value = $object->data[$fieldName];
                        /**
                         * Only strip this value if not explicit index
                         * @todo review logic
                         */
                        if (!(isset($collisions[$index]) && $collisions[$index] === $value))
                            if ($value !== null)
                                $object->removeIndex($index, null, $value);
                    }
                }
        }

        return $object;
    }

    /**
     * Delete this object from Riak
     *
     * @param int $dw optional DW-Value: X partitions must delete object before returning
     * @return Object
     */
    public function delete($dw = null) {
        /**
         * Use defaults if not specified
         */
        $params = array('dw'=>$this->bucket->getDW($dw));
        $response = $this->client->transport->deleteObject($this, $params);
        $this->client->transport->populate($this, $response);

        return $this;
    }

    /**
     * Reset this object
     *
     * @return Object
     */
    public function clear() {
        $this->headers = array();
        $this->_links = array();
        $this->_data = null;
        $this->_exists = false;
        $this->_siblings = array();
        $this->_indexes = array();
        $this->_autoIndexes = array();
        $this->_meta = array();
        return $this;
    }

    /**
     * Get the vclock of this object
     *
     * @return string|null
     */
    public function getVclock() {
        if (array_key_exists('x-riak-vclock', $this->headers))
            return $this->headers['x-riak-vclock'];
        return null;
    }

    /**
     * Populate object links
     *
     * @param string $linkHeaders
     * @return Object
     */
    public function populateLinks($linkHeaders) {
        $linkHeaders = explode(',', trim($linkHeaders));
        foreach ($linkHeaders as $linkHeader)
            if (preg_match('/\<\/([^\/]+)\/([^\/]+)\/([^\/]+)\>; ?riaktag="([^"]+)"/', trim($linkHeader), $matches))
                $this->_links[] = new Link(urldecode($matches[2]), urldecode($matches[3]), urldecode($matches[4]));

        return $this;
    }

    /**
     * Return true if this object has siblings
     *
     * @return bool
     */
    public function getHasSiblings() {
        return ($this->getSiblingCount() > 0);
    }

    /**
     * Get the number of siblings that this object contains
     *
     * @return int
     */
    public function getSiblingCount() {
        return count($this->_siblings);
    }

    /**
     * Retrieve a sibling by sibling number
     *
     * @param int $i Sibling number
     * @param int $r R-Value: X partitions must respond before returning
     * @return Object
     */
    public function getSibling($i, $r = null) {
        /**
         * Use defaults if not specified
         */
        $r = $this->bucket->getR($r);

        /**
         * Run the request
         */
        $vtag = $this->_siblings[$i];
        $params = array('r' => $r, 'vtag' => $vtag);

        Yii::trace('Fetching sibling "' . $i . '" of object "' . $this->key . '" from bucket "' . $this->bucket->name . '"', 'ext.riiak.Object');
        $response = $this->client->transport->fetchObject($this->bucket, $this->key, $params);

        /**
         * Respond with a new object
         */
        $obj = new Object($this->client, $this->bucket, $this->key);
        $obj->jsonize = $this->jsonize;
        return self::populateResponse($obj, $response);
    }

    /**
     * Retrieve an array of siblings
     *
     * @todo It's possible to fetch multiple siblings in 1 request. That should be implemented here.
     * @link http://wiki.basho.com/HTTP-Fetch-Object.html#Get-all-siblings-in-one-request
     *
     * @param int $r R-Value: X partitions must respond before returning
     * @return array[int]Object
     */
    public function getSiblings($r = null) {
        $a = array();
        for ($i = 0; $i < $this->getSiblingCount(); $i++)
            $a[] = $this->getSibling($i, $r);

        return $a;
    }

    /**
     * Specify sibling vtags
     *
     * @param array[int]string $siblings
     * @return Object
     */
    public function setSiblings(array $siblings) {
        $this->_siblings = $siblings;
        return $this;
    }

    /**
     * Returns a MapReduce instance
     *
     * @param bool $reset Whether to create a new MapReduce instance
     * @return MapReduce
     */
    public function getMapReduce($reset = false) {
        return $this->client->getMapReduce($reset);
    }

}