API Reference 0.4.0couchclientCouchClient

CouchClient abstract class

Client to a Couchbase cluster servers.

Future<CouchClient> future = CouchClient.connect(
  [Uri.parse("http://localhost:8091/pools")], "default", "");

// Store a value
future
 .then((c) => c.set("someKey", someObject))
 .then((ok) => print("done"))
 .catchError((err) => print("$err");

// Retrieve a value.
future
 .then((c) => c.get("someKey"))
 .then((myObject) => print("$myObject"))
 .catchError((err) => print("$err");
abstract class CouchClient implements MemcachedClient, Reconfigurable {
 /**
  * Get the RESTful client associated with this CouchClient.
  */
 RestClient get restClient;

 /**
  * Get document as a GetResult of the provided key and lock its write
  * access for the specified [locktime] in seconds. The
  * maximum lock time is 30 seconds; any number more than 30 or less than zero
  * would be deemed as 30 seconds.
  * This API returns GetResult if succeed; otherwise, throw OPStatus.NOT_FOUND
  * or other error status.
  */
 Future<GetResult> getAndLock(String key, int locktime);

 /**
  * Unlock document associated with the specified key.
  */
 Future<bool> unlock(String key, {int cas});

 /**
  * Create a DesignDoc and add into Couchbase; asynchronously return true
  * if succeed.
  */
 Future<bool> addDesignDoc(DesignDoc doc);

 /**
  * Delete the named DesignDoc.
  */
 Future<bool> deleteDesignDoc(String docName);

 /**
  * Retrieve the named DesignDoc.
  */
 Future<DesignDoc> getDesignDoc(String docName);

 /**
  * Retrieve the named View in the named DesignDoc.
  */
 Future<View> getView(String docName, String viewName);

 /**
  * Retrieve the named SpatialView in the named DesignDoc.
  */
 Future<SpatialView> getSpatialView(String docName, String viewName);

 /**
  * query data from the couchbase with the spcified View(can be [View] or
  * [SpatialView]) and query condition.
  */
 Future<ViewResponse> query(ViewBase view, Query query);

 /**
  * Returns the statistic information of a give key.
  */
 Future<Map<String, String>> keyStats(String key);

 /**
  * Observe a document with the specified key and check its persistency and
  * replicas status in the cluster.
  *
  * + [key] - key of the document
  * + [cas] - expected version of the observed document; null to ignore it. If
  *   specified and the document has been updated, ObserverStatus.MODIFIED
  *   would be returned in ObserveResult.status field.
  */
 Future<Map<SocketAddress, ObserveResult>> observe(String key, {int cas});

 /**
  * Poll and observe a key with the given cas and persist settings.
  *
  * Based on the given [persistTo], [replicateTo], [isDelete] settings, it
  * observes the key and raises an exception if a timeout has been reached.
  * This method is normally used to make sure that a value is stored/deleted
  * to the status you want it in the cluster.
  *
  * If [persistTo] is not specified, it will default to PersistTo.ZERO and if
  * [replicateTo] is not specified, it will default to ReplicateTo.ZERO. This
  * is the default behavior and is the same as not observing at all.
  *
  * + [key] - the key to observe.
  * + [cas] - (optional) CAS version for the key; default: null to ignore cas check.
  * + [persistTo] - (optional) persistence setting; default: [PersistTo.ZERO].
  * + [replicateTo] - (optional) replication setting; default: [ReplicateTo.ZERO].
  * + [isDelete] - (optional) if the key is to be deleted; default: false.
  */
 Future<bool> observePoll(String key, {
   int cas,
   PersistTo persistTo: PersistTo.ZERO,
   ReplicateTo replicateTo: ReplicateTo.ZERO,
   bool isDelete: false});

 /**
  * Create a new client connectting to the specified Couchbase bucket per
  * the given initial server list in the cluster; this method returns a
  * [Future] that will complete with either a [CouchClient] once connected or
  * an error if the server-lookup or connection failed.
  *
  * + [baseList] - the Uri list of one or more servers from the cluster
  * + [bucket] - the bucket name in the cluster you want to connect.
  * + [password] - the password of the bucket
  */
 static Future<CouchClient> connect(
     List<Uri> baseList, String bucket, String password) {
   return new Future.sync(() {
     final factory = new CouchbaseConnectionFactory(baseList, bucket, password);
     return CouchClientImpl.connect(factory);
   });
 }
}

Subclasses

CouchClientImpl

Implements

Reconfigurable, MemcachedClient

Static Methods

Future<CouchClient> connect(List<Uri> baseList, String bucket, String password) #

Create a new client connectting to the specified Couchbase bucket per the given initial server list in the cluster; this method returns a Future that will complete with either a CouchClient once connected or an error if the server-lookup or connection failed.

  • baseList - the Uri list of one or more servers from the cluster
  • bucket - the bucket name in the cluster you want to connect.
  • password - the password of the bucket
static Future<CouchClient> connect(
   List<Uri> baseList, String bucket, String password) {
 return new Future.sync(() {
   final factory = new CouchbaseConnectionFactory(baseList, bucket, password);
   return CouchClientImpl.connect(factory);
 });
}

Properties

final List<SocketAddress> availableServers #

inherited from MemcachedClient

Returns those servers that are currently active and respond to commands.

List<SocketAddress> get availableServers;

final NodeLocator locator #

inherited from MemcachedClient

Returns default Transcoder used with this MemcachedClient.

Returns the locator of the server nodes in the cluster.

NodeLocator get locator;

final RestClient restClient #

Get the RESTful client associated with this CouchClient.

RestClient get restClient;

final List<SocketAddress> unavailableServers #

inherited from MemcachedClient

Returns those servers that are currently not active and cannot respond to commands.

List<SocketAddress> get unavailableServers;

Methods

abstract Future<bool> add(String key, List<int> document, {int exptime}) #

inherited from MemcachedClient

Add specified document if the provided key is not existed yet. Returns true if succeed; otherwise, throw OPStatus.NOT_STORED or other Error status.

  • key - the key of the document
  • document - the document to be set
  • exptime - optional: document expiration time in seconds; defalut to 0 which means permenent. If exptime exceeds 30 days(30x24x60x60), it is deemed as an absolute date in seconds since epoch time.

abstract Future<bool> addDesignDoc(DesignDoc doc) #

Create a DesignDoc and add into Couchbase; asynchronously return true if succeed.

abstract Future<bool> append(String key, List<int> append, {int cas}) #

inherited from MemcachedClient

append byte array at the rear of the existing document of the provided key. Returns true if succeed; otherwise, throw OPStatus.NOT_STORED or other Error status.

  • key - the key of the document
  • append - the byte array append at the rear of the existing document
  • cas - optional: the document version

abstract void close() #

inherited from MemcachedClient

Close this memcached client.

abstract Future<int> decrement(String key, int by, {int def, int exptime}) #

inherited from MemcachedClient

Decrement the document(must be an integer) by the provided by value. Returns the result integer; otherwise, throw OPStatus.NOT_FOUND or other error status. Note decrement will NEVER result in "negative value" or "wrap the counter), it will stay at 0 instead.

  • key - the key of the document
  • by - the number to be decreased from the number document
  • def - optional: the default number to return if the doucment did not exist; default to 0. If exptime is set to -1, this value is ignored.

  • exptime - optional: document expiration time in seconds; default to 0 which means permenent. If exptime exceeds 30 days(30x24x60x60), it is deemed as an absolute date in seconds since unix epoch time. -1 indicate to throw OPStatus.NOT_FOUND if document did not exist.

abstract Future<bool> delete(String key, {int cas}) #

inherited from MemcachedClient

Delete the specified key; return true if succeed. Otherwise, throws OPStatus.NOT_FOUND or other errors.

  • key - the key of the document
  • cas - optional: the document version

abstract Future<bool> deleteDesignDoc(String docName) #

Delete the named DesignDoc.

abstract Future<GetResult> get(String key) #

inherited from MemcachedClient

Get document as a GetResult of the provided key. If you need cas token to avoid racing when setting the document of the key, please use gets API. This API returns GetResult if succeed; otherwise, throw OPStatus.NOT_FOUND or other error status.

abstract Stream<GetResult> getAll(List<String> keys) #

inherited from MemcachedClient

Get list of documents as a Stream of GetResult. If you need cas token to avoid racing when setting the document of the key, please use getsAll API. This API returns a Stream of GetResult per the provided key list; return an empty Stream if none of the doucment of the provided key exists.

abstract Future<GetResult> getAndLock(String key, int locktime) #

Get document as a GetResult of the provided key and lock its write access for the specified locktime in seconds. The maximum lock time is 30 seconds; any number more than 30 or less than zero would be deemed as 30 seconds. This API returns GetResult if succeed; otherwise, throw OPStatus.NOT_FOUND or other error status.

abstract Future<GetResult> getAndTouch(String key, int exptime) #

inherited from MemcachedClient

Get document as a GetResult of the provided key and reset the document expiration time in seconds. 0 means permenent, If exptime exceeds 30 days(30x24x60x60), it is deemed as an absolute date in seconds. This API returns GetResult if succeed; otherwise, throw OPStatus.NOT_FOUND or other error status.

  • exptime - optional: document expiration time in seconds; defalut to 0 which means permenent. If exptime exceeds 30 days(30x24x60x60), it is deemed as an absolute date in seconds since epoch time.

abstract Future<DesignDoc> getDesignDoc(String docName) #

Retrieve the named DesignDoc.

abstract Future<GetResult> gets(String key) #

inherited from MemcachedClient

Get document as a GetResult of the provided key with cas token. The cas token can be used to avoid racing when setting the document of the key. This API returns GetResult if succeed; otherwise, throw OPStatus.NOT_FOUND or other error status.

abstract Stream<GetResult> getsAll(List<String> keys) #

inherited from MemcachedClient

Get list of documents with cas tokens as a Stream of GetResult. The cas token can be used to avoid racing when setting the document of the key. This API returns a Stream of GetResult per the provided key list; return an empty Stream if none of the doucment of the provided key exists.

abstract Future<SpatialView> getSpatialView(String docName, String viewName) #

Retrieve the named SpatialView in the named DesignDoc.

abstract Future<View> getView(String docName, String viewName) #

Retrieve the named View in the named DesignDoc.

abstract Future<int> increment(String key, int by, {int def, int exptime}) #

inherited from MemcachedClient

Increment the docuemnt(must be an integer) by the provided by value. Returns the result integer; otherwise, throw OPStatus.NOT_FOUND or other error status. Note increment might cause counter to wrap over(64bit unsigned).

  • key - the key of the document
  • by - the number to be increased onto the number document
  • def - optional: the default number to return if the doucment did not exist; default to 0. If exptime is set to -1, this value is ignored.

  • exptime - optional: document expiration time in seconds; default to 0 which means permenent. If exptime exceeds 30 days(30x24x60x60), it is deemed as an absolute date in seconds since unix epoch time. -1 indicate to throw OPStatus.NOT_FOUND if document did not exist.

abstract Future<Map<String, String>> keyStats(String key) #

Returns the statistic information of a give key.

abstract Future<Set<String>> listSaslMechs() #

inherited from MemcachedClient

Returns the set of supported SASL authentication mechanisms.

abstract Future<Map<SocketAddress, ObserveResult>> observe(String key, {int cas}) #

Observe a document with the specified key and check its persistency and replicas status in the cluster.

  • key - key of the document
  • cas - expected version of the observed document; null to ignore it. If specified and the document has been updated, ObserverStatus.MODIFIED would be returned in ObserveResult.status field.

abstract Future<bool> observePoll(String key, {int cas, PersistTo persistTo: PersistTo.ZERO, ReplicateTo replicateTo: ReplicateTo.ZERO, bool isDelete: false}) #

Poll and observe a key with the given cas and persist settings.

Based on the given persistTo, replicateTo, isDelete settings, it observes the key and raises an exception if a timeout has been reached. This method is normally used to make sure that a value is stored/deleted to the status you want it in the cluster.

If persistTo is not specified, it will default to PersistTo.ZERO and if replicateTo is not specified, it will default to ReplicateTo.ZERO. This is the default behavior and is the same as not observing at all.

  • key - the key to observe.
  • cas - (optional) CAS version for the key; default: null to ignore cas check.
  • persistTo - (optional) persistence setting; default: PersistTo.ZERO.
  • replicateTo - (optional) replication setting; default: ReplicateTo.ZERO.
  • isDelete - (optional) if the key is to be deleted; default: false.

abstract Future<bool> prepend(String key, List<int> prepend, {int cas}) #

inherited from MemcachedClient

Prepend byte array in front of the existing document of the provided key. Returns true if succeed; otherwise, throw OPStatus.NOT_STORED or other Error status.

  • key - the key of the document
  • prepend - the byte array prepend in front of the existing document
  • cas - optional: the document version

abstract Future<ViewResponse> query(ViewBase view, Query query) #

query data from the couchbase with the spcified View(can be View or SpatialView) and query condition.

abstract void reconfigure(Bucket bucket) #

inherited from Reconfigurable

Called on configuration updates.

abstract Future<bool> replace(String key, List<int> document, {int cas, int exptime}) #

inherited from MemcachedClient

Replace the existing document of the provided key with the specified byte array. Returns true if succeed; otherwise, throw OPStatus.NOT_STORED or other Error status.

  • key - the key of the document
  • document - the document to be set
  • cas - optional: the document version
  • exptime - optional: document expiration time in seconds; defalut to 0 which means permenent. If exptime exceeds 30 days(30x24x60x60), it is deemed as an absolute date in seconds since epoch time.

abstract Future<bool> set(String key, List<int> document, {int cas, int exptime}) #

inherited from MemcachedClient

Set unconditinally the specified document. Returns true if succeed; throw Error status otherwise.

  • key - the key of the document
  • document - the document to be set
  • cas - optional: the document version
  • exptime - optional: document expiration time in seconds; defalut to 0 which means permenent. If exptime exceeds 30 days(30x24x60x60), it is deemed as an absolute date in seconds since epoch time.

abstract Future<Map<SocketAddress, Map<String, String>>> stats({String prefix}) #

inherited from MemcachedClient

Returns the statistics of the connected servers. Returns statistics as a Map<String, String>. see here for details regarding statistics.

  • prefix - which statistic to get. Search "Statistics" in this document for detail regarding which prefix are allowed

abstract Future<bool> touch(String key, int exptime) #

inherited from MemcachedClient

Touch document expiration time in seconds. 0 means permenent. If exptime exceeds 30 days(30x24x60x60), it is deemed as an absolute date in seconds. Returns true if succeed; othewise, throw OPStatus.NOT_FOUND or other Error status.

  • exptime - optional: document expiration time in seconds; defalut to 0 which means permenent. If exptime exceeds 30 days(30x24x60x60), it is deemed as an absolute date in seconds since epoch time.

abstract Future<bool> unlock(String key, {int cas}) #

Unlock document associated with the specified key.

abstract Future<Map<SocketAddress, String>> versions() #

inherited from MemcachedClient

Returns the versions of the connected servers. Returns version as a String.