zookeeper 0.9.3-java

data/lib/zookeeper.rb

@@ -0,0 +1,297 @@
+# Ruby wrapper for the Zookeeper C API
+
+require 'thread'
+require 'monitor'
+require 'forwardable'
+require 'logger'
+
+require 'zookeeper/common'
+require 'zookeeper/constants'
+require 'zookeeper/callbacks'
+require 'zookeeper/exceptions'
+require 'zookeeper/stat'
+require 'zookeeper/acls'
+
+
+if defined?(::JRUBY_VERSION)
+  $LOAD_PATH.unshift(File.expand_path('../java', File.dirname(__FILE__))).uniq!
+else
+  $LOAD_PATH.unshift(File.expand_path('../ext', File.dirname(__FILE__))).uniq!
+end
+
+require 'zookeeper_base'
+
+class Zookeeper < ZookeeperBase
+  unless defined?(@@logger)
+    @@logger = Logger.new($stderr).tap { |l| l.level = Logger::ERROR } 
+  end
+
+  def self.logger
+    @@logger
+  end
+
+  def self.logger=(logger)
+    @@logger = logger
+  end
+
+  def reopen(timeout=10, watcher=nil)
+    warn "WARN: ZookeeperBase#reopen watcher argument is now ignored" if watcher
+    super
+  end
+
+  def initialize(host, timeout=10, watcher=nil)
+    super
+  end
+
+  def get(options = {})
+    assert_open
+    assert_supported_keys(options, [:path, :watcher, :watcher_context, :callback, :callback_context])
+    assert_required_keys(options, [:path])
+
+    req_id = setup_call(:get, options)
+    rc, value, stat = super(req_id, options[:path], options[:callback], options[:watcher])
+
+    rv = { :req_id => req_id, :rc => rc }
+    options[:callback] ? rv : rv.merge(:data => value, :stat => Stat.new(stat))
+  end
+
+  def set(options = {})
+    assert_open
+    assert_supported_keys(options, [:path, :data, :version, :callback, :callback_context])
+    assert_required_keys(options, [:path])
+    assert_valid_data_size!(options[:data])
+    options[:version] ||= -1
+
+    req_id = setup_call(:set, options)
+    rc, stat = super(req_id, options[:path], options[:data], options[:callback], options[:version])
+
+    rv = { :req_id => req_id, :rc => rc }
+    options[:callback] ? rv : rv.merge(:stat => Stat.new(stat))
+  end
+
+  def get_children(options = {})
+    assert_open
+    assert_supported_keys(options, [:path, :callback, :callback_context, :watcher, :watcher_context])
+    assert_required_keys(options, [:path])
+
+    req_id = setup_call(:get_children, options)
+    rc, children, stat = super(req_id, options[:path], options[:callback], options[:watcher])
+
+    rv = { :req_id => req_id, :rc => rc }
+    options[:callback] ? rv : rv.merge(:children => children, :stat => Stat.new(stat))
+  end
+
+  def stat(options = {})
+    assert_open
+    assert_supported_keys(options, [:path, :callback, :callback_context, :watcher, :watcher_context])
+    assert_required_keys(options, [:path])
+
+    req_id = setup_call(:stat, options)
+    rc, stat = exists(req_id, options[:path], options[:callback], options[:watcher])
+
+    rv = { :req_id => req_id, :rc => rc }
+    options[:callback] ? rv : rv.merge(:stat => Stat.new(stat))
+  end
+
+  def create(options = {})
+    assert_open
+    assert_supported_keys(options, [:path, :data, :acl, :ephemeral, :sequence, :callback, :callback_context])
+    assert_required_keys(options, [:path])
+    assert_valid_data_size!(options[:data])
+
+    flags = 0
+    flags |= ZOO_EPHEMERAL if options[:ephemeral]
+    flags |= ZOO_SEQUENCE if options[:sequence]
+
+    options[:acl] ||= ZOO_OPEN_ACL_UNSAFE
+
+    req_id = setup_call(:create, options)
+    rc, newpath = super(req_id, options[:path], options[:data], options[:callback], options[:acl], flags)
+
+    rv = { :req_id => req_id, :rc => rc }
+    options[:callback] ? rv : rv.merge(:path => newpath)
+  end
+
+  def delete(options = {})
+    assert_open
+    assert_supported_keys(options, [:path, :version, :callback, :callback_context])
+    assert_required_keys(options, [:path])
+    options[:version] ||= -1
+
+    req_id = setup_call(:delete, options)
+    rc = super(req_id, options[:path], options[:version], options[:callback])
+
+    { :req_id => req_id, :rc => rc }
+  end
+
+  # this method is *only* asynchronous
+  #
+  # @note There is a discrepancy between the zkc and java versions. zkc takes
+  #   a string_callback_t, java takes a VoidCallback. You should most likely use
+  #   the ZookeeperCallbacks::VoidCallback and not rely on the string value.
+  #
+  def sync(options = {})
+    assert_open
+    assert_supported_keys(options, [:path, :callback, :callback_context])
+    assert_required_keys(options, [:path, :callback])
+
+    req_id = setup_call(:sync, options)
+
+    rc = super(req_id, options[:path]) # we don't pass options[:callback] here as this method is *always* async
+
+    { :req_id => req_id, :rc => rc }
+  end
+
+  def set_acl(options = {})
+    assert_open
+    assert_supported_keys(options, [:path, :acl, :version, :callback, :callback_context])
+    assert_required_keys(options, [:path, :acl])
+    options[:version] ||= -1
+
+    req_id = setup_call(:set_acl, options)
+    rc = super(req_id, options[:path], options[:acl], options[:callback], options[:version])
+
+    { :req_id => req_id, :rc => rc }
+  end
+
+  def get_acl(options = {})
+    assert_open
+    assert_supported_keys(options, [:path, :callback, :callback_context])
+    assert_required_keys(options, [:path])
+
+    req_id = setup_call(:get_acl, options)
+    rc, acls, stat = super(req_id, options[:path], options[:callback])
+
+    rv = { :req_id => req_id, :rc => rc }
+    options[:callback] ? rv : rv.merge(:acl => acls, :stat => Stat.new(stat))
+  end
+
+  # close this client and any underyling connections
+  def close
+    super
+  end
+
+  def state
+    super
+  end
+
+  def connected?
+    super
+  end
+
+  def connecting?
+    super
+  end
+
+  def associating?
+    super
+  end
+  
+  # There are some operations that are dangerous in the context of the event
+  # dispatch thread (because they would block further event delivery). This
+  # method allows clients to know if they're currently executing in the context of an
+  # event.
+  #
+  # @returns [true,false] true if the current thread is the event dispatch thread
+  def event_dispatch_thread?
+    super
+  end
+
+  # for expert use only. set the underlying debug level for the C layer, has no
+  # effect in java
+  #
+  # @private
+  def self.set_debug_level(val)
+    if defined?(::CZookeeper)
+      CZookeeper.set_debug_level(val.to_i)
+    end
+  end
+
+  # @private
+  def self.get_debug_level
+    if defined?(::CZookeeper)
+      CZookeeper.get_debug_level
+    end
+  end
+
+  class << self
+    # @private
+    alias :debug_level= :set_debug_level
+    
+    # @private
+    alias :debug_level :get_debug_level
+  end
+
+  # DEPRECATED: use the class-level method instead
+  def set_debug_level(val)
+    super
+  end
+
+  # has the underlying connection been closed?
+  def closed?
+    super
+  end
+
+  # is the event delivery system running?
+  def running?
+    super
+  end
+
+  # return the session id of the current connection as an Fixnum
+  def session_id
+    super
+  end
+
+  # Return the passwd portion of this connection's credentials as a String
+  def session_passwd
+    super
+  end
+
+protected
+  # used during shutdown, awaken the event delivery thread if it's blocked
+  # waiting for the next event
+  def wake_event_loop!
+    super
+  end
+  
+  # starts the event delivery subsystem going. after calling this method, running? will be true
+  def setup_dispatch_thread!
+    super
+  end
+
+  # TODO: describe what this does
+  def get_default_global_watcher
+    super
+  end
+
+  def logger
+    Zookeeper.logger
+  end
+
+  def assert_valid_data_size!(data)
+    return if data.nil?
+
+    data = data.to_s
+    if data.length >= 1048576 # one megabyte 
+      raise ZookeeperException::DataTooLargeException, "data must be smaller than 1 MiB, your data starts with: #{data[0..32].inspect}"
+    end
+    nil
+  end
+
+private
+  # TODO: Sanitize user mistakes by unregistering watchers from ops that
+  # don't return ZOK (except wexists)?  Make users clean up after themselves for now.
+  #
+  # XXX: is this dead code?
+  def unregister_watcher(req_id)
+    @mutex.synchronize {
+      @watcher_reqs.delete(req_id)
+    }
+  end
+  
+  # must be supplied by parent class impl.
+  def assert_open
+    super
+  end
+end
+

data/lib/zookeeper/acls.rb

@@ -0,0 +1,40 @@
+module ZookeeperACLs
+  class Id
+    attr_reader :scheme, :id
+    def initialize(hash)
+      @scheme = hash[:scheme]
+      @id = hash[:id]
+    end
+
+    def to_hash
+      { :id => id, :scheme => scheme }
+    end
+  end
+    
+  class ACL
+    attr_reader :perms, :id
+    def initialize(hash)
+      @perms = hash[:perms]
+      v = hash[:id]
+      @id = v.kind_of?(Hash) ? Id.new(v) : v
+    end
+
+    def to_hash
+      { :perms => perms, :id => id.to_hash }
+    end
+  end
+  
+  ZOO_PERM_READ   = 0
+  ZOO_PERM_WRITE  = 1
+  ZOO_PERM_CREATE = 2
+  ZOO_PERM_DELETE = 4
+  ZOO_PERM_ADMIN  = 8
+  ZOO_PERM_ALL    = ZOO_PERM_READ | ZOO_PERM_WRITE | ZOO_PERM_CREATE | ZOO_PERM_DELETE | ZOO_PERM_ADMIN
+  
+  ZOO_ANYONE_ID_UNSAFE = Id.new(:scheme => "world", :id => "anyone")
+  ZOO_AUTH_IDS         = Id.new(:scheme => "auth", :id => "")
+
+  ZOO_OPEN_ACL_UNSAFE  = [ACL.new(:perms => ZOO_PERM_ALL,  :id => ZOO_ANYONE_ID_UNSAFE)]
+  ZOO_READ_ACL_UNSAFE  = [ACL.new(:perms => ZOO_PERM_READ, :id => ZOO_ANYONE_ID_UNSAFE)]
+  ZOO_CREATOR_ALL_ACL  = [ACL.new(:perms => ZOO_PERM_ALL,  :id => ZOO_AUTH_IDS)]
+end

data/lib/zookeeper/callbacks.rb

@@ -0,0 +1,91 @@
+module ZookeeperCallbacks
+  class Callback
+    attr_reader :proc, :completed, :context
+
+    def initialize
+      @completed = false
+      @proc = Proc.new do |hash|
+        initialize_context(hash)
+        yield if block_given?
+        @completed = true
+      end
+    end
+    
+    def call(*args)
+      # puts "call passed #{args.inspect}"
+      @proc.call(*args)
+    end
+    
+    def completed?
+      @completed
+    end
+    
+    def initialize_context(hash)
+      @context = nil
+    end
+  end
+  
+  class WatcherCallback < Callback
+    ## wexists, awexists, wget, awget, wget_children, awget_children
+    attr_reader :type, :state, :path
+    
+    def initialize_context(hash)
+      @type, @state, @path, @context = hash[:type], hash[:state], hash[:path], hash[:context]
+    end
+  end
+
+  class DataCallback < Callback
+    ## aget, awget
+    attr_reader :return_code, :data, :stat
+
+    def initialize_context(hash)
+      @return_code, @data, @stat, @context = hash[:rc], hash[:data], hash[:stat], hash[:context]
+    end
+  end
+
+  class StringCallback < Callback
+    ## acreate, async
+    attr_reader :return_code, :string, :context
+
+    alias path string
+
+    def initialize_context(hash)
+      @return_code, @string, @context = hash[:rc], hash[:string], hash[:context]
+    end
+  end
+
+  class StringsCallback < Callback
+    ## aget_children, awget_children
+    attr_reader :return_code, :children, :stat
+
+    def initialize_context(hash)
+      @return_code, @children, @stat, @context = hash[:rc], hash[:strings], hash[:stat], hash[:context]
+    end
+  end
+
+  class StatCallback < Callback
+    ## aset, aexists, awexists
+    attr_reader :return_code, :stat
+
+    def initialize_context(hash)
+      @return_code, @stat, @context = hash[:rc], hash[:stat], hash[:context]
+    end
+  end
+
+  class VoidCallback < Callback
+    ## adelete, aset_acl, add_auth
+    attr_reader :return_code
+    
+    def initialize_context(hash)
+      @return_code, @context = hash[:rc], hash[:context]
+    end
+  end
+
+  class ACLCallback < Callback
+    ## aget_acl
+    attr_reader :return_code, :acl, :stat
+    def initialize_context(hash)
+      @return_code, @acl, @stat, @context = hash[:rc], hash[:acl], hash[:stat], hash[:context]
+    end
+  end
+end

data/lib/zookeeper/common.rb

@@ -0,0 +1,174 @@
+require 'zookeeper/exceptions'
+
+module ZookeeperCommon
+  # sigh, i guess define this here?
+  ZKRB_GLOBAL_CB_REQ   = -1
+
+  def event_dispatch_thread?
+    @dispatcher && (@dispatcher == Thread.current)
+  end
+
+protected
+  def get_next_event(blocking=true)
+    @event_queue.pop(!blocking).tap do |event|
+      logger.debug { "#{self.class}##{__method__} delivering event #{event.inspect}" }
+    end
+  rescue ThreadError
+    nil
+  end
+
+  def setup_call(meth_name, opts)
+    req_id = nil
+    @mutex.synchronize {
+      req_id = @current_req_id
+      @current_req_id += 1
+      setup_completion(req_id, meth_name, opts) if opts[:callback]
+      setup_watcher(req_id, opts) if opts[:watcher]
+    }
+    req_id
+  end
+ 
+  def setup_watcher(req_id, call_opts)
+    @watcher_reqs[req_id] = { :watcher => call_opts[:watcher],
+                              :context => call_opts[:watcher_context] }
+  end
+
+  # as a hack, to provide consistency between the java implementation and the C
+  # implementation when dealing w/ chrooted connections, we override this in
+  # ext/zookeeper_base.rb to wrap the callback in a chroot-path-stripping block.
+  #
+  # we don't use meth_name here, but we need it in the C implementation
+  #
+  def setup_completion(req_id, meth_name, call_opts)
+    @completion_reqs[req_id] = { :callback => call_opts[:callback],
+                                 :context => call_opts[:callback_context] }
+  end
+  
+  def get_watcher(req_id)
+    @mutex.synchronize {
+      (req_id == ZKRB_GLOBAL_CB_REQ) ? @watcher_reqs[req_id] : @watcher_reqs.delete(req_id)
+    }
+  end
+  
+  def get_completion(req_id)
+    @mutex.synchronize { @completion_reqs.delete(req_id) }
+  end
+
+  def setup_dispatch_thread!
+    logger.debug {  "starting dispatch thread" }
+    @dispatcher ||= Thread.new do
+      while true
+        begin
+          dispatch_next_callback(get_next_event(true))
+        rescue QueueWithPipe::ShutdownException
+          logger.info { "dispatch thread exiting, got shutdown exception" }
+          break
+        rescue Exception => e
+          $stderr.puts ["#{e.class}: #{e.message}", e.backtrace.map { |n| "\t#{n}" }.join("\n")].join("\n")
+        end
+      end
+      signal_dispatch_thread_exit!
+    end
+  end
+  
+  # this method is part of the reopen/close code, and is responsible for
+  # shutting down the dispatch thread. 
+  #
+  # @dispatcher will be nil when this method exits
+  #
+  def stop_dispatch_thread!
+    logger.debug { "#{self.class}##{__method__}" }
+
+    if @dispatcher
+      if @dispatcher.join(0)
+        @dispatcher = nil
+        return
+      end
+
+      @mutex.synchronize do
+        event_queue.graceful_close!
+
+        # we now release the mutex so that dispatch_next_callback can grab it
+        # to do what it needs to do while delivering events
+        #
+        # wait for a maximum of 2 sec for dispatcher to signal exit (should be
+        # fast)
+        @dispatch_shutdown_cond.wait(2)
+
+        # wait for another 2 sec for the thread to join
+        unless @dispatcher.join(2)
+          logger.error { "Dispatch thread did not join cleanly, continuing" }
+        end
+        @dispatcher = nil
+      end
+    end
+  end
+
+  def signal_dispatch_thread_exit!
+    @mutex.synchronize do
+      logger.debug { "dispatch thread exiting!" }
+      @dispatch_shutdown_cond.broadcast
+    end
+  end
+
+  def dispatch_next_callback(hash)
+    return nil unless hash
+
+    Zookeeper.logger.debug { "get_next_event returned: #{prettify_event(hash).inspect}" }
+    
+    is_completion = hash.has_key?(:rc)
+    
+    hash[:stat] = ZookeeperStat::Stat.new(hash[:stat]) if hash.has_key?(:stat)
+    hash[:acl] = hash[:acl].map { |acl| ZookeeperACLs::ACL.new(acl) } if hash[:acl]
+    
+    callback_context = is_completion ? get_completion(hash[:req_id]) : get_watcher(hash[:req_id])
+
+    # When connectivity to the server has been lost (as indicated by SESSION_EVENT)
+    # we want to rerun the callback at a later time when we eventually do have
+    # a valid response.
+    if hash[:type] == ZookeeperConstants::ZOO_SESSION_EVENT
+      is_completion ? setup_completion(hash[:req_id], callback_context) : setup_watcher(hash[:req_id], callback_context)
+    end
+    if callback_context
+      callback = is_completion ? callback_context[:callback] : callback_context[:watcher]
+
+      hash[:context] = callback_context[:context]
+
+      # TODO: Eventually enforce derivation from Zookeeper::Callback
+      if callback.respond_to?(:call)
+        callback.call(hash)
+      else
+        # puts "dispatch_next_callback found non-callback => #{callback.inspect}"
+      end
+    else
+      logger.warn { "Duplicate event received (no handler for req_id #{hash[:req_id]}, event: #{hash.inspect}" }
+    end
+    true
+  end
+
+  def assert_supported_keys(args, supported)
+    unless (args.keys - supported).empty?
+      raise ZookeeperExceptions::ZookeeperException::BadArguments,  # this heirarchy is kind of retarded
+            "Supported arguments are: #{supported.inspect}, but arguments #{args.keys.inspect} were supplied instead"
+    end
+  end
+
+  def assert_required_keys(args, required)
+    unless (required - args.keys).empty?
+      raise ZookeeperExceptions::ZookeeperException::BadArguments,
+            "Required arguments are: #{required.inspect}, but only the arguments #{args.keys.inspect} were supplied."
+    end
+  end
+
+private
+  def prettify_event(hash)
+    hash.dup.tap do |h|
+      # pretty up the event display
+      h[:type]    = ZookeeperConstants::EVENT_TYPE_NAMES.fetch(h[:type]) if h[:type]
+      h[:state]   = ZookeeperConstants::STATE_NAMES.fetch(h[:state]) if h[:state]
+      h[:req_id]  = :global_session if h[:req_id] == -1
+    end
+  end
+end
+
+require 'zookeeper/common/queue_with_pipe'