believer 0.1.4 → 0.2

data/README.md

@@ -12,31 +12,34 @@ The Believer library is heavily inspired by ActiveRecord. Most patterns used in
 ### Define your class
 An example:
 
-    require 'believer'
+``` ruby
+require 'believer'
 
-    class Artist < Believer::Base
-        column :name
-        column :label
+class Artist < Believer::Base
+    column :name
+    column :label
 
-        primary_key :name
-    end
+    primary_key :name
+end
 
-    class Album < Believer::Base
-        column :artist
-        column :name
-        column :release_date, :type => :timestamp
+class Album < Believer::Base
+    column :artist
+    column :name
+    column :release_date, :type => :timestamp
 
-        primary_key :artist, :name
-    end
+    primary_key :artist, :name
+end
 
-    class Song < Believer::Base
-        column :artist
-        column :album
-        column :name
-        column :track_number, :type => :integer
+class Song < Believer::Base
+    column :artist
+    column :album
+    column :name
+    column :track_number, :type => :integer
+    column :data, :cql_type => :blob
 
-        primary_key :artist, :album, :name
-    end
+    primary_key :artist, :album, :name
+end
+```
 
 #### The Believer::Base class
 This is the class you should extend from.
@@ -44,14 +47,25 @@ This is the class you should extend from.
 #### The column class method
 Defines the mapping between a Ruby object attribute and a Cassandra column. Also defines a getter and setter attribute with the same name.
 The second argument is a Hash, which support the following keys:
-* type: the data type. Supported are: :string, :integer, :float, :timestamp
-
+* type: the data type. Supported values are: :string, :integer, :float, :timestamp, :time
+* cql_type: the CQL data type.
+For type determination, you must include either or both the :type or the :cql_type options.
 
 #### The primary_key class method
 Sets the primary key columns of the class.
 In a situation where you're only querying data, you don't need to set this.
 However, if you rely on object equality somewhere in your application, it is advisable to set the primary key, as the primary key values are used in the Believer::Base.eql? method.
 
+If you wish to use a partition key consisting of multiple columns, use an array as the first part of the primary_key list:
+
+``` ruby
+class Song
+    ...
+    primary_key [:artist, :album], :name, :...
+    ...
+end
+```
+
 ### Query your class
 The following methods can be used to query class instances.
 * where: specify query filters
@@ -64,69 +78,170 @@ All methods are chainable, meaning you can
 #### The where method
 Use the where method to specify filters on the result set. These filters correspond to the expressions in the WHERE clause of a Cassandra query.
 
-    # Using a hash
-    Artist.where(:name => 'James Brown')
+``` ruby
+# Using a hash
+Artist.where(:name => 'James Brown')
 
-    # Using a hash mapping key to an array of possible values. Maps to the CQL IN operator
-    Artist.where(:name => ['Coldplay', 'Depeche Mode', 'Eurythmics'])
+# Using a hash mapping key to an array of possible values. Maps to the CQL IN operator
+Artist.where(:name => ['Coldplay', 'Depeche Mode', 'Eurythmics'])
 
-    # Using string with interpolation
-    Artist.where('name = ?', 'Foreigner')
+# Using string with interpolation
+Artist.where('name = ?', 'Foreigner')
+```
 
 #### The select method
 Using the select method you can define the columns loaded in a query. These fields correspond to the expressions in the SELECT clause of a Cassandra query.
 This might be handy in the case you have a table with a lot of columns, but only need a few.
 
-    # Select a single field
-    Artist.select(:name)
+``` ruby
+# Select a single field
+Artist.select(:name)
 
-    # Select a multiple fields
-    Artist.select(:name, :label)
+# Select a multiple fields
+Artist.select(:name, :label)
+```
 
 #### The limit method
 Limits the amount of records returned to the specified maximum
 
-    # Yield at most 20 class instances
-    Artist.limit(20)
+``` ruby
+# Yield at most 20 class instances
+Artist.limit(20)
+```
 
 #### The order method
 Order the results in using the specified column
 
-    # Order ascending by name
-    Album.order(:name)
-    Album.order(:name, :asc)
+``` ruby
+# Order ascending by name
+Album.order(:name)
+Album.order(:name, :asc)
 
-    # Order descending by name
-    Album.order(:name, :desc)
+# Order descending by name
+Album.order(:name, :desc)
+```
 
 #### Method chaining
 All query methods can be chained.
 This is done by creating and returning a clone of the receiver. The clone is the receiver of the query method.
 
-    # 'Echoes'....
-    Song.where(:artist => 'Pink Floyd').where(:album => 'Meddle').order(:track_number, :desc).limit(1)
+``` ruby
+# 'Echoes'....
+Song.where(:artist => 'Pink Floyd').where(:album => 'Meddle').order(:track_number, :desc).limit(1)
+```
 
 ### Configuration
 If using Rails, place a believer.yml file in the configuration directory of your application.
 The file structure starts with the the environment name, followed by the connection configuration.
 This is the client connection configuration passed to the cql-rb gem.
 
-    development:
-        host: 127.0.0.1
-        port: 9042
-        keyspace: my_keyspace
+``` yaml
+development:
+    host: 127.0.0.1
+    port: 9042
+    keyspace: my_keyspace
+
+staging:
+    host: 'staging.mynetwork.local'
+    port: 9042
+    keyspace: my_keyspace
+    credentials:
+        username: john
+        password: $FDFD%@#&*
+```
 
-    staging:
-        host: 'staging.mynetwork.local'
-        port: 9042
-        keyspace: my_keyspace
-        credentials:
-            username: john
-            password: $FDFD%@#&*
+In other cases, you will have to programatically set the environment:
 
+``` ruby
+Believer::Base.environment = Believer::Environment::BaseEnv.new(:host => '127.0.0.1',
+                                                                :keyspace => 'mykeyspace')
+```
+
+### Connection pooling
+If you wish to use a pool of connections, include a :pool node to the configuration.
+The pool library used is [connection_pool](https://github.com/mperham/connection_pool).
+
+``` yaml
+development:
+    host: 127.0.0.1
+    port: 9042
+    keyspace: my_keyspace
+    pool:
+        size: 10
+        timeout: 5
+```
+
+## Callbacks
+The Believer::Base supports several callbacks to hook into the lifecycle of the models.
+These callbacks can be included in the body of a Believer::Base subclass, like so:
+
+``` ruby
+class Song < Believer::Base
+    after_save :do_something
+
+    before_destroy do
+        puts "About to be destroyed: #{self}"
+    end
 
-In other cases, you will have to programatically set the environment:
+    def do_something
+        puts "Just been saved: #{self}"
+    end
+end
+```
+
+Supported callbacks are:
+* after_initialize
+* before_save
+* after_save
+* around_save
+* before_destroy
+* after_destroy
+* around_destroy
+
+## Relations
+If you include Believer::Relation in any class, you can define a relation between the including class and the Believer::Base instances.
+
+Supported relations are:
+* one-to-one: use the has_single method in the referencing class
+* one-to-many: use the has_some method in the referencing class
+
+Options for both relations are:
+* :class the name of the referenced class. If nil, it will be created from the relation name. Can be a constant or a String
+* :foreign_key the name of the attribute of the referenced class which acts as the key to this object. Can also be an array, in which case the cardinality and order must match with the :key option
+* :key the name of the attribute of the referencing class which acts as the key the referenced records. Can also be an array, in which case the cardinality and order must match with the :foreign_key option
+* :filter a Proc or lambda which is called with a Believer::Query instance as a parameter to tweak the relation query
+
+Example(s):
+
+``` ruby
+class Artist
+    include Believer::Relation
+
+    attr_accessor :name
+
+    has_some :albums, :class => 'Album', :key => :name, :foreign_key => :artist_name
+end
+
+class Album < Believer::Base
+    column :artist_name
+    column :name
+end
+
+class Song < Believer::Base
+    include Believer::Relation
+
+    column :artist_name
+    column :album_name
 
-    Believer::Base.environment = Believer::Environment::BaseEnv.new(:host => '127.0.0.1', :keyspace => 'mykeyspace')
+    has_single :album, :class => 'Test::Album', :key => [:artist_name, :album_name], :foreign_key => [:artist_name, :name]
+end
+```
 
+## Test support
+An important aspect to note is that Cassandra does not support transactional rollbacks.
+The consequence of this is that records persisted in a test case are not automatically deleted after a test has executed,
+causing you to 'manually' delete all the garbage.
 
+To make this a little less labor intensive, you can include the module Believer::Test::TestRunLifeCycle in your test.
+This module will implement an after(:each) hook, which deletes all Believer::Base instance/records created in the span
+of the test.

data/lib/believer.rb

@@ -13,31 +13,34 @@ require 'cql/client'
 
 require 'yaml'
 
-require 'believer/environment.rb'
+require 'believer/cql_helper'
+require 'believer/environment'
 require 'believer/environment/rails_env'
-require 'believer/connection.rb'
-require 'believer/values.rb'
-require 'believer/columns.rb'
-require 'believer/model_schema.rb'
-require 'believer/persistence.rb'
-require 'believer/command.rb'
-require 'believer/querying.rb'
-require 'believer/where_clause.rb'
-require 'believer/empty_result.rb'
-require 'believer/limit.rb'
-require 'believer/order_by.rb'
-require 'believer/scoped_command.rb'
-require 'believer/query.rb'
-require 'believer/delete.rb'
-require 'believer/insert.rb'
-require 'believer/scoping.rb'
-require 'believer/batch.rb'
-require 'believer/batch_delete.rb'
-require 'believer/callbacks.rb'
-
-require 'believer/observer.rb'
-require 'believer/owner.rb'
-
-require 'believer/ddl.rb'
-require 'believer/base.rb'
+require 'believer/environment/merb_env'
+require 'believer/connection'
+require 'believer/values'
+require 'believer/column'
+require 'believer/columns'
+require 'believer/model_schema'
+require 'believer/persistence'
+require 'believer/command'
+require 'believer/querying'
+require 'believer/where_clause'
+require 'believer/empty_result'
+require 'believer/limit'
+require 'believer/order_by'
+require 'believer/scoped_command'
+require 'believer/query'
+require 'believer/delete'
+require 'believer/insert'
+require 'believer/scoping'
+require 'believer/batch'
+require 'believer/batch_delete'
+require 'believer/callbacks'
+
+require 'believer/observer'
+require 'believer/relation'
+
+require 'believer/ddl'
+require 'believer/base'
 

data/lib/believer/base.rb

@@ -27,6 +27,8 @@ module Believer
       attrs.each do |name, val|
         send("#{name}=".to_sym, val)
       end if attrs.present?
+
+      yield self if block_given?
     end
 
     def self.instantiate_from_result_rows(row)

data/lib/believer/column.rb

@@ -0,0 +1,65 @@
+module Believer
+
+  # Represents a Cassandra table column
+  class Column
+    include Values
+
+    CQL_TYPES = {
+        :ascii => {:ruby_type => :string}, # strings US-ASCII character string
+        :bigint => {:ruby_type => :integer}, # integers 64-bit signed long
+        :blob => {:ruby_type => :string}, # blobs Arbitrary bytes (no validation), expressed as hexadecimal
+        :boolean => {:ruby_type => :boolean}, # booleans true or false
+        :counter => {:ruby_type => :integer}, # integers Distributed counter value (64-bit long)
+        :decimal => {:ruby_type => :float}, # integers, floats Variable-precision decimal
+        :double => {:ruby_type => :float}, # integers 64-bit IEEE-754 floating point
+        :float => {:ruby_type => :float}, # integers, floats 32-bit IEEE-754 floating point
+        :inet => {:ruby_type => :string}, # strings IP address string in IPv4 or IPv6 format*
+        :int => {:ruby_type => :integer}, # integers 32-bit signed integer
+        :list => {:ruby_type => :array}, # n/a A collection of one or more ordered elements
+        :map => {:ruby_type => :hash}, # n/a A JSON-style array of literals: { literal : literal, literal : literal ... }
+        :set => {:ruby_type => :array}, # n/a A collection of one or more elements
+        :text => {:ruby_type => :string}, # strings UTF-8 encoded string
+        :timestamp => {:ruby_type => :time}, # integers, strings Date plus time, encoded as 8 bytes since epoch
+        :uuid => {:ruby_type => :string}, # uuids A UUID in standard UUID format
+        :timeuuid => {:ruby_type => :integer}, # uuids Type 1 UUID only (CQL 3)
+        :varchar => {:ruby_type => :string}, # strings UTF-8 encoded string
+        :varint => {:ruby_type => :integer}, # integers Arbitrary-precision integer
+    }
+
+    # Supported Ruby 'types'
+    RUBY_TYPES = {
+        :integer => {:default_cql_type => :int},
+        :string => {:default_cql_type => :varchar},
+        :time => {:default_cql_type => :timestamp},
+        :timestamp => {:default_cql_type => :timestamp},
+        :float => {:default_cql_type => :float}
+    }
+
+    attr_reader :name, :type, :cql_type
+
+    # Creates a new instance.
+    # @param opts [Hash] values options
+    # @option opts :name the column name
+    # @option opts :type the Ruby type. Can be :integer, :string, :time, :timestamp, :float
+    # @option opts :cql_type the CQL type. See Cassandra CQL documentation and {#CQL_TYPES} for supported types
+    def initialize(opts)
+      raise "Must specify either a :type and/or a :cql_type" if opts[:type].nil? && opts[:cql_type].nil?
+      raise "Invalid CQL column type #{opts[:cql_type]}" if opts[:cql_type] && !CQL_TYPES.has_key?(opts[:cql_type])
+      raise "Invalid type #{opts[:type]}" unless RUBY_TYPES.has_key?(opts[:type])
+
+      @name = opts[:name]
+      @type = opts[:type].nil? ? CQL_TYPES[opts[:cql_type]][:ruby_type] : opts[:type]
+      @cql_type = opts[:cql_type].nil? ? RUBY_TYPES[opts[:type]][:default_cql_type] : opts[:cql_type]
+    end
+
+    # Converts the value to a one that conforms to the type of this column
+    # @param v [Object] the value
+    def convert_to_type(v)
+      convert_method = "convert_to_#{@type}".to_sym
+      return self.send(convert_method, v) if respond_to?(convert_method)
+      v
+    end
+
+  end
+
+end

data/lib/believer/columns.rb

@@ -19,61 +19,6 @@ module Believer
 
     end
 
-    class Column
-      #TYPES = {
-      #    :ascii	strings	US-ASCII character string
-      #bigint	integers	64-bit signed long
-      #blob	blobs	Arbitrary bytes (no validation), expressed as hexadecimal
-      #boolean	booleans	true or false
-      #counter	integers	Distributed counter value (64-bit long)
-      #decimal	integers, floats	Variable-precision decimal
-      #double	integers	64-bit IEEE-754 floating point
-      #float	integers, floats	32-bit IEEE-754 floating point
-      #inet	strings	IP address string in IPv4 or IPv6 format*
-      #                                                     int	integers	32-bit signed integer
-      #list	n/a	A collection of one or more ordered elements
-      #map	n/a	A JSON-style array of literals: { literal : literal, literal : literal ... }
-      #set	n/a	A collection of one or more elements
-      #text	strings	UTF-8 encoded string
-      #timestamp	integers, strings	Date plus time, encoded as 8 bytes since epoch
-      #uuid	uuids	A UUID in standard UUID format
-      #timeuuid	uuids	Type 1 UUID only (CQL 3)
-      #varchar	strings	UTF-8 encoded string
-      #varint	integers	Arbitrary-precision integer
-      #}
-      #
-      CQL_COL_TYPES = {
-          :integer => 'INT',
-          :string => 'VARCHAR',
-          :timestamp => 'TIMESTAMP',
-          :float => 'FlOAT'
-      }
-
-      attr_reader :name, :type
-
-      def initialize(opts)
-        @name = opts[:name]
-        @type = opts[:type]
-        raise "Invalid column type #{@type}" unless CQL_COL_TYPES.has_key?(@type)
-        @key = opts[:key] == true || !opts[:key].nil?
-        if @key && opts[:key].is_a?(Hash)
-          @partition_key = opts[:key][:partition_key]
-        end
-      end
-
-      def cql_column_type
-        CQL_COL_TYPES[@type]
-      end
-
-      def is_key?
-        @key
-      end
-
-      def is_partition_key?
-        @partition_key
-      end
-
-    end
 
     module ClassMethods
 
@@ -83,7 +28,7 @@ module Believer
         @columns ||= {}
       end
 
-        # Defines a column on the model.
+      # Defines a column on the model.
       # The column name must correspond with the Cassandra column name
       def column(name, opts = {})
         defaults = {
@@ -91,7 +36,7 @@ module Believer
         }
         options = defaults.merge(opts).merge(:name => name)
 
-        columns[name] = Column.new(options)
+        columns[name] = ::Believer::Column.new(options)
 
         self.redefine_method(name) do
           read_attribute(name)
@@ -152,11 +97,7 @@ module Believer
     def write_attribute(attr_name, value)
       v = value
       # Convert the value to the actual type
-      unless v.nil? && self.class.columns[attr_name]
-        value_type = self.class.columns[attr_name].type
-        convert_method = "convert_to_#{value_type}".to_sym
-        v = self.send(convert_method, v) if respond_to?(convert_method)
-      end
+      v = self.class.columns[attr_name].convert_to_type(v) unless self.class.columns[attr_name].nil?
       @attributes[attr_name] = v
     end