cequel 1.0.0.rc1 → 1.0.0.rc2

data/lib/cequel/metal/writer.rb

@@ -1,19 +1,36 @@
-require 'delegate'
-
 module Cequel
-
   module Metal
-
+    #
+    # Internal representation of a data manipulation statement
+    #
+    # @abstract Subclasses must implement #write_to_statement, which writes
+    #   internal state to a Statement instance
+    #
+    # @since 1.0.0
+    # @api private
+    #
     class Writer
-
       extend Forwardable
 
+      #
+      # @param data_set [DataSet] data set to write to
+      # @param options [Options] options
+      # @option options [Integer] :ttl time-to-live in seconds for the written
+      #   data
+      # @option options [Time,Integer] :timestamp the timestamp associated with
+      #   the column values
+      #
       def initialize(data_set, options = {}, &block)
         @data_set, @options, @block = data_set, options, block
         @statements, @bind_vars = [], []
         SimpleDelegator.new(self).instance_eval(&block) if block
       end
 
+      #
+      # Execute the statement as a write operation
+      #
+      # @return [void]
+      #
       def execute
         return if empty?
         statement = Statement.new
@@ -23,6 +40,7 @@ module Cequel
       end
 
       private
+
       attr_reader :data_set, :options, :statements, :bind_vars
       def_delegator :data_set, :table_name
       def_delegator :statements, :empty?
@@ -44,11 +62,6 @@ module Cequel
       #
       # Generate CQL option statement for inserts and updates
       #
-      # @param [Hash] options options for insert
-      # @option options [Symbol,String] :consistency required consistency for the write
-      # @option options [Integer] :ttl time-to-live in seconds for the written data
-      # @option options [Time,Integer] :timestamp the timestamp associated with the column values
-      #
       def generate_upsert_options
         if options.empty?
           ''
@@ -57,7 +70,6 @@ module Cequel
           options.map do |key, value|
             serialized_value =
               case key
-              when :consistency then value.to_s.upcase
               when :timestamp then (value.to_f * 1_000_000).to_i
               else value
               end
@@ -65,9 +77,6 @@ module Cequel
           end.join(' AND ')
         end
       end
-
     end
-
   end
-
 end

data/lib/cequel/record.rb

@@ -8,6 +8,7 @@ require 'cequel/record/collection'
 require 'cequel/record/persistence'
 require 'cequel/record/bulk_writes'
 require 'cequel/record/record_set'
+require 'cequel/record/data_set_builder'
 require 'cequel/record/bound'
 require 'cequel/record/lazy_record_collection'
 require 'cequel/record/scoped'
@@ -28,9 +29,50 @@ if defined? Rails
 end
 
 module Cequel
-
+  #
+  # Cequel::Record is an active record-style data modeling library and
+  # object-row mapper. Model classes inherit from Cequel::Record, define their
+  # columns in the class definition, and have access to a full and robust set
+  # of read and write functionality.
+  #
+  # Individual components are documented in their respective modules. See below
+  # for links.
+  #
+  # @example A Record class showing off many of the possibilities
+  #   class Post
+  #     include Cequel::Record
+  #
+  #     belongs_to :blog
+  #     key :id, :timeuuid, auto: true
+  #     column :title, :text
+  #     column :body, :text
+  #     column :author_id, :uuid, index: true
+  #     set :categories
+  #
+  #     has_many :comments, dependent: destroy
+  #
+  #     after_create :notify_followers
+  #
+  #     validates :title, presence: true
+  #
+  #     def self.for_author(author_id)
+  #       where(:author_id, author_id)
+  #     end
+  #   end
+  #
+  # @see Properties Defining properties
+  # @see Collection Collection columns
+  # @see SecondaryIndexes Defining secondary indexes
+  # @see Associations Defining associations between records
+  # @see Persistence Creating, updating, and destroying records
+  # @see BulkWrites Updating and destroying records in bulk
+  # @see RecordSet Loading records from the database
+  # @see MassAssignment Mass-assignment protection and strong attributes
+  # @see Callbacks Lifecycle hooks
+  # @see Validations
+  # @see Dirty Dirty attribute tracking
+  #
   module Record
-
     extend ActiveSupport::Concern
     extend Forwardable
 
@@ -48,18 +90,22 @@ module Cequel
       extend ActiveModel::Naming
       include ActiveModel::Serializers::JSON
       include ActiveModel::Serializers::Xml
-
     end
 
     class <<self
+      # @return [Metal::Keyspace] the keyspace used for record persistence
       attr_accessor :connection
 
+      #
+      # Establish a connection with the given configuration
+      #
+      # @param (see Cequel.connect)
+      # @option (see Cequel.connect)
+      # @return [void]
+      #
       def establish_connection(configuration)
         self.connection = Cequel.connect(configuration)
       end
-
     end
-
   end
-
 end

data/lib/cequel/record/association_collection.rb

@@ -1,11 +1,21 @@
 module Cequel
-
   module Record
-
+    #
+    # Collection of records from a
+    # {Associations::ClassMethods#has_many has_many} associaiton. Encapsulates
+    # and behaves like a {RecordSet}, but unlike a normal RecordSet the loaded
+    # records are held in memory after they are loaded.
+    #
+    # @see Associations::ClassMethods#has_many
+    # @since 1.0.0
+    #
     class AssociationCollection < DelegateClass(RecordSet)
-
       include Enumerable
 
+      #
+      # @yield [Record]
+      # @return [void]
+      #
       def each(&block)
         target.each(&block)
       end
@@ -15,9 +25,6 @@ module Cequel
       def target
         @target ||= __getobj__.entries
       end
-
     end
-
   end
-
 end

data/lib/cequel/record/associations.rb

@@ -1,9 +1,55 @@
 module Cequel
-
   module Record
-
+    #
+    # Cequel records can have parent-child relationships defined by
+    # {ClassMethods#belongs_to belongs_to} and {ClassMethods#has_many has_many}
+    # associations. Unlike in a relational database ORM, associations are not
+    # represented by foreign keys; instead they use CQL3's compound primary
+    # keys. A child object's primary key begins with it's parent's primary key.
+    #
+    # In the below example, the `blogs` table has a one-column primary key
+    # `(subdomain)`, and the `posts` table has a two-column primary key
+    # `(blog_subdomain, permalink)`. All posts that belong to the blog with
+    # subdomain `"cassandra"` will have `"cassandra"` as their
+    # `blog_subdomain`.
+    #
+    # @example Blogs and Posts
+    #
+    #   class Blog
+    #     include Cequel::Record
+    #
+    #     key :subdomain, :text
+    #
+    #     column :name, :text
+    #
+    #     has_many :posts
+    #   end
+    #
+    #   class Post
+    #     include Cequel::Record
+    #
+    #     # This defines the first primary key column as `blog_subdomain`.
+    #     # Because `belongs_to` associations implicitly define columns in the
+    #     # primary key, it must come before any explicit key definition. For
+    #     # the same reason, a Record class can only have a single `belongs_to`
+    #     # declaration.
+    #     belongs_to :blog
+    #
+    #     # We also define an additional primary key column so that each post
+    #     # has a unique compound primary key
+    #     key :permalink
+    #
+    #     column :title, :text
+    #     column :body, :text
+    #   end
+    #
+    #   blog = Blog.new(subdomain: 'cassandra')
+    #   post = blog.posts.new(permalink: 'cequel')
+    #   post.blog_subdomain #=> "cassandra"
+    #
+    # @since 1.0.0
+    #
     module Associations
-
       extend ActiveSupport::Concern
 
       included do
@@ -12,43 +58,83 @@ module Cequel
         self.child_associations = {}
       end
 
+      #
+      # Class macros for declaring associations
+      #
+      # @see Associations
+      #
       module ClassMethods
-
         include Forwardable
 
-        def belongs_to(name)
+        # @!attribute parent_association
+        #   @return [BelongsToAssociation] association declared by
+        #     {#belongs_to}
+        # @!attribute child_associations
+        #   @return [Hash<Symbol,HasManyAssociation>] associations declared by
+        #     {#has_many}
+
+        #
+        # Declare the parent association for this record. The name of the class
+        # is inferred from the name of the association. The `belongs_to`
+        # declaration also serves to define key columns, which are derived from
+        # the key columns of the parent class. So, if the parent class `Blog`
+        # has a primary key `(subdomain)`, this will declare a key column
+        # `blog_subdomain` of the same type.
+        #
+        # Parent associations are read/write, so declaring `belongs_to :blog`
+        # will define a `blog` getter and `blog=` setter, which will update the
+        # underlying key column. Note that a record's parent cannot be changed
+        # once the record has been saved.
+        #
+        # @param name [Symbol] name of the parent association
+        # @param options [Options] options for association
+        # @option (see BelongsToAssociation#initialize)
+        # @return [void]
+        #
+        # @see Associations
+        #
+        def belongs_to(name, options = {})
           if parent_association
-            raise InvalidRecordConfiguration,
-              "Can't declare more than one belongs_to association"
+            fail InvalidRecordConfiguration,
+                 "Can't declare more than one belongs_to association"
           end
           if table_schema.key_columns.any?
-            raise InvalidRecordConfiguration,
-              "belongs_to association must be declared before declaring key(s)"
+            fail InvalidRecordConfiguration,
+                 "belongs_to association must be declared before declaring " \
+                 "key(s)"
           end
-          self.parent_association = BelongsToAssociation.new(self, name.to_sym)
+
+          self.parent_association =
+            BelongsToAssociation.new(self, name.to_sym, options)
+
           parent_association.association_key_columns.each do |column|
             key :"#{name}_#{column.name}", column.type
           end
           def_parent_association_accessors
         end
 
+        #
+        # Declare a child association. The child association should have a
+        # `belongs_to` referencing this class or, at a minimum, must have a
+        # primary key whose first N columns have the same types as the N
+        # columns in this class's primary key.
+        #
+        # `has_many` associations are read-only, so `has_many :posts` will
+        # define a `posts` reader but not a `posts=` writer; and the collection
+        # returned by `posts` will be immutable.
+        #
+        # @param name [Symbol] plural name of association
+        # @param options [Options] options for association
+        # @option (see HasManyAssociation#initialize)
+        # @return [void]
+        #
+        # @see Associations
+        #
         def has_many(name, options = {})
-          options.assert_valid_keys(:dependent)
-
-          association = HasManyAssociation.new(self, name.to_sym)
+          association = HasManyAssociation.new(self, name.to_sym, options)
           self.child_associations =
             child_associations.merge(name => association)
           def_child_association_reader(association)
-
-          case options[:dependent]
-          when :destroy
-            after_destroy { delete_children(name, true) }
-          when :delete
-            after_destroy { delete_children(name) }
-          when nil
-          else
-            raise ArgumentError, "Invalid option #{options[:dependent].inspect} provided for :dependent. Specify :destroy or :delete."
-          end
         end
 
         private
@@ -60,12 +146,12 @@ module Cequel
 
         def def_parent_association_reader
           def_delegator 'self', :read_parent_association,
-            parent_association.name
+                        parent_association.name
         end
 
         def def_parent_association_writer
           def_delegator 'self', :write_parent_association,
-            "#{parent_association.name}="
+                        "#{parent_association.name}="
         end
 
         def def_child_association_reader(association)
@@ -75,7 +161,22 @@ module Cequel
             end
           RUBY
         end
+      end
 
+      #
+      # @private
+      #
+      def destroy(*)
+        super.tap do
+          self.class.child_associations.each_value do |association|
+            case association.dependent
+            when :destroy
+              __send__(association.name).destroy_all
+            when :delete
+              __send__(association.name).delete_all
+            end
+          end
+        end
       end
 
       private
@@ -85,11 +186,11 @@ module Cequel
         if instance_variable_defined?(ivar_name)
           return instance_variable_get(ivar_name)
         end
-        parent_key_values = key_values.
-          first(parent_association.association_key_columns.length)
+        parent_key_values = key_values
+          .first(parent_association.association_key_columns.length)
         if parent_key_values.none? { |value| value.nil? }
           clazz = parent_association.association_class
-          parent = parent_key_values.inject(clazz) do |record_set, key_value|
+          parent = parent_key_values.reduce(clazz) do |record_set, key_value|
             record_set[key_value]
           end
           instance_variable_set(ivar_name, parent)
@@ -98,19 +199,20 @@ module Cequel
 
       def write_parent_association(parent)
         unless parent.is_a?(parent_association.association_class)
-          raise ArgumentError,
-            "Wrong class for #{parent_association.name}; expected " +
-            "#{parent_association.association_class.name}, got " +
-            "#{parent.class.name}"
+          fail ArgumentError,
+               "Wrong class for #{parent_association.name}; expected " \
+               "#{parent_association.association_class.name}, got " \
+               "#{parent.class.name}"
         end
         instance_variable_set "@#{parent_association.name}", parent
         key_column_names = self.class.key_column_names
-        parent.key_attributes.
-          zip(key_column_names) do |(parent_column_name, value), column_name|
+        parent.key_attributes
+          .zip(key_column_names) do |(parent_column_name, value), column_name|
             if value.nil?
-              raise ArgumentError,
-                "Can't set parent association #{parent_association.name.inspect} " +
-                "without value in key #{parent_column_name.inspect}"
+              fail ArgumentError,
+                   "Can't set parent association " \
+                   "#{parent_association.name.inspect} " \
+                   "without value in key #{parent_column_name.inspect}"
             end
             write_attribute(column_name, value)
           end
@@ -122,26 +224,16 @@ module Cequel
         if !reload && instance_variable_defined?(ivar)
           return instance_variable_get(ivar)
         end
-        association_record_set = key_values.inject(association.association_class) do |record_set, key_value|
-          record_set[key_value]
-        end
-        instance_variable_set(
-          ivar, AssociationCollection.new(association_record_set))
-      end
 
-      def delete_children(association_name, run_callbacks = false)
-        if run_callbacks
-          self.send(association_name).each do |c|
-            c.run_callbacks(:destroy)
+        base_scope = association.association_class
+        association_record_set =
+          key_values.reduce(base_scope) do |record_set, key_value|
+            record_set[key_value]
           end
-        end
-        connection[association_name].where(
-          send(association_name).scoped_key_attributes
-        ).delete
-      end
 
+        instance_variable_set(
+          ivar, AssociationCollection.new(association_record_set))
+      end
     end
-
   end
-
 end