cassandra_mapper 0.0.1

data/README.rdoc

@@ -0,0 +1,98 @@
+= CassandraMapper: Easily build classes for working with Cassandra
+
++CassandraMapper+ uses the features and semantics of +SimpleMapper+ to make
+working with your Cassandra schema productive and expressive.
+
+Build your Cassandra-fronting model classes with +CassandraMapper+, using the
+same straightforward semantics of +SimpleMapper+.  +CassandraMapper+ adds in
+basic connection management (very basic, and easily customized) and persistence
+logic for inserting/updating via the Thrift client.
+
+    class Animal < CassandraMapper::Base
+      # specify the name of the column family fronted by this class
+      column_family 'Animals'
+      
+      # indicate which attribute should serve as the key for identification
+      key :species
+      
+      # specify the attributes you expect ala SimpleMapper
+      maps :species, :type => :string
+      maps :name,    :type => :string
+      
+      # define a custom type to define the domain of a given attribute
+      module DietaryPreference
+        DIETS = [:herbivore, :carnivore, :omnivore].inject({}) {|h, v| h[v] = v.to_s; h}
+        # encode should convert a "native" value (as you would work with it in Ruby)
+        # to the Cassandra storage format at it should be passed to Thrift.
+        def self.encode(value)
+          raise Exception unless value = DIETS[value]
+          value
+        end
+        # decode should convert a Cassandra/Thrift value to a "native" value (the inverse
+        # of encode)
+        def self.decode(value)
+          raise Exception unless DIETS.has_key?( key = value.to_sym )
+          key
+        end
+        # let's default to herbivore, for a kinder, gentler world
+        def self.default
+          :herbivore
+        end
+      end
+      
+      # Anything that has decode/encode/default can serve as a type,
+      # without being registered with the general symbol-lookup
+      # type registry.
+      # The :from_type default will mean the default value for this
+      # attribute (when it is left undefined) will come from the type.
+      maps :diet, :type => DietaryPreference, :default => :from_type     
+    end
+
+With a class defined, you can work with these objects as you would intuitively
+expect (though you'll need to see connection management topics to get this to work).
+
+    # now let's create some animals, in order of ascending stupidity
+    deer = Animal.new(:species => 'odocoileus virginianus',
+                      :name    => 'White-tailed Deer)
+    deer.save
+    gull = Animal.new(:species => 'larus occidentalis',
+                      :name    => 'Seagull',
+                      :diet    => :carnivore)
+    gull.save
+    human = Animal.new(:species => 'homo sapiens',
+                       :name    => 'Human',
+                       :diet    => :omnivore)
+    human.save
+    # and let's fetch 'em back.  Note that we didn't need to specify the :diet for the deer.
+    # This should return [:herbivore, :omnivore, :carnivore], though not necessarily in that order
+    Animal.find([human, deer, gull].collect {|animal| animal.species}).collect {|a| a.diet}
+
+= Connection Management
+
+As stated above, connection management is quite simple. Bare bones, in fact.
+
+At present, +CassandraMapper+ expects you to manage your connections to +Cassandra+
+yourself.  There are a variety of reasons for this.  The most important one is
+that the lack of transactional isolation, or even "session" isolation, and the
+whole eventually-consistent paradigm, effectively deprecate the idea of having all
+steps in a business transaction take place on the same connection.  If you're using
+Cassandra, chances are you're interested in serious scaling of writes or reads or
+both.  This is best achieved by managing connections yourself in a way that maximizes
+scalability/throughput for your use case.
+
+It is likely that connection management will be introduced in more sophisticated form
+in the reasonably near future, but that's not the most pressing priority.  So, for
+the time being, connections are at the class level (like in +ActiveRecord+) and need
+to be explicitly assigned.
+
+Thus, for the +Animal+ set/get examples above to truly work, you would need to
+get an instance of the +Cassandra+ thrift client (+Cassandra.new(...)+), and
+you would need to assign it to the +Animal+ class.
+
+    # load up the Cassandra client
+    require 'cassandra'
+    # get a connection and assign it to the class.
+    Animal.connection = Cassandra.new('YourKeyspace', '127.0.0.1:9160')
+
+A near-term improvement will allow per-object specification of the connection,
+for more flexible management.

data/Rakefile.rb

@@ -0,0 +1,11 @@
+require 'rake'
+require 'rake/testtask'
+require 'rake/clean'
+
+CLOBBER.include('cassandra_mapper-*.gem')
+
+Rake::TestTask.new do |t|
+  t.pattern = 'test/**/*_test.rb'
+  t.libs = ['test', 'lib']
+end
+

data/lib/cassandra_mapper.rb

@@ -0,0 +1,5 @@
+require 'cassandra'
+module CassandraMapper
+  require 'cassandra_mapper/exceptions'
+  autoload :Base, 'cassandra_mapper/base'
+end

data/lib/cassandra_mapper/base.rb

@@ -0,0 +1,19 @@
+require 'simple_mapper'
+class CassandraMapper::Base
+  include SimpleMapper::Attributes
+
+  require 'cassandra_mapper/identity'
+  include CassandraMapper::Identity
+
+  require 'cassandra_mapper/persistence'
+  include CassandraMapper::Persistence
+
+  require 'cassandra_mapper/connection'
+  include CassandraMapper::Connection
+
+  require 'cassandra_mapper/observable'
+  include CassandraMapper::Observable
+
+  require 'cassandra_mapper/indexing'
+  include CassandraMapper::Indexing
+end

data/lib/cassandra_mapper/connection.rb

@@ -0,0 +1,9 @@
+module CassandraMapper::Connection
+  def connection=(conn)
+    @connection = conn
+  end
+
+  def connection
+    @connection || self.class.connection
+  end
+end

data/lib/cassandra_mapper/core_ext/array/extract_options.rb

@@ -0,0 +1,29 @@
+class Hash
+  # By default, only instances of Hash itself are extractable.
+  # Subclasses of Hash may implement this method and return
+  # true to declare themselves as extractable. If a Hash
+  # is extractable, Array#extract_options! pops it from
+  # the Array when it is the last element of the Array.
+  def extractable_options?
+    instance_of?(Hash)
+  end
+end
+
+class Array
+  # Extracts options from a set of arguments. Removes and returns the last
+  # element in the array if it's a hash, otherwise returns a blank hash.
+  #
+  #   def options(*args)
+  #     args.extract_options!
+  #   end
+  #
+  #   options(1, 2)           # => {}
+  #   options(1, 2, :a => :b) # => {:a=>:b}
+  def extract_options!
+    if last.is_a?(Hash) && last.extractable_options?
+      pop
+    else
+      {}
+    end
+  end
+end

data/lib/cassandra_mapper/core_ext/array/wrap.rb

@@ -0,0 +1,22 @@
+class Array
+  # Wraps the object in an Array unless it's an Array.  Converts the
+  # object to an Array using #to_ary if it implements that.
+  #
+  # It differs with Array() in that it does not call +to_a+ on
+  # the argument:
+  #
+  #   Array(:foo => :bar)      # => [[:foo, :bar]]
+  #   Array.wrap(:foo => :bar) # => [{:foo => :bar}]
+  #
+  #   Array("foo\nbar")        # => ["foo\n", "bar"], in Ruby 1.8
+  #   Array.wrap("foo\nbar")   # => ["foo\nbar"]
+  def self.wrap(object)
+    if object.nil?
+      []
+    elsif object.respond_to?(:to_ary)
+      object.to_ary
+    else
+      [object]
+    end
+  end
+end

data/lib/cassandra_mapper/core_ext/class/inheritable_attributes.rb

@@ -0,0 +1,232 @@
+require 'cassandra_mapper/core_ext/object/duplicable'
+require 'cassandra_mapper/core_ext/array/extract_options'
+
+# Retain for backward compatibility.  Methods are now included in Class.
+module ClassInheritableAttributes # :nodoc:
+end
+
+# Allows attributes to be shared within an inheritance hierarchy, but where each descendant gets a copy of
+# their parents' attributes, instead of just a pointer to the same. This means that the child can add elements
+# to, for example, an array without those additions being shared with either their parent, siblings, or
+# children, which is unlike the regular class-level attributes that are shared across the entire hierarchy.
+#
+# The copies of inheritable parent attributes are added to subclasses when they are created, via the
+# +inherited+ hook.
+class Class # :nodoc:
+  def class_inheritable_reader(*syms)
+    options = syms.extract_options!
+    syms.each do |sym|
+      next if sym.is_a?(Hash)
+      class_eval(<<-EOS, __FILE__, __LINE__ + 1)
+        def self.#{sym}                                # def self.after_add
+          read_inheritable_attribute(:#{sym})          #   read_inheritable_attribute(:after_add)
+        end                                            # end
+                                                       #
+        #{"                                            #
+        def #{sym}                                     # def after_add
+          self.class.#{sym}                            #   self.class.after_add
+        end                                            # end
+        " unless options[:instance_reader] == false }  # # the reader above is generated unless options[:instance_reader] == false
+      EOS
+    end
+  end
+
+  def class_inheritable_writer(*syms)
+    options = syms.extract_options!
+    syms.each do |sym|
+      class_eval(<<-EOS, __FILE__, __LINE__ + 1)
+        def self.#{sym}=(obj)                          # def self.color=(obj)
+          write_inheritable_attribute(:#{sym}, obj)    #   write_inheritable_attribute(:color, obj)
+        end                                            # end
+                                                       #
+        #{"                                            #
+        def #{sym}=(obj)                               # def color=(obj)
+          self.class.#{sym} = obj                      #   self.class.color = obj
+        end                                            # end
+        " unless options[:instance_writer] == false }  # # the writer above is generated unless options[:instance_writer] == false
+      EOS
+    end
+  end
+
+  def class_inheritable_array_writer(*syms)
+    options = syms.extract_options!
+    syms.each do |sym|
+      class_eval(<<-EOS, __FILE__, __LINE__ + 1)
+        def self.#{sym}=(obj)                          # def self.levels=(obj)
+          write_inheritable_array(:#{sym}, obj)        #   write_inheritable_array(:levels, obj)
+        end                                            # end
+                                                       #
+        #{"                                            #
+        def #{sym}=(obj)                               # def levels=(obj)
+          self.class.#{sym} = obj                      #   self.class.levels = obj
+        end                                            # end
+        " unless options[:instance_writer] == false }  # # the writer above is generated unless options[:instance_writer] == false
+      EOS
+    end
+  end
+
+  def class_inheritable_hash_writer(*syms)
+    options = syms.extract_options!
+    syms.each do |sym|
+      class_eval(<<-EOS, __FILE__, __LINE__ + 1)
+        def self.#{sym}=(obj)                          # def self.nicknames=(obj)
+          write_inheritable_hash(:#{sym}, obj)         #   write_inheritable_hash(:nicknames, obj)
+        end                                            # end
+                                                       #
+        #{"                                            #
+        def #{sym}=(obj)                               # def nicknames=(obj)
+          self.class.#{sym} = obj                      #   self.class.nicknames = obj
+        end                                            # end
+        " unless options[:instance_writer] == false }  # # the writer above is generated unless options[:instance_writer] == false
+      EOS
+    end
+  end
+
+  def class_inheritable_accessor(*syms)
+    class_inheritable_reader(*syms)
+    class_inheritable_writer(*syms)
+  end
+
+  def class_inheritable_array(*syms)
+    class_inheritable_reader(*syms)
+    class_inheritable_array_writer(*syms)
+  end
+
+  def class_inheritable_hash(*syms)
+    class_inheritable_reader(*syms)
+    class_inheritable_hash_writer(*syms)
+  end
+
+  def inheritable_attributes
+    @inheritable_attributes ||= EMPTY_INHERITABLE_ATTRIBUTES
+  end
+
+  def write_inheritable_attribute(key, value)
+    if inheritable_attributes.equal?(EMPTY_INHERITABLE_ATTRIBUTES)
+      @inheritable_attributes = {}
+    end
+    inheritable_attributes[key] = value
+  end
+
+  def write_inheritable_array(key, elements)
+    write_inheritable_attribute(key, []) if read_inheritable_attribute(key).nil?
+    write_inheritable_attribute(key, read_inheritable_attribute(key) + elements)
+  end
+
+  def write_inheritable_hash(key, hash)
+    write_inheritable_attribute(key, {}) if read_inheritable_attribute(key).nil?
+    write_inheritable_attribute(key, read_inheritable_attribute(key).merge(hash))
+  end
+
+  def read_inheritable_attribute(key)
+    inheritable_attributes[key]
+  end
+
+  def reset_inheritable_attributes
+    @inheritable_attributes = EMPTY_INHERITABLE_ATTRIBUTES
+  end
+
+  private
+    # Prevent this constant from being created multiple times
+    EMPTY_INHERITABLE_ATTRIBUTES = {}.freeze unless const_defined?(:EMPTY_INHERITABLE_ATTRIBUTES)
+
+    def inherited_with_inheritable_attributes(child)
+      inherited_without_inheritable_attributes(child) if respond_to?(:inherited_without_inheritable_attributes)
+
+      if inheritable_attributes.equal?(EMPTY_INHERITABLE_ATTRIBUTES)
+        new_inheritable_attributes = EMPTY_INHERITABLE_ATTRIBUTES
+      else
+        new_inheritable_attributes = inheritable_attributes.inject({}) do |memo, (key, value)|
+          memo.update(key => value.duplicable? ? value.dup : value)
+        end
+      end
+
+      child.instance_variable_set('@inheritable_attributes', new_inheritable_attributes)
+    end
+
+    alias inherited_without_inheritable_attributes inherited
+    alias inherited inherited_with_inheritable_attributes
+end
+
+class Class
+  # Defines class-level inheritable attribute reader. Attributes are available to subclasses,
+  # each subclass has a copy of parent's attribute.
+  #
+  # @param *syms<Array[#to_s]> Array of attributes to define inheritable reader for.
+  # @return <Array[#to_s]> Array of attributes converted into inheritable_readers.
+  #
+  # @api public
+  #
+  # @todo Do we want to block instance_reader via :instance_reader => false
+  # @todo It would be preferable that we do something with a Hash passed in
+  #   (error out or do the same as other methods above) instead of silently
+  #   moving on). In particular, this makes the return value of this function
+  #   less useful.
+  def extlib_inheritable_reader(*ivars, &block)
+    options = ivars.extract_options!
+
+    ivars.each do |ivar|
+      self.class_eval <<-RUBY, __FILE__, __LINE__ + 1
+        def self.#{ivar}
+          return @#{ivar} if self.object_id == #{self.object_id} || defined?(@#{ivar})
+          ivar = superclass.#{ivar}
+          return nil if ivar.nil? && !#{self}.instance_variable_defined?("@#{ivar}")
+          @#{ivar} = ivar.duplicable? ? ivar.dup : ivar
+        end
+      RUBY
+      unless options[:instance_reader] == false
+        self.class_eval <<-RUBY, __FILE__, __LINE__ + 1
+          def #{ivar}
+            self.class.#{ivar}
+          end
+        RUBY
+      end
+      instance_variable_set(:"@#{ivar}", yield) if block_given?
+    end
+  end
+
+  # Defines class-level inheritable attribute writer. Attributes are available to subclasses,
+  # each subclass has a copy of parent's attribute.
+  #
+  # @param *syms<Array[*#to_s, Hash{:instance_writer => Boolean}]> Array of attributes to
+  #   define inheritable writer for.
+  # @option syms :instance_writer<Boolean> if true, instance-level inheritable attribute writer is defined.
+  # @return <Array[#to_s]> An Array of the attributes that were made into inheritable writers.
+  #
+  # @api public
+  #
+  # @todo We need a style for class_eval <<-HEREDOC. I'd like to make it
+  #   class_eval(<<-RUBY, __FILE__, __LINE__), but we should codify it somewhere.
+  def extlib_inheritable_writer(*ivars)
+    options = ivars.extract_options!
+
+    ivars.each do |ivar|
+      self.class_eval <<-RUBY, __FILE__, __LINE__ + 1
+        def self.#{ivar}=(obj)
+          @#{ivar} = obj
+        end
+      RUBY
+      unless options[:instance_writer] == false
+        self.class_eval <<-RUBY, __FILE__, __LINE__ + 1
+          def #{ivar}=(obj) self.class.#{ivar} = obj end
+        RUBY
+      end
+
+      self.send("#{ivar}=", yield) if block_given?
+    end
+  end
+
+  # Defines class-level inheritable attribute accessor. Attributes are available to subclasses,
+  # each subclass has a copy of parent's attribute.
+  #
+  # @param *syms<Array[*#to_s, Hash{:instance_writer => Boolean}]> Array of attributes to
+  #   define inheritable accessor for.
+  # @option syms :instance_writer<Boolean> if true, instance-level inheritable attribute writer is defined.
+  # @return <Array[#to_s]> An Array of attributes turned into inheritable accessors.
+  #
+  # @api public
+  def extlib_inheritable_accessor(*syms, &block)
+    extlib_inheritable_reader(*syms)
+    extlib_inheritable_writer(*syms, &block)
+  end
+end

data/lib/cassandra_mapper/core_ext/kernel/reporting.rb

@@ -0,0 +1,62 @@
+require 'rbconfig'
+module Kernel
+  # Sets $VERBOSE to nil for the duration of the block and back to its original value afterwards.
+  #
+  #   silence_warnings do
+  #     value = noisy_call # no warning voiced
+  #   end
+  #
+  #   noisy_call # warning voiced
+  def silence_warnings
+    with_warnings(nil) { yield }
+  end
+
+  # Sets $VERBOSE to true for the duration of the block and back to its original value afterwards.
+  def enable_warnings
+    with_warnings(true) { yield }
+  end
+
+  # Sets $VERBOSE for the duration of the block and back to its original value afterwards.
+  def with_warnings(flag)
+    old_verbose, $VERBOSE = $VERBOSE, flag
+    yield
+  ensure
+    $VERBOSE = old_verbose
+  end
+
+  # For compatibility
+  def silence_stderr #:nodoc:
+    silence_stream(STDERR) { yield }
+  end
+
+  # Silences any stream for the duration of the block.
+  #
+  #   silence_stream(STDOUT) do
+  #     puts 'This will never be seen'
+  #   end
+  #
+  #   puts 'But this will'
+  def silence_stream(stream)
+    old_stream = stream.dup
+    stream.reopen(Config::CONFIG['host_os'] =~ /mswin|mingw/ ? 'NUL:' : '/dev/null')
+    stream.sync = true
+    yield
+  ensure
+    stream.reopen(old_stream)
+  end
+
+  # Blocks and ignores any exception passed as argument if raised within the block.
+  #
+  #   suppress(ZeroDivisionError) do
+  #     1/0
+  #     puts "This code is NOT reached"
+  #   end
+  #
+  #   puts "This code gets executed and nothing related to ZeroDivisionError was seen"
+  def suppress(*exception_classes)
+    begin yield
+    rescue Exception => e
+      raise unless exception_classes.any? { |cls| e.kind_of?(cls) }
+    end
+  end
+end