Skip to content

6. More about requests

Jump to bottom
Pierre-Antoine Ganaye edited this page Aug 16, 2014 · 1 revision

ZooKeeper v3.5.0 and higher

checkWatches

Checks if the watches on a node for a specified watcher type are still available on the server side.

def checkWatches(
  path: String,
  watcherType: Int
): Future[Unit]
  • path is the path of the future node
  • watcherType the watcher type (children, data, any)

built in watcher types :

  • WatcherType.ANY for all the watches
  • WatcherType.CHILDREN only for watches set with getChildren requests
  • WatcherType.DATA only for watches set with getData and exists requests
checkWatcher

Checks if a watcher is not triggered.

def checkWatcher(watcher: Watcher): Future[Unit]
  • watcher a watcher to check.
getConfig

Return the last committed configuration (as known to the server to which the client is connected) and the stat of the configuration.

def getConfig(watch: Boolean = false): Future[GetDataResponse]
  • watch if you want to set a watch or not on the configuration node

If the watch is true and the call is successful (no exception is thrown), a watch will be left on the configuration node. The watch will be triggered by a successful reconfig operation.

reconfig

Reconfigure - add/remove servers. Return the new configuration.

def reconfig(
  joiningServers: String,
  leavingServers: String,
  newMembers: String,
  fromConfig: Long
): Future[GetDataResponse]
  • joiningServers a comma separated list of servers being added (incremental reconfiguration)
  • leavingServers a comma separated list of servers being removed (incremental reconfiguration)
  • newMembers a comma separated list of new membership (non-incremental reconfiguration)
  • fromConfig version of the current configuration (optional - causes reconfiguration to throw an exception if configuration is no longer current)
removeWatches

For the given node path, removes the specified watcher.

def removeWatches(
  watcher: Watcher,
  local: Boolean
): Future[Unit]
  • watcher the watcher to remove.
  • local whether watches can be removed locally when there is no server connection.
removeAllWatches

For the given node path, removes all the registered watchers of given watcherType.

def removeAllWatches(
  path: String,
  watcherType: Int,
  local: Boolean
): Future[Unit]
  • path is the path of the future node
  • watcherType the watcher type (children, data, any)
  • local whether watches can be removed locally when there is no server connection.

ZooKeeper v3.4.0 and higher

connect

Connect to a specific host.

def connect(host: Option[String] = None): Future[Unit]
  • host is the address of a specific host (not mandatory).

If the host parameter is specified, it will try to connect to this host first, of find a new one in the host list if the first attempt was not successful.

If successful, it will return Unit once connected to a server.

disconnect

Close the session and stop background jobs.

def disconnect(): Future[Unit]

If successful, returns Unit once the session is close and background jobs are stopped. If an exception is thrown (maybe because you were not supposed to disconnect), we can at least ensure that background jobs are stopped, watchers cleared and Auth infos removed. So you could start a new session safely.

create

Create a node with the given path. The node data will be the given data, and node acl will be the given acl.

def create(
  path: String,
  data: Array[Byte],
  acl: Seq[ACL],
  createMode: Int
): Future[String]
  • path is the path of the future node
  • data is the data associated to this node
  • acl the ACL to set for this node
  • createMode the creation mode of the node

If successful, this request returns the future path of the created node.

A list of ACL is already included in the client :

  • Ids.OPEN_ACL_UNSAFE This is a completely open ACL (Perms.ALL, ANYONE_ID_UNSAFE)
  • Ids.CREATOR_ALL_ACL This ACL gives the creators authentication id's all permissions (Perms.ALL, AUTH_IDS)
  • Ids.READ_ACL_UNSAFE This ACL gives the world the ability to read (Perms.READ, ANYONE_ID_UNSAFE)

A list of createMode is also available :

  • CreateMode.PERSISTENT (value 0)
  • CreateMode.EPHEMERAL (value 1)
  • CreateMode.PERSISTENT_SEQUENTIAL (value 2)
  • CreateMode.EPHEMERAL_SEQUENTIAL (value 3)
create2
def create2(
  path: String,
  data: Array[Byte],
  acl: Seq[ACL],
  createMode: Int
): Future[Create2Response]
  • path is the path of the future node
  • data is the data associated to this node
  • acl the ACL to set for this node
  • createMode the creation mode of the node

If successful, this request returns a future Create2Response composed by the path of the new node and a Stat of this node.

Here is a detailed view of Create2Response:

case class Create2Response(path: String, stat: Stat)
delete

Delete the node with the given path (if the given version is -1, it matches any node's versions).

def delete(path: String, version: Int): Future[Unit]
  • path is the node's path
  • version is the current node's version

If successful returns a Future[Unit].

getData
def getData(
  path: String,
  watch: Boolean = false
): Future[GetDataResponse]
  • path is the node's path
  • watch if you want to set a watch or not for this node

If successful there are two possible case :

  • First if you had not set a watch, it will return a Future[GetDataResponse] without a watcher (None).
  • Second if you had set a watch, it will return a Future[GetDataResponse] with a watcher (Some(watcher)).

Here is a detailed view of GetDataResponse :

case class GetDataResponse(data: Array[Byte], stat: Stat, watcher: Option[Watcher])
setData

Set the data for the node of the given path.

def setData(path: String, data: Array[Byte], version: Int): Future[Stat]
  • path is the node's path
  • data is the data associated to this node
  • version is the current node's version

If successful returns a Future[Stat]

exists

Return the stat of the node of the given path

def exists(path: String, watch: Boolean = false): Future[ExistsResponse]
  • path is the node's path
  • watch if you want to set a watch or not for this node

If you want to set a watch on a non-existing node, you can do it by calling this definition with the future path of the node and specifying true for the watch parameter. This way you are setting a watch for the existence of this node, once it will be created, the given watcher will be triggered.

If successful returns a Future[ExistsResponse].

Detailed view of ExistsResponse :

case class ExistsResponse(stat: Option[Stat], watcher: Option[Watcher])
getChildren

For the given node path returns the stat and children list.

def getChildren(
  path: String,
  watch: Boolean = false
): Future[GetChildrenResponse]
  • path is the node's path
  • watch if you want to set a watch or not for this node

If successful returns a Future[GetChildrenResponse].

Detailed view of GetChildrenResponse :

case class GetChildrenResponse(children: Seq[String], watcher: Option[Watcher])
getChildren2

For the given node path returns the stat and children list.

def getChildren2(
  path: String,
  watch: Boolean = false
): Future[GetChildren2Response]
  • path is the node's path
  • watch if you want to set a watch or not for this node

If successful returns a Future[GetChildren2Response].

Detailed view of GetChildren2Response :

case class GetChildren2Response(
  children: Seq[String],
  stat: Stat,
  watcher: Option[Watcher]
)
getACL

Return the ACL and stat of the node of the given path.

def getACL(path: String): Future[GetACLResponse]
  • path is the node's path

If successful returns a Future[GetACLResponse].

Detailed view of GetACLResponse :

case class GetACLResponse(acl: Seq[ACL], stat: Stat)
setACL

Set the ACL for the node of the given path.

def setACL(path: String, acl: Seq[ACL], version: Int): Future[Stat]
  • path is the node's path
  • acl the ACL to set for this node
  • version is the current node's version

If successful returns a Future[Stat].

addAuth

Add the specified scheme:auth information to this connection.

def addAuth(scheme: String, auth: Array[Byte]): Future[Unit]
  • scheme is the authentication scheme (world, auth, digest, ip)
  • auth the value of the authentication

Examples :

client.addAuth("world", "anyone".getBytes)
client.addAuth("ip", "192.168.10.10".getBytes)
client.addAuth("auth", "".getBytes)
client.addAuth("digest", "pat:pass".getBytes)

If successful returns a Future[Unit].

sync

Synchronize client and server for a node.

def sync(path: String): Future[String]
  • path is the node's path

If successful returns a Future[String] representing the synchronized node's path.

transaction
def transaction(opList: Seq[OpRequest]): Future[TransactionResponse]
  • opList a sequence of OpRequest

Return value: Future[TransactionResponse]. A TransactionResponse is composed of a responseList, it's a sequence of OpResult. This sequence is ordered in the same order than the original request sequence.

If one of the resquest contained in the TransactionRequest produces an error during the transaction proccessing, all the operations of this transaction are cancelled, and the server will return a TransactionResponse where the sequence of responses is only composed by ErrorResponse.

An ErrorResponse will indicate the cause of the error with its exception value. By reading the sequence of response from the transaction, if the exception is OkException then the corresponding request is not the cause of the failure, you can go throught the list to find the problem (exception will be different of OkException)

A transaction can be composed by one or more OpRequests :

case class CheckVersionRequest(path: String, version: Int)
case class CreateRequest(
  path: String,
  data: Array[Byte],
  aclList: Seq[ACL],
  createMode: Int
  )
case class Create2Request(
  path: String,
  data: Array[Byte],
  aclList: Seq[ACL],
  createMode: Int
  )
case class DeleteRequest(path: String, version: Int)
case class SetDataRequest(
  path: String,
  data: Array[Byte],
  version: Int
  )

Each opRequest will return a response of the same type (expect delete and checkVersion that return an EmptyResponse)

Clone this wiki locally