8686 */
8787 const COUCHBASE_UNKNOWN_HOST = 0x15 ; //LCB_UNKNOWN_HOST
8888
89-
9089////////////////////////////////////////////////////////
9190// //
9291// The following option constants exist //
151150 const COUCHBASE_PRESERVE_ORDER = 1 ;
152151
153152
153+ ////////////////////////////////////////////////////////
154+ // //
155+ // The following replica strategies exist //
156+ // //
157+ ////////////////////////////////////////////////////////
158+
159+ /**
160+ * The caller will get a reply from the first replica to successfully
161+ * reply within the timeout for the operation or will receive an
162+ * error.
163+ */
164+ const COUCHBASE_REPLICA_FIRST = LCB_REPLICA_FIRST ;
165+
166+ /**
167+ * Ask all replicas to send documents/items back. The order of the
168+ * replicas does not imply anything and is just the order they are
169+ * received from the servers (one server may be more busy than
170+ * the other etc).
171+ */
172+ const COUCHBASE_REPLICA_ALL = LCB_REPLICA_ALL ;
173+
174+ /**
175+ * Select one replica by the index in the configuration starting from
176+ * zero. This approach can more quickly receive all possible replies
177+ * for a given topology, but it can also generate false negatives
178+ */
179+ const COUCHBASE_REPLICA_SELECT = LCB_REPLICA_SELECT ;
180+
154181class Couchbase {
155182
156183 /**
@@ -349,21 +376,44 @@ function getMulti($ids, &$cas = array(), $flags = 0) {
349376 /**
350377 * Retrieve a replica of a document from the cluster.
351378 *
352- * Please note that this method is currently experimental and its
353- * signature may change in a future release.
379+ * Examples:
380+ * <code>
381+ * $obj = $cb->getReplica("key",
382+ * array("strategy" => COUCHBASE_REPLICA_SELECT,
383+ * "index" => 0));
354384 *
355- * @param string $id identifies the object to retrieve
356- * @param callable $callback a callback function to call for missing
357- * objects. The function signature looks like:
358- * <code>bool function($res, $id, &$val)</code>
359- * if the function returns <code>true</code> the value
360- * returned through $val is returned. Please note that
361- * the cas field is not updated in these cases.
362- * @param string $cas where to store the cas identifier of the object
385+ * returns
386+ * [ "foo" => [ "value" => "bar", "cas" => 0] ]
387+ *
388+ *
389+ * $obj = $cb->getReplica("foo", COUCHBASE_REPLICA_ALL);
390+ *
391+ * returns
392+ * [ "foo" => [ [ "value" => "bar", "cas" => 0],
393+ * [ "value" => "bar", "cas" => 0] ]
394+ * ]
395+ *
396+ *
397+ * $obj = $cb->getReplica(array("foo", "bar"), COUCHBASE_REPLICA_ALL);
398+ *
399+ * returns
400+ * [ "foo" => [ [ "value" => "bar", "cas" => 0],
401+ * [ "value" => "bar", "cas" => 0] ],
402+ * "bar" => [ [ "value" => "val", "cas" => 0],
403+ * [ "value" => "val", "cas" => 0] ]
404+ * ]
405+ *
406+ * </code>
407+ *
408+ * @param string $ids The document id(s) to get. Pass an array to
409+ * retrieve multiple documets
410+ * @param string $strategy Which strategy to use to pick the replica.
411+ * Pass in an array to specify extra options
412+ * to the strategy.
363413 * @return object The document from the cluster
364414 * @throws CouchbaseException if an error occurs
365415 */
366- function getReplica ($ id$ callback NULL , & $ cas = "" ) {
416+ function getReplica ($ id$ strategy COUCHBASE_REPLICA_FIRST ) {
367417
368418 }
369419
@@ -375,10 +425,12 @@ function getReplica($id, $callback = NULL, &$cas = "") {
375425 *
376426 * @param array $ids an array containing all of the document identifiers
377427 * @param array $cas an array to store the cas identifiers of the documents
428+ * @param string $strategy Which strategy to use to pick the replica
429+ * @param int $replicaidx Index (for COUCHBASE_REPLICA_SELECT)
378430 * @return array an array containing the documents
379431 * @throws CouchbaseException if an error occurs
380432 */
381- function getReplicaMulti ($ ids$ casarray ()) {
433+ function getReplicaMulti ($ ids$ casarray (), $ strategy , $ replicaidx
382434
383435 }
384436
0 commit comments