zookeeper-ng 1.5

data/lib/zookeeper.rb

@@ -0,0 +1,115 @@
+# Ruby wrapper for the Zookeeper C API
+
+require 'thread'
+require 'monitor'
+require 'forwardable'
+require 'logger'
+require 'benchmark'
+
+module Zookeeper
+  ZOOKEEPER_ROOT = File.expand_path('../..', __FILE__)
+
+  # require a path relative to the lib directory
+  # this is to avoid monkeying explicitly with $LOAD_PATH
+  #
+  # @private
+  def self.require_lib(*relpaths)
+    relpaths.each do |relpath|
+      require File.join(ZOOKEEPER_ROOT, 'lib', relpath)
+    end
+  end
+
+  # require a path that's relative to ZOOKEEPER_ROOT
+  # @private
+  def self.require_root(*relpaths)
+    relpaths.each do |relpath|
+      require File.join(ZOOKEEPER_ROOT, relpath)
+    end
+  end
+end
+
+Zookeeper.require_lib(
+  'zookeeper/core_ext',
+  'zookeeper/monitor',
+  'zookeeper/logger',
+  'zookeeper/logger/forwarding_logger',
+  'zookeeper/forked',
+  'zookeeper/latch',
+  'zookeeper/acls',
+  'zookeeper/constants',
+  'zookeeper/exceptions',
+  'zookeeper/continuation',
+  'zookeeper/common',
+  'zookeeper/request_registry',
+  'zookeeper/callbacks',
+  'zookeeper/stat',
+  'zookeeper/client_methods'
+)
+
+# ok, now we construct the client
+Zookeeper.require_lib 'zookeeper/client'
+
+module Zookeeper
+  include Constants
+  #::Logger.new($stderr).tap { |l| l.level = ENV['ZOOKEEPER_DEBUG'] ? ::Logger::DEBUG : ::Logger::ERROR } 
+  #
+  
+  @@logger = nil unless defined?(@@logger)
+  
+  def self.logger
+    @@logger
+  end
+
+  def self.logger=(logger)
+    @@logger = logger
+  end
+
+  # @private
+  def self.deprecation_warnings?
+    @deprecation_warnings = true if @deprecation_warnings.nil?
+  end
+
+  # set this to false to mute Zookeeper related deprecation warnings...
+  # __AT YOUR PERIL__
+  def self.deprecation_warnings=(v)
+    @deprecation_warnings = v
+  end
+
+  # @private
+  def self.deprecation_warning(warning)
+    Kernel.warn(warning) if deprecation_warnings?
+  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
+end
+
+# just for first test, get rid of this soon
+Zookeeper.require_lib 'zookeeper/compatibility'
+
+if ENV['ZKRB_DEBUG']
+  Zookeeper.debug_level = Zookeeper::Constants::ZOO_LOG_LEVEL_DEBUG
+end
+

data/lib/zookeeper/acls.rb

@@ -0,0 +1,44 @@
+module Zookeeper
+module ACLs
+  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
+  
+  module Constants
+    ZOO_PERM_READ   = 1 << 0
+    ZOO_PERM_WRITE  = 1 << 1
+    ZOO_PERM_CREATE = 1 << 2
+    ZOO_PERM_DELETE = 1 << 3
+    ZOO_PERM_ADMIN  = 1 << 4
+    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
+end
+end

data/lib/zookeeper/callbacks.rb

@@ -0,0 +1,108 @@
+module Zookeeper
+module Callbacks
+  class Base
+    attr_reader :proc, :completed, :context
+
+    # allows for easier construction of a user callback block that will be
+    # called with the callback object itself as an argument. 
+    #
+    # @example
+    #   
+    #   Base.create do |cb|
+    #     puts "watcher callback called with argument: #{cb.inspect}"
+    #   end
+    #
+    #   "watcher callback called with argument: #<Zookeeper::Callbacks::Base:0x1018a3958 @state=3, @type=1, ...>"
+    #
+    #
+    def self.create
+      cb_inst = new { yield cb_inst }
+    end
+
+    def initialize
+      @completed = false
+      @proc = Proc.new do |hash|
+        initialize_context(hash)
+        yield if block_given?
+        @completed = true
+      end
+    end
+    
+    def call(*args)
+      @proc.call(*args)
+    end
+    
+    def completed?
+      @completed
+    end
+    
+    def initialize_context(hash)
+      @context = nil
+    end
+  end
+
+  class WatcherCallback < Base
+    ## 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 < Base
+    ## 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 < Base
+    ## 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 < Base
+    ## 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 < Base
+    ## 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 < Base
+    ## adelete, aset_acl, add_auth
+    attr_reader :return_code
+    
+    def initialize_context(hash)
+      @return_code, @context = hash[:rc], hash[:context]
+    end
+  end
+
+  class ACLCallback < Base
+    ## 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
+end

data/lib/zookeeper/client.rb

@@ -0,0 +1,30 @@
+# figure out what platform we're on
+# this way there's no ambiguity about which file to include
+# or which class we're subclassing.
+
+if defined?(::JRUBY_VERSION)
+  Zookeeper.require_root('java/java_base')
+else
+  Zookeeper.require_root('ext/zookeeper_base')
+end
+
+
+module Zookeeper
+  if defined?(::JRUBY_VERSION)
+    class Client < Zookeeper::JavaBase
+    end
+  else
+    class Client < Zookeeper::ZookeeperBase
+    end
+  end
+
+  def self.new(*a, &b)
+    Zookeeper::Client.new(*a, &b)
+  end
+end
+
+
+Zookeeper::Client.class_eval do
+  include Zookeeper::ClientMethods
+end
+

data/lib/zookeeper/client_methods.rb

@@ -0,0 +1,282 @@
+module Zookeeper
+module ClientMethods
+  extend Forwardable
+  include Constants
+  include ACLs
+  include Logger
+
+  # @req_registry is set up in the platform-specific base classes
+  def_delegators :@req_registry, :setup_call
+  private :setup_call
+
+  def reopen(timeout=10, watcher=nil, opts = {})
+    warn "WARN: ZookeeperBase#reopen watcher argument is now ignored" if watcher
+    super
+  end
+
+  def initialize(host, timeout=10, watcher=nil, opts = {})
+    super
+  end
+
+  def add_auth(options = {})
+    assert_open
+    assert_keys(options, 
+                :supported => [:scheme, :cert],
+                :required  => [:scheme, :cert])
+
+    req_id = setup_call(:add_auth, options)
+    rc = super(req_id, options[:scheme], options[:cert])
+
+    { :req_id => req_id, :rc => rc }
+  end
+
+  def get(options = {})
+    assert_open
+    assert_keys(options,
+                :supported  => [:path, :watcher, :watcher_context, :callback, :callback_context],
+                :required   => [: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_keys(options,
+                :supported  => [:path, :data, :version, :callback, :callback_context],
+                :required   => [: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_keys(options,
+                :supported => [:path, :callback, :callback_context, :watcher, :watcher_context],
+                :required  => [: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_keys(options,
+                :supported  => [:path, :callback, :callback_context, :watcher, :watcher_context],
+                :required   => [: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_keys(options,
+                :supported  => [:path, :data, :acl, :ephemeral, :sequence, :callback, :callback_context],
+                :required   => [: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_keys(options,
+                :supported  => [:path, :version, :callback, :callback_context],
+                :required   => [: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 Zookeeper::Callbacks::VoidCallback and not rely on the string value.
+  #
+  def sync(options = {})
+    assert_open
+    assert_keys(options,
+                :supported  => [:path, :callback, :callback_context],
+                :required   => [: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_keys(options,
+                :supported  => [:path, :acl, :version, :callback, :callback_context],
+                :required   => [: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_keys(options,
+                :supported  => [:path, :callback, :callback_context],
+                :required   => [: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 underlying 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
+
+  # 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
+
+  # stop all underlying threads in preparation for a fork()
+  def pause_before_fork_in_parent
+    super
+  end
+
+  # re-start all underlying threads after performing a fork()
+  def resume_after_fork_in_parent
+    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 assert_valid_data_size!(data)
+    return if data.nil?
+
+    data = data.to_s
+    if data.length >= 1048576 # one megabyte 
+      raise Zookeeper::Exceptions::DataTooLargeException, "data must be smaller than 1 MiB, your data starts with: #{data[0..32].inspect}"
+    end
+    nil
+  end
+
+private
+  def assert_keys(args, opts={})
+    supported = opts[:supported] || []
+    required  = opts[:required]  || []
+
+    unless (args.keys - supported).empty?
+      raise Zookeeper::Exceptions::BadArguments,
+            "Supported arguments are: #{supported.inspect}, but arguments #{args.keys.inspect} were supplied instead"
+    end
+
+    unless (required - args.keys).empty?
+      raise Zookeeper::Exceptions::BadArguments,
+            "Required arguments are: #{required.inspect}, but only the arguments #{args.keys.inspect} were supplied."
+    end
+  end
+  
+  # must be supplied by parent class impl.
+  def assert_open
+    super
+  end
+end # ClientMethods
+end # Zookeeper