Bucket.php

<?php

namespace riiak;

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

/**
 * The Bucket object allows you to access and change information
 * about a Riak bucket, and provides methods to create or retrieve
 * objects within the bucket.
 * @package riiak
 *
 * @property array $properties
 * @property bool $allowMultiples
 * @property int $dw
 * @property int $nVal
 * @property int $r
 * @property int $w
 *
 * @property-read array $keys
 */
class Bucket extends CComponent {

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

    /**
     * Bucket name
     *
     * @var string
     */
    public $name;

    /**
     * R-Value
     *
     * @var int
     */
    protected $_r;

    /**
     * W-Value
     *
     * @var int
     */
    protected $_w;

    /**
     * DW-Value
     *
     * @var int
     */
    protected $_dw;

    /**
     * @var array
     */
    protected $_properties;

    /**
     * @var array
     */
    protected $_keys;

    public function __construct(Riiak $client, $name) {
        $this->client = $client;
        $this->name = $name;
    }

    /**
     * Get the R-Value for this bucket, if set. Falls back to client value.
     *
     * @param int $r Optional: The R-Value to be returned if not null
     * @return int
     */
    public function getR($r = null) {
        if ($r !== null)
            return $r;
        if ($this->_r !== null)
            return $this->_r;
        return $this->client->r;
    }

    /**
     * Set the R-value for this bucket.
     * get/getBinary operations may use this value
     *
     * @param int $r The new R-Value
     * @return \riiak\Bucket
     */
    public function setR($r) {
        $this->_r = $r;
        return $this;
    }

    /**
     * Get the W-Value for this bucket, if set. Falls back to client value.
     *
     * @param int $w Optional: The W-Value to be returned if not null
     * @return int
     */
    public function getW($w=null) {
        if ($w !== null)
            return $w;
        if ($this->_w !== null)
            return $this->_w;
        return $this->client->w;
    }

    /**
     * Set the W-Value for this bucket
     * get/getBinary operations may use this value
     *
     * @param int $w The new W-Value
     * @return \riiak\Bucket
     */
    public function setW($w) {
        $this->_w = $w;
        return $this;
    }

    /**
     * Get the DW-Value for this bucket, if set. Falls back to client value.
     *
     * @param int $dw Optional: The DW-Value to be returned if not null
     * @return int
     */
    public function getDW($dw=null) {
        if ($dw !== null)
            return $dw;
        if ($this->_dw !== null)
            return $this->_dw;
        return $this->client->dw;
    }

    /**
     * Set the DW-Value for this bucket
     * get/getBinary operations may use this value
     *
     * @param int $dw The new DW-Value
     * @return \riiak\Bucket
     */
    public function setDW($dw) {
        $this->_dw = $dw;
        return $this;
    }

    /**
     * Create a new Riak object that will be stored as JSON
     *
     * @param string $key optional Key value
     * @param mixed $data optional Data to store (Default: null)
     * @return \riiak\Object
     */
    public function newObject($key = null, $data = null) {
        return $this->newBinary($key, $data, 'application/json', true);
    }

    /**
     * Create a new Riak object that will be stored as Binary
     *
     * @param string $key optional Key value
     * @param mixed $data optional Data to store
     * @param string $contentType optional Content type of the object (Default: application/json)
     * @param bool $jsonize optional Whether to treat the object as JSON (Default: false)
     * @return \riiak\Object
     */
    public function newBinary($key = null, $data = null, $contentType = 'application/json', $jsonize = false) {
        $obj = new Object($this->client, $this, $key);
        $obj->data = $data;
        $obj->contentType = $contentType;
        $obj->jsonize = $jsonize;
        return $obj;
    }

    /**
     * Retrieve a JSON-encoded object from Riak
     *
     * @param string $key Name of the key
     * @param int $r optional R-Value of the request (Default: bucket's R)
     * @return \riiak\Object
     */
    public function get($key, $r = null) {
        return $this->getBinary($key, $r, true);
    }

    /**
     * Retrieves binary/string object from Riak
     *
     * @param string $key Name of the key
     * @param int $r R-Value of the request (Default: bucket's R)
     * @param bool $jsonize Whether to treat the object as JSON (Default: false)
     * @return \riiak\Object
     */
    public function getBinary($key, $r = null, $jsonize = false) {
        $obj = new Object($this->client, $this, $key);
        $obj->jsonize = $jsonize;
        $r = $this->getR($r);
        return $obj->reload($r);
    }

    public function getMulti(array $keys, $r = null) {
        return $this->getMultiBinary($keys, $r, true);
    }

    public function getMultiBinary(array $keys, $r = null, $jsonize = false) {
        $bucket = $this;
        $client = $this->client;
        
        $objects = array_map(function($key)use($jsonize, $client, $bucket) {
                    $obj = new Object($client, $bucket, $key);
                    $obj->jsonize = $jsonize;
                    return $obj;
                }, $keys);
        $r = $this->getR($r);
        return Object::reloadMulti($client, $objects, $r);
    }

    /**
     * Set N-value for this bucket. Controls number replicas of each object
     * that will be written. Set once before writing data to the bucket.
     * Should never change this value from the initially used N-Val, otherwise
     * unexpected results may occur. Only use if you know what you're doing
     *
     * @param int $nval The new N-Val
     */
    public function setNVal($nval) {
        $this->setProperty('n_val', $nval);
    }

    /**
     * Retrieve the N-value for this bucket
     *
     * @return int
     */
    public function getNVal() {
        return $this->getProperty('n_val');
    }

    /**
     * Whether writes can have conflicting data. Detect by calling hasSiblings()
     * and getSiblings(). Only use if you know what you are doing
     *
     * @param bool $bool True to store & return conflicting writes
     */
    public function setAllowMultiples($bool) {
        $this->setProperty('allow_mult', $bool);
    }

    /**
     * Retrieve the 'allow multiples' setting
     *
     * @return bool
     */
    public function getAllowMultiples() {
        return 'true' == $this->getProperty('allow_mult');
    }

    /**
     * Set a bucket property. Only use if you know what you're doing
     *
     * @param string $key
     * @param mixed $value
     */
    public function setProperty($key, $value) {
        $this->setProperties(array($key => $value));
    }

    /**
     * Retrieve a bucket property
     *
     * @param string $key The property to retrieve
     * @return mixed|null
     */
    public function getProperty($key) {
        $props = $this->getProperties();
        if (array_key_exists($key, $props))
            return $props[$key];
        else
            return null;
    }

    /**
     * Set multiple bucket properties in one call. Only use if you know
     * what you're doing
     *
     * @param array $props An associative array of $key=>$value
     * @return Bucket
     */
    public function setProperties(array $props) {
        Yii::trace('Setting Bucket properties for bucket "' . $this->name . '"', 'ext.riiak.Bucket');
        $this->client->transport->setBucket($this, array('props'=>$props));

        $this->_properties = null;

        return $this;
    }

    /**
     * Retrieve an associative array of all bucket properties
     *
     * @param bool $refresh
     * @return array
     */
    public function getProperties($refresh = false) {
        if ($refresh || !is_array($this->_properties)) {
            Yii::trace('Fetching properties for bucket "' . $this->name . '"', 'ext.riiak.Bucket');
            $props = $this->client->transport->listBucketProps($this);
            if(empty($props))
                return array();
            $this->_properties = $props;
        }
        return $this->_properties;
    }

    /**
     * Retrieve an array of all keys in this bucket
     * Note: this operation is pretty slow
     *
     * @param bool $refresh
     * @return array
     */
    public function getKeys($refresh = false) {
        if ($refresh || !is_array($this->_keys)) {
            Yii::log('Bucket key listing is a very intensive operation, and should never occur in production!', \CLogger::LEVEL_WARNING);
            Yii::trace('Fetching keys for bucket "' . $this->name . '"', 'ext.riiak.Bucket');
            $this->_keys = $this->client->transport->listBucketKeys($this);
        }
        return $this->_keys;
    }

    /**
     * Search a secondary index
     * @author Eric Stevens <estevens@taglabsinc.com>
     * @param string $name - The name of the index to search
     * @param string $type - The type of index ('int' or 'bin')
     * @param string|int $startOrExact
     * @param string|int $end optional
     * @param bool $dedupe - whether to eliminate duplicate entries if any
     * @return array of Links
     */
    public function indexSearch($name, $type, $startOrExact, $end = NULL, $dedupe = false) {
        $url = $this->client->transport->buildBucketIndexPath($this, $name . '_' . $type, $startOrExact, $end);
        $response = $this->client->transport->get($url);

        $obj = Object::populateResponse(new Object($this->client, $this), $response, 'secondaryIndex');
        if (!$obj->exists)
            throw new Exception('Error searching index.');

        $data = $obj->data;
        $keys = array_map('urldecode', $data['keys']);

        /**
         * Combo of array_keys+array_flip is faster than array_unique
         */
        if ($dedupe)
            $keys = array_keys(array_flip($keys));

        array_walk($keys, array($this, 'inflateLinkCallback'));
        return $keys;
    }

    protected function inflateLinkCallback(&$key, $k) {
        $key = new Link($this->name, $key);
        $key->client = $this->client;
    }

}