cequel 1.0.0.rc1 → 1.0.0.rc2

data/lib/cequel/record/configuration_generator.rb

@@ -1,5 +1,10 @@
 module Cequel
   module Record
+    #
+    # Rails generator for a default configuration file
+    #
+    # @since 1.0.0
+    #
     class ConfigurationGenerator < Rails::Generators::Base
       namespace 'cequel:configuration'
       source_root File.expand_path('../../../../templates/', __FILE__)

data/lib/cequel/record/data_set_builder.rb

@@ -0,0 +1,86 @@
+module Cequel
+  module Record
+    #
+    # This is a utility class to construct a {Metal::DataSet} for a given
+    # {RecordSet}.
+    #
+    # @api private
+    #
+    class DataSetBuilder
+      extend Forwardable
+
+      #
+      # Build a data set for the given record set
+      #
+      # @param (see #initialize)
+      # @return [Metal::DataSet] a DataSet exposing the rows for the record set
+      #
+      def self.build_for(record_set)
+        new(record_set).build
+      end
+
+      #
+      # @param record_set [RecordSet] record set for which to construct data
+      #   set
+      #
+      def initialize(record_set)
+        @record_set = record_set
+        @data_set = record_set.connection[record_set.target_class.table_name]
+      end
+      private_class_method :new
+
+      def build
+        add_limit
+        add_select_columns
+        add_where_statement
+        add_bounds
+        add_order
+        data_set
+      end
+
+      protected
+
+      attr_accessor :data_set
+      attr_reader :record_set
+      def_delegators :record_set, :row_limit, :select_columns,
+                     :scoped_key_names, :scoped_key_values,
+                     :scoped_indexed_column, :lower_bound,
+                     :upper_bound, :reversed?, :order_by_column
+
+      private
+
+      def add_limit
+        self.data_set = data_set.limit(row_limit) if row_limit
+      end
+
+      def add_select_columns
+        self.data_set = data_set.select(*select_columns) if select_columns
+      end
+
+      def add_where_statement
+        if scoped_key_values
+          key_conditions = Hash[scoped_key_names.zip(scoped_key_values)]
+          self.data_set = data_set.where(key_conditions)
+        end
+        if scoped_indexed_column
+          self.data_set = data_set.where(scoped_indexed_column)
+        end
+      end
+
+      def add_bounds
+        if lower_bound
+          self.data_set =
+            data_set.where(*lower_bound.to_cql_with_bind_variables)
+        end
+        if upper_bound
+          self.data_set =
+            data_set.where(*upper_bound.to_cql_with_bind_variables)
+        end
+      end
+
+      def add_order
+        self.data_set = data_set.order(order_by_column => :desc) if reversed?
+      end
+    end
+  end
+end

data/lib/cequel/record/dirty.rb

@@ -1,15 +1,21 @@
 module Cequel
-
   module Record
-
+    #
+    # Cequel provides support for dirty attribute tracking via ActiveModel.
+    # Modifications to collection columns are registered by this mechanism.
+    #
+    # @see http://api.rubyonrails.org/classes/ActiveModel/Dirty.html Rails
+    #   documentation for ActiveModel::Dirty
+    #
+    # @since 0.1.0
+    #
     module Dirty
-
       extend ActiveSupport::Concern
 
       included { include ActiveModel::Dirty }
 
+      # @private
       module ClassMethods
-
         def key(name, *)
           define_attribute_method(name)
           super
@@ -34,9 +40,9 @@ module Cequel
           define_attribute_method(name)
           super
         end
-
       end
 
+      # @private
       def save(options = {})
         super.tap do |success|
           if success
@@ -54,9 +60,6 @@ module Cequel
         end
         super
       end
-
     end
-
   end
-
 end

data/lib/cequel/record/errors.rb

@@ -1,14 +1,48 @@
 module Cequel
-
   module Record
-
+    #
+    # Raised when attempting to access an attribute of a record when that
+    # attribute hasn't been loaded
+    #
+    # @since 1.0.0
+    #
     MissingAttributeError = Class.new(ArgumentError)
+    #
+    # Raised when attempting to read or write an attribute that isn't defined
+    # on the record
+    #
+    # @since 1.0.0
+    #
     UnknownAttributeError = Class.new(ArgumentError)
+    #
+    # Raised when attempting to load a record by key when that record does not
+    # exist
+    #
     RecordNotFound = Class.new(StandardError)
+    #
+    # Raised when attempting to configure a record in a way that is not
+    # possible
+    #
+    # @since 1.0.0
+    #
     InvalidRecordConfiguration = Class.new(StandardError)
+    #
+    # Raised when attempting to save a record that is invalid
+    #
     RecordInvalid = Class.new(StandardError)
+    #
+    # Raised when attempting to construct a {RecordSet} that cannot construct
+    # a valid CQL query
+    #
+    # @since 1.0.0
+    #
     IllegalQuery = Class.new(StandardError)
-
+    #
+    # Raised when attempting to persist a Cequel::Record without defining all
+    # primary key columns
+    #
+    # @since 1.0.0
+    #
+    MissingKeyError = Class.new(StandardError)
   end
-
 end

data/lib/cequel/record/has_many_association.rb

@@ -1,26 +1,59 @@
 module Cequel
-
   module Record
-
+    #
+    # Represents a child association declared by
+    # {Associations::ClassMethods#has_many has_many}.
+    #
+    # @see Associations::ClassMethods#child_associations
+    # @since 1.0.0
+    #
     class HasManyAssociation
-
-      attr_reader :owner_class, :name, :association_class_name
-
+      # @return [Class] Record class that declares this association
+      attr_reader :owner_class
+      # @return [Symbol] name of this association
+      attr_reader :name
+      # @return [Symbol] name of the child class that this association contains
+      attr_reader :association_class_name
+      # @return [Boolean] behavior for propagating destruction from parent to
+      #   children
+      attr_reader :dependent
+
+      #
+      # @param owner_class [Class] Record class that declares this association
+      # @param name [Symbol] name of the association
+      # @param options [Options] options for the association
+      # @option options [Symbol] :class_name name of the child class
+      # @option options [Boolean] :dependent propagation behavior for destroy
+      #
+      # @api private
+      #
       def initialize(owner_class, name, options = {})
+        options.assert_valid_keys(:class_name, :dependent)
+
         @owner_class, @name = owner_class, name
-        @association_class_name = options.fetch(:class_name, name.to_s.classify)
+        @association_class_name =
+          options.fetch(:class_name, name.to_s.classify)
+        case options[:dependent]
+        when :destroy, :delete, nil
+          @dependent = options[:dependent]
+        else
+          fail ArgumentError,
+               "Invalid :dependent option #{options[:dependent].inspect}. " \
+               "Valid values are :destroy, :delete"
+        end
       end
 
+      #
+      # @return [Class] class of child association
+      #
       def association_class
         @association_class ||= association_class_name.constantize
       end
 
+      # @private
       def instance_variable_name
         @instance_variable_name ||= :"@#{name}"
       end
-
     end
-
   end
-
 end

data/lib/cequel/record/lazy_record_collection.rb

@@ -1,19 +1,36 @@
 module Cequel
-
   module Record
-
+    #
+    # Encapsulates a collection of unloaded {Record} instances. In the case
+    # where a record set is scoped to fully specify the keys of multiple
+    # records, those records will be returned unloaded in a
+    # LazyRecordCollection. When an attribute is read from any of the records
+    # in a LazyRecordCollection, it will eagerly load all of the records' rows
+    # from the database.
+    #
+    # @since 1.0.0
+    #
     class LazyRecordCollection < DelegateClass(Array)
-
       extend Forwardable
       include BulkWrites
-
+      #
+      # @!method table
+      #   (see RecordSet#table)
+      # @!method connection
+      #   (see RecordSet#connection)
       def_delegators :record_set, :table, :connection
 
+      #
+      # @param record_set [RecordSet] record set representing the records in
+      #   this collection
+      # @api private
+      #
       def initialize(record_set)
-        raise ArgumentError if record_set.nil?
+        fail ArgumentError if record_set.nil?
+        @record_set = record_set
 
         exploded_key_attributes = [{}].tap do |all_key_attributes|
-          record_set.key_columns.zip(record_set.scoped_key_attributes.values) do |column, values|
+          key_columns.zip(scoped_key_values) do |column, values|
             all_key_attributes.replace(Array(values).flat_map do |value|
               all_key_attributes.map do |key_attributes|
                 key_attributes.merge(column.name => value)
@@ -27,9 +44,12 @@ module Cequel
         end
 
         super(unloaded_records)
-        @record_set = record_set
       end
 
+      #
+      # Hydrate all the records in this collection from a database query
+      #
+      # @return [LazyRecordCollection] self
       def load!
         records_by_identity = index_by { |record| record.key_values }
 
@@ -37,17 +57,26 @@ module Cequel
           identity = row.values_at(*record_set.key_column_names)
           records_by_identity[identity].hydrate(row)
         end
+
+        loaded_count = count { |record| record.loaded? }
+        if loaded_count < count
+          fail Cequel::Record::RecordNotFound,
+               "Expected #{count} results; got #{loaded_count}"
+        end
+
+        self
       end
 
       private
+
       attr_reader :record_set
 
+      def_delegators :record_set, :key_columns, :scoped_key_values
+      private :key_columns, :scoped_key_values
+
       def key_attributes_for_each_row
         map { |record| record.key_attributes }
       end
-
     end
-
   end
-
 end

data/lib/cequel/record/mass_assignment.rb

@@ -5,11 +5,21 @@ rescue LoadError
 end
 
 module Cequel
-
   module Record
-
+    #
+    # Cequel supports mass-assignment protection in both the Rails 3 and Rails
+    # 4 paradigms. Rails 3 applications may define `attr_protected` and
+    # `attr_accessible` attributes in {Record} classes. In Rails 4, Cequel will
+    # respect strong parameters.
+    #
+    # @see https://github.com/rails/strong_parameters Rails 4 Strong Parameters
+    # @see
+    #   http://api.rubyonrails.org/v3.2.15/classes/ActiveModel/MassAssignmentSecurity.html
+    #   Rails 3 mass-assignment security
+    #
+    # @since 1.0.0
+    #
     module MassAssignment
-
       extend ActiveSupport::Concern
 
       included do
@@ -20,12 +30,10 @@ module Cequel
         end
       end
 
+      # @private
       def attributes=(attributes)
         super(sanitize_for_mass_assignment(attributes))
       end
-
     end
-
   end
-
 end

data/lib/cequel/record/persistence.rb

@@ -1,68 +1,173 @@
 module Cequel
-
   module Record
-
+    #
+    # This module provides functionality for loading and saving records to the
+    # Cassandra database.
+    #
+    # @see ClassMethods
+    #
+    # @since 0.1.0
+    #
     module Persistence
-
       extend ActiveSupport::Concern
       extend Forwardable
 
+      #
+      # Class-level functionality for loading and saving records
+      #
       module ClassMethods
-
         extend Forwardable
-        def_delegator 'Cequel::Record', :connection
 
+        #
+        # Initialize a new record instance, assign attributes, and immediately
+        # save it.
+        #
+        # @param attributes [Hash] attributes to assign to the new record
+        # @yieldparam record [Record] record to make modifications before
+        #   saving
+        # @return [Record] self
+        #
+        # @example Create a new record with attribute assignment
+        #   Post.create(
+        #     blog_subdomain: 'cassandra',
+        #     permalink: 'cequel',
+        #     title: 'Cequel: The Next Generation'
+        #   )
+        #
+        # @example Create a new record with a block
+        #   Post.create do |post|
+        #     post.blog = blog
+        #     post.permalink = 'cequel'
+        #     post.title = 'Cequel: The Next Generation'
+        #   end
+        #
         def create(attributes = {}, &block)
           new(attributes, &block).tap { |record| record.save }
         end
 
+        # @private
         def table
           connection[table_name]
         end
 
+        # @private
         def hydrate(row)
           new_empty(row).__send__(:hydrated!)
         end
 
+        # @private
+        def_delegator 'Cequel::Record', :connection
       end
 
-      def_delegators 'self.class', :connection, :table
-
+      #
+      # @return [Hash] the attributes of this record that make up the primary
+      #   key
+      #
+      # @example
+      #   post = Post.new
+      #   post.blog_subdomain = 'cassandra'
+      #   post.permalink = 'cequel'
+      #   post.title = 'Cequel: The Next Generation'
+      #   post.key_attributes
+      #     #=> {:blog_subdomain=>'cassandra', :permalink=>'cequel'}
+      #
+      # @since 1.0.0
+      #
       def key_attributes
         @attributes.slice(*self.class.key_column_names)
       end
 
+      #
+      # @return [Array] the values of the primary key columns for this record
+      #
+      # @see #key_attributes
+      # @since 1.0.0
+      #
       def key_values
         key_attributes.values
       end
 
+      #
+      # Check if an unloaded record exists in the database
+      #
+      # @return  `true` if the record has a corresponding row in the
+      #   database
+      #
+      # @since 1.0.0
+      #
       def exists?
         load!
         true
       rescue RecordNotFound
         false
       end
-      alias :exist? :exists?
-
+      alias_method :exist?, :exists?
+
+      #
+      # Load an unloaded record's row from the database and hydrate the
+      # record's attributes
+      #
+      # @return [Record] self
+      #
+      # @since 1.0.0
+      #
       def load
         assert_keys_present!
         record_collection.load! unless loaded?
         self
       end
 
+      #
+      # Attempt to load an unloaded record and raise an error if the record
+      # does not correspond to a row in the database
+      #
+      # @return [Record] self
+      # @raise [RecordNotFound] if row does not exist in the database
+      #
+      # @see #load
+      # @since 1.0.0
+      #
       def load!
         load.tap do
           if transient?
-            raise RecordNotFound,
-              "Couldn't find #{self.class.name} with #{key_attributes.inspect}"
+            fail RecordNotFound,
+                 "Couldn't find #{self.class.name} with " \
+                 "#{key_attributes.inspect}"
           end
         end
       end
 
+      #
+      # @overload loaded?
+      #   @return [Boolean] true if this record's attributes have been loaded
+      #     from the database
+      #
+      # @overload loaded?(column)
+      #   @param [Symbol] column name of column to check if loaded
+      #   @return [Boolean] true if the named column is loaded in memory
+      #
+      # @return [Boolean]
+      #
+      # @since 1.0.0
+      #
       def loaded?(column = nil)
         !!@loaded && (column.nil? || @attributes.key?(column.to_sym))
       end
 
+      #
+      # Persist the record to the database. If this is a new record, it will
+      # be saved using an INSERT statement. If it is an existing record, it
+      # will be persisted using a series of `UPDATE` and `DELETE` statements
+      # which will persist all changes to the database, including atomic
+      # collection modifications.
+      #
+      # @param options [Options] options for save
+      # @option options [Boolean] :validate (true) whether to run validations
+      #   before saving
+      # @return [Boolean] true if record saved successfully, false if invalid
+      #
+      # @see Validations#save!
+      #
       def save(options = {})
         options.assert_valid_keys
         if new_record? then create
@@ -72,11 +177,26 @@ module Cequel
         true
       end
 
+      #
+      # Set attributes and save the record
+      #
+      # @param attributes [Hash] hash of attributes to update
+      # @return [Boolean] true if saved successfully
+      #
+      # @see #save
+      # @see Properties#attributes=
+      # @see Validations#update_attributes!
+      #
       def update_attributes(attributes)
         self.attributes = attributes
         save
       end
 
+      #
+      # Remove this record from the database
+      #
+      # @return [Record] self
+      #
       def destroy
         assert_keys_present!
         metal_scope.delete
@@ -84,18 +204,34 @@ module Cequel
         self
       end
 
+      #
+      # @return true if this is a new, unsaved record
+      #
+      # @since 1.0.0
+      #
       def new_record?
         !!@new_record
       end
 
+      #
+      # @return true if this record is persisted in the database
+      #
+      # @see #transient?
+      #
       def persisted?
         !!@persisted
       end
 
+      #
+      # @return true if this record is not persisted in the database
+      #
+      # @see persisted?
+      #
       def transient?
         !persisted?
       end
 
+      # @private
       def hydrate(row)
         @attributes = row
         hydrated!
@@ -140,6 +276,9 @@ module Cequel
 
       private
 
+      def_delegators 'self.class', :connection, :table
+      private :connection, :table
+
       def read_attribute(attribute)
         super
       rescue MissingAttributeError
@@ -149,13 +288,14 @@ module Cequel
 
       def write_attribute(name, value)
         column = self.class.reflect_on_column(name)
-        raise UnknownAttributeError, "unknown attribute: #{name}" unless column
+        fail UnknownAttributeError, "unknown attribute: #{name}" unless column
         value = column.cast(value) unless value.nil?
 
         super.tap do
           unless new_record?
             if key_attributes.keys.include?(name)
-              raise ArgumentError, "Can't update key #{name} on persisted record"
+              fail ArgumentError,
+                   "Can't update key #{name} on persisted record"
             end
 
             if value.nil?
@@ -169,8 +309,8 @@ module Cequel
 
       def record_collection
         @record_collection ||=
-          LazyRecordCollection.new(self.class.at(*key_values)).
-          tap { |set| set.__setobj__([self]) }
+          LazyRecordCollection.new(self.class.at(*key_values))
+          .tap { |set| set.__setobj__([self]) }
       end
 
       def hydrated!
@@ -206,13 +346,10 @@ module Cequel
       def assert_keys_present!
         missing_keys = key_attributes.select { |k, v| v.nil? }
         if missing_keys.any?
-          raise MissingKeyError,
-            "Missing required key values: #{missing_keys.keys.join(', ')}"
+          fail MissingKeyError,
+               "Missing required key values: #{missing_keys.keys.join(', ')}"
         end
       end
-
     end
-
   end
-
 end