zookeeper — zookeeper-clj 0.10.0

Zookeeper-clj is a Clojure DSL for <a href="http://zookeeper.apache.org/">Apache ZooKeeper</a>, which "<i>is a centralized service for maintaining configuration information, naming, providing distributed synchronization, and providing group services.</i>"

Out of the box ZooKeeper provides name service, configuration, and group membership. From these core services, higher-level distributed concurrency abstractions can be built, including distributed locks, distributed queues, barriers, leader-election, and transaction services as described in <a href="http://zookeeper.apache.org/doc/trunk/recipes.html">ZooKeeper Recipes and Solutions</a> and the paper <a href="http://www.usenix.org/event/atc10/tech/full_papers/Hunt.pdf">"ZooKeeper: Wait-free coordination for Internet-scale systems"</a>.

See examples:

• http://developer.yahoo.com/blogs/hadoop/posts/2009/05/using_zookeeper_to_tame_system/
• http://archive.cloudera.com/cdh/3/zookeeper/zookeeperProgrammers.pdf

acl clj

(acl scheme id-value perm & more-perms)

Creates an ACL object.

Examples:

(use 'zookeeper) (def client (connect "127.0.0.1:2181" :watcher #(println "event received: " %)))

(def open-acl-unsafe (acl "world" "anyone" :read :create :delete :admin :write)) (create client "/mynode" :acl [open-acl-unsafe])

(def ip-acl (acl "ip" "127.0.0.1" :read :create :delete :admin :write)) (create client "/mynode2" :acl [ip-acl])

(add-auth-info client "digest" "david:secret")

;; works (def auth-acl (acl "auth" "" :read :create :delete :admin :write)) (create client "/mynode4" :acl [auth-acl]) (data client "/mynode4")

;; change auth-info (add-auth-info client "digest" "edgar:secret") (data client "/mynode4")

acl-id clj

(acl-id scheme id-value)

Returns an ACL Id object with the given scheme and ID value.

add-auth-info clj

(add-auth-info client scheme auth)

Add auth info to connection.

auth-acl clj

(auth-acl & perms)

Create an instance of an ACL using the auth scheme.

children clj

(children client
          path
          &
          {:keys [watcher watch? async? callback context]
           :or {watch? false async? false context path}})

Returns a sequence of child node name for the given node, nil if it has no children or false if the node does not exist.

Examples:

(use 'zookeeper) (def client (connect "127.0.0.1:2181" :watcher #(println "event received: " %)))

(defn callback [result] (println "got callback result: " result))

(delete-all client "/foo") (create client "/foo" :persistent? true) (repeatedly 5 #(create client "/foo/child-" :sequential? true))

(children client "/foo") (def p0 (children client "/foo" :async? true)) @p0 (def p1 (children client "/foo" :callback callback)) @p1 (def p2 (children client "/foo" :async? true :watch? true)) @p2 (def p3 (children client "/foo" :async? true :watcher #(println "watched event: " %))) @p3

close clj

(close client)

Closes the connection to the ZooKeeper server.

compare-and-set-data clj

(compare-and-set-data client node expected-value new-value)

Sets the data field of the given node, only if the current data byte-array equals (Arrays/equal) the given expected-value.

connect clj

(connect connection-string
         &
         {:keys [timeout-msec watcher] :or {timeout-msec 5000}})

Returns a ZooKeeper client.

create clj

(create client
        path
        &
        {:keys [data acl persistent? sequential? context callback async?]
         :or {persistent? false
              sequential? false
              acl (zi/acls :open-acl-unsafe)
              context path
              async? false}})

Creates a node, returning either the node's name, or a promise with a result map if either the :async? option is true or if a :callback function is provided. If the node already exists, create will return false.

Options:

:persistent? indicates if the node should be persistent :sequential? indicates if the node should be sequential :data data to associate with the node :acl access control, see the acls map :async? indicates that the create should occur asynchronously, a promise will be returned :callback indicates that the create should occur asynchronously and that this function should be called when it does, a promise will also be returned

Example:

(use 'zookeeper) (def client (connect "127.0.0.1:2181" :watcher #(println "event received: " %)))

(defn callback [result] (println "got callback result: " result))

;; first delete the baz node if it exists (delete-all client "/baz") ;; now create a persistent parent node, /baz, and two child nodes (def p0 (create client "/baz" :callback callback :persistent? true)) @p0 (def p1 (create client "/baz/1" :callback callback)) @p1 (def p2 (create client "/baz/2-" :async? true :sequential? true)) @p2 (create client "/baz/3")

create-all clj

(create-all client path & options)

Create a node and all of its parents. The last node will be ephemeral, and its parents will be persistent.

Options like :persistent? :sequential? and :acl will only be applied to the last child node.

Examples: (delete-all client "/foo") (create-all client "/foo/bar/baz" :persistent? true) (create-all client "/foo/bar/baz/n-" :sequential? true)

data clj

(data client
      path
      &
      {:keys [watcher watch? async? callback context]
       :or {watch? false async? false context path}})

Returns a map with two fields, :data and :stat:

• :stat: node status. Same as returned by zookeeper/exists.
• :data: byte array of data saved on node.

Examples:

(use 'zookeeper) (def client (connect "127.0.0.1:2181" :watcher #(println "event received: " %)))

(defn callback [result] (println "got callback result: " result))

(delete-all client "/foo") (create client "/foo" :persistent? true :data (.getBytes "Hello World" "UTF-8")) (def result (data client "/foo")) (String. (:data result)) (:stat result)

(def p0 (data client "/foo" :async? true)) @p0 (String. (:data @p0))

(def p1 (data client "/foo" :watch? true :callback callback)) @p1 (String. (:data @p1))

(create client "/foobar" :persistent? true :data (.getBytes (pr-str {:a 1, :b 2, :c 3} "UTF-8"))) (read-string (String. (:data (data client "/foobar"))))

default-perms clj

delete clj

(delete client
        path
        &
        {:keys [version async? callback context]
         :or {version -1 async? false context path}})

Delete the given node if it exists.

Examples:

(use 'zookeeper) (def client (connect "127.0.0.1:2181" :watch #(println "event received: " %)))

(defn callback [result] (println "got callback result: " result))

(create client "/foo" :persistent? true) (create client "/bar" :persistent? true)

(delete client "/foo") (def p0 (delete client "/bar" :callback callback)) @p0

delete-all clj

(delete-all client path & options)

Delete a node and all of its children.

delete-children clj

(delete-children client path & options)

Delete all of a node's children.

digest-acl clj

(digest-acl username password & perms)

Create an instance of an ACL using the digest scheme.

exists clj

(exists client
        path
        &
        {:keys [watcher watch? async? callback context]
         :or {watch? false async? false context path}})

Returns the status of the given node, or nil if the node does not exist.

If the watch is true and the call is successful (no exception is thrown), a watch will be left on the node with the given path. The watch will be triggered by a successful operation that creates/delete the node or sets the data on the node.

If a watcher is provided the function will be called asynchronously with the provided watcher.

If a callback is provided or async? is true, exists will be called asynchronously and return a promise.

Examples:

(use 'zookeeper) (def client (connect "127.0.0.1:2181" :wacher #(println "event received: " %)))

(defn callback [result] (println "got callback result: " result))

(exists client "/yadda" :watch? true) (create client "/yadda") (exists client "/yadda") (def p0 (exists client "/yadda" :async? true)) @p0 (def p1 (exists client "/yadda" :callback callback)) @p1

filter-children-by-pattern clj

(filter-children-by-pattern client dir pattern)

Returns a sequence of child node names filtered by the given regex pattern.

filter-children-by-prefix clj

(filter-children-by-prefix client dir prefix)

Returns a sequence of child node names that start with the given prefix.

filter-children-by-suffix clj

(filter-children-by-suffix client dir suffix)

Returns a sequence of child node names that end with the given suffix.

get-acl clj

(get-acl client
         path
         &
         {:keys [async? callback context] :or {async? false context path}})

Returns a sequence of ACLs associated with the node at the given path and its stat.

Examples:

(use 'zookeeper) (def client (connect "127.0.0.1:2181" :watcher #(println "event received: " %))) (add-auth-info client "digest" "david:secret")

(defn callback [result] (println "got callback result: " result))

(delete-all client "/foo") (create client "/foo" :acl [(acl "auth" "" :read :write :create :delete)]) (get-acl client "/foo")

(def p0 (get-acl client "/foo" :async? true))

(def p1 (get-acl client "/foo" :callback callback))

host-acl clj

(host-acl host-suffix & perms)

Create an instance of an ACL using the host scheme.

ip-acl clj

(ip-acl ip-address & perms)

Create an instance of an ACL using the IP scheme.

register-watcher clj

(register-watcher client watcher)

Registers a default watcher function with this connection. Overrides the watcher specified during connection.

set-data clj

(set-data client
          path
          data
          version
          &
          {:keys [async? callback context] :or {async? false context path}})

Set the data for the node of the given path if such a node exists and the given version matches the version of the node. if the given version is -1, it matches any node's versions. Return the stat of the node.

Examples:

(use 'zookeeper) (def client (connect "127.0.0.1:2181" :watcher #(println "event received: " %)))

(defn callback [result] (println "got callback result: " result))

(delete-all client "/foo") (create client "/foo" :persistent? true)

(set-data client "/foo" (.getBytes "Hello World" "UTF-8") 0) (String. (:data (data client "/foo")))

(def p0 (set-data client "/foo" (.getBytes "New Data" "UTF-8") 0 :async? true)) @p0 (String. (:data (data client "/foo")))

(def p1 (set-data client "/foo" (.getBytes "Even Newer Data" "UTF-8") 1 :callback callback)) @p1 (String. (:data (data client "/foo")))

state clj

(state client)

Returns the client's current state. One of: :ASSOCIATING :AUTH_FAILED :CLOSED :CONNECTED :CONNECTEDREADONLY :CONNECTING :NOT_CONNECTED

world-acl clj

(world-acl & perms)

Create an instance of an ACL using the world scheme.