cequel 1.0.0.rc1 → 1.0.0.rc2

data/lib/cequel/metal/deleter.rb

@@ -1,21 +1,58 @@
 module Cequel
-
   module Metal
-
+    #
+    # DSL for the construction of a DELETE statement comprising multiple
+    # operations (e.g. deleting a column value, deleting an element from a
+    # list, etc.)
+    #
+    #
+    # @note This class should not be instantiated directly
+    # @see DataSet#delete
+    # @see
+    #   http://www.datastax.com/documentation/cql/3.0/webhelp/index.html#cql/cql_reference/delete_r.html
+    #   CQL documentation for DELETE
+    # @since 1.0.0
+    #
     class Deleter < Writer
-
+      #
+      # Delete the entire row or rows matched by the data set
+      #
+      # @return [void]
+      #
       def delete_row
         @delete_row = true
       end
 
+      #
+      # Delete specified columns
+      #
+      # @param columns [Symbol] column names to delete
+      # @return [void]
+      #
       def delete_columns(*columns)
         statements.concat(columns)
       end
 
+      #
+      # Remove elements from a list by position
+      #
+      # @param column [Symbol] name of list column
+      # @param positions [Integer] positions in list from which to delete
+      #   elements
+      # @return [void]
+      #
       def list_remove_at(column, *positions)
-        statements.concat(positions.map { |position| "#{column}[#{position}]" })
+        statements
+          .concat(positions.map { |position| "#{column}[#{position}]" })
       end
 
+      #
+      # Remote elements from a map by key
+      #
+      # @param column [Symbol] name of map column
+      # @param keys [Object] keys to delete from map
+      # @return [void]
+      #
       def map_remove(column, *keys)
         statements.concat(keys.length.times.map { "#{column}[?]" })
         bind_vars.concat(keys)
@@ -27,11 +64,11 @@ module Cequel
         if @delete_row
           statement.append("DELETE FROM #{table_name}")
         elsif statements.empty?
-          raise ArgumentError, "No targets given for deletion!"
+          fail ArgumentError, "No targets given for deletion!"
         else
-          statement.append("DELETE ").
-            append(statements.join(','), *bind_vars).
-            append(" FROM #{table_name}")
+          statement.append("DELETE ")
+            .append(statements.join(','), *bind_vars)
+            .append(" FROM #{table_name}")
         end
         statement.append(generate_upsert_options)
       end
@@ -39,9 +76,6 @@ module Cequel
       def empty?
         super && !@delete_row
       end
-
     end
-
   end
-
 end

data/lib/cequel/metal/incrementer.rb

@@ -1,9 +1,19 @@
 module Cequel
-
   module Metal
-
+    #
+    # Encapsulates a counter `UPDATE` operation comprising multiple increment
+    # or decrement operations
+    #
+    # @see DataSet#increment
+    # @since 1.0.0
+    #
     class Incrementer < Writer
-
+      #
+      # Increment one or more columns by given deltas
+      #
+      # @param data [Hash<Symbol,Integer>] map of column names to deltas
+      # @return [void]
+      #
       def increment(data)
         data.each_pair do |column_name, delta|
           operator = delta < 0 ? '-' : '+'
@@ -12,6 +22,12 @@ module Cequel
         end
       end
 
+      #
+      # Decrement one or more columns by given deltas
+      #
+      # @param data [Hash<Symbol,Integer>] map of column names to deltas
+      # @return [void]
+      #
       def decrement(data)
         increment(Hash[data.map { |column, count| [column, -count] }])
       end
@@ -19,17 +35,14 @@ module Cequel
       private
 
       def write_to_statement(statement)
-        statement.
-          append("UPDATE #{table_name}").
-          append(generate_upsert_options).
-          append(
+        statement
+          .append("UPDATE #{table_name}")
+          .append(generate_upsert_options)
+          .append(
             " SET " << statements.join(', '),
             *bind_vars
         )
       end
-
     end
-
   end
-
 end

data/lib/cequel/metal/inserter.rb

@@ -1,25 +1,41 @@
 module Cequel
-
   module Metal
-
+    #
+    # Encapsulates an `INSERT` statement
+    #
+    # @see DataSet#insert
+    # @since 1.0.0
+    #
     class Inserter < Writer
-
+      #
+      # (see Writer#initialize)
+      #
       def initialize(data_set, options = {})
         @row = {}
         super
       end
 
+      #
+      # (see Writer#execute)
+      #
       def execute
         statement = Statement.new
         write_to_statement(statement)
         data_set.write(*statement.args)
       end
 
+      #
+      # Insert the given data into the table
+      #
+      # @param data [Hash<Symbol,Object>] map of column names to values
+      # @return [void]
+      #
       def insert(data)
         @row.merge!(data.symbolize_keys)
       end
 
       private
+
       attr_reader :row
 
       def column_names
@@ -45,9 +61,6 @@ module Cequel
           *bind_vars)
         statement.append(generate_upsert_options)
       end
-
     end
-
   end
-
 end

data/lib/cequel/metal/keyspace.rb

@@ -1,113 +1,93 @@
 module Cequel
-
   module Metal
-
     #
-    # Handle to a Cassandra keyspace.
+    # Handle to a Cassandra keyspace (database). Keyspace objects are factories
+    # for DataSet instances and provide a handle to a Schema::Keyspace
+    # instance.
     #
     class Keyspace
+      extend Forwardable
+      include Logging
+
+      # @return [Hash] configuration options for this keyspace
       attr_reader :configuration
+      # @return [String] name of the keyspace
+      attr_reader :name
+
+      #
+      # @!method write(statement, *bind_vars)
+      #
+      # Write data to this keyspace using a CQL query. Will be included the
+      # current batch operation if one is present.
+      #
+      # @param (see #execute)
+      # @return [void]
+      #
+      def_delegator :write_target, :execute, :write
+
+      #
+      # @!method batch
+      #   (see Cequel::Metal::BatchManager#batch)
+      #
+      def_delegator :batch_manager, :batch
 
       #
       # @api private
+      # @param configuration [Options]
+      # @option (see #configure)
       # @see Cequel.connect
       #
       def initialize(configuration={})
         configure(configuration)
       end
 
-      def name
-        @keyspace
-      end
-
-      def connection=(connection)
-        @connection = connection
-      end
-
+      #
+      # Configure this keyspace from a hash of options
+      #
+      # @param configuration [Options] configuration options
+      # @option configuration [String] :host ('127.0.0.1:9160') host/port of
+      #   single Cassandra instance to connect to
+      # @option configuration [Array<String>] :hosts list of Cassandra
+      #   instances to connect to
+      # @option configuration [Hash] :thrift Thrift options to be passed
+      #   directly to Thrift client
+      # @option configuration [String] :keyspace name of keyspace to connect to
+      # @option configuration [Integer] :pool (1) size of connection pool
+      # @option configuration [Integer] :pool_timeout (0) timeout when
+      #   attempting to check out connection from pool
+      # @return [void]
+      #
       def configure(configuration = {})
         @configuration = configuration
-        @hosts = configuration.fetch(:host, configuration.fetch(:hosts, '127.0.0.1:9160'))
+        @hosts = configuration.fetch(
+          :host, configuration.fetch(:hosts, '127.0.0.1:9160'))
         @thrift_options = configuration[:thrift].try(:symbolize_keys) || {}
-        @keyspace = configuration[:keyspace]
+        @name = configuration[:keyspace]
         # reset the connections
         clear_active_connections!
       end
 
+      #
+      # @return [Schema::Keyspace] schema object providing full read/write
+      #   access to database schema
       def schema
         Schema::Keyspace.new(self)
       end
 
-      def logger=(logger)
-        @logger = logger
-      end
-
-      def logger
-        @logger
-      end
-
-      def slowlog=(slowlog)
-        @slowlog = slowlog
-      end
-
-      def slowlog
-        @slowlog
-      end
-
-      def slowlog_threshold=(slowlog_threshold)
-        @slowlog_threshold = slowlog_threshold
-      end
-
-      def slowlog_threshold
-        @slowlog_threshold
-      end
-
-      def connection_pool
-        return @connection_pool if defined? @connection_pool
-        if @configuration[:pool]
-          options = {
-            :size => @configuration[:pool] || 10,
-            :timeout => @configuration[:pool_timeout] || 5
-          }
-          @connection_pool = ConnectionPool.new(options) do
-            build_connection
-          end
-        else
-          @connection_pool = nil
-        end
-      end
-
-      def connection
-        @connection ||= build_connection
-      end
-
-      def clear_active_connections!
-        remove_instance_variable(:@connection) if defined? @connection
-        remove_instance_variable(:@connection_pool) if defined? @connection_pool
-      end
-
-      def with_connection(&block)
-        if connection_pool
-          connection_pool.with(&block)
-        else
-          yield connection
-        end
-      end
-
       #
-      # Get DataSet encapsulating a column family in this keyspace
+      # @param table_name [Symbol] the name of the table
+      # @return [DataSet] data set encapsulating table
       #
-      # @param column_family_name [Symbol] the name of the column family
-      # @return [DataSet] a column family
-      #
-      def [](column_family_name)
-        DataSet.new(column_family_name.to_sym, self)
+      def [](table_name)
+        DataSet.new(table_name.to_sym, self)
       end
 
       #
-      # Execute a CQL query in this keyspace.
+      # Execute a CQL query in this keyspace
       #
       # @param statement [String] CQL string
-      # @param *bind_vars [Object] values for bind variables
+      # @param bind_vars [Object] values for bind variables
+      # @return [void]
       #
       def execute(statement, *bind_vars)
         log('CQL', statement, *bind_vars) do
@@ -118,59 +98,27 @@ module Cequel
       end
 
       #
-      # Write data to this keyspace using a CQL query. Will be included the
-      # current batch operation if one is present.
+      # Clears all active connections
       #
-      # @param (see #execute)
+      # @return [void]
       #
-      def write(statement, *bind_vars)
-        if get_batch
-          get_batch.execute(statement, *bind_vars)
-        else
-          execute(statement, *bind_vars)
+      def clear_active_connections!
+        if defined? @connection_pool
+          remove_instance_variable(:@connection_pool)
         end
       end
 
-      #
-      # Execute write operations in a batch. Any inserts, updates, and deletes
-      # inside this method's block will be executed inside a CQL BATCH operation.
-      #
-      # @param options [Hash]
-      # @option options [Fixnum] :auto_apply Automatically send batch to Cassandra after this many statements
-      #
-      # @example Perform inserts in a batch
-      #   DB.batch do
-      #     DB[:posts].insert(:id => 1, :title => 'One')
-      #     DB[:posts].insert(:id => 2, :title => 'Two')
-      #   end
-      #
-      def batch(options = {})
-        new_batch = Batch.new(self, options)
-
-        if get_batch
-          if get_batch.unlogged? && new_batch.logged?
-            raise ArgumentError,
-              "Already in a logged batch; can't start an unlogged batch."
-          elsif get_batch.logged? && new_batch.unlogged?
-            raise ArgumentError,
-              "Already in an unlogged batch; can't start a logged batch."
-          end
-          return yield
-        end
+      private
 
-        begin
-          set_batch(new_batch)
-          yield.tap { new_batch.apply }
-        ensure
-          set_batch(nil)
-        end
-      end
+      def_delegator :connection_pool, :with, :with_connection
+      private :with_connection
 
-      private
+      def_delegator :batch_manager, :current_batch
+      private :current_batch
 
       def build_connection
-        options = {:cql_version => '3.0.0'}
-        options[:keyspace] = @keyspace if @keyspace
+        options = {cql_version: '3.0.0'}
+        options[:keyspace] = name if name
         CassandraCQL::Database.new(
           @hosts,
           options,
@@ -178,49 +126,24 @@ module Cequel
         )
       end
 
-      def get_batch
-        ::Thread.current[batch_key]
-      end
-
-      def set_batch(batch)
-        ::Thread.current[batch_key] = batch
+      def connection_pool
+        return @connection_pool if defined? @connection_pool
+        options = {
+          size: @configuration.fetch(:pool, 1),
+          timeout: @configuration.fetch(:pool_timeout, 0)
+        }
+        @connection_pool = ConnectionPool.new(options) do
+          build_connection
+        end
       end
 
-      def batch_key
-        :"cequel-batch-#{object_id}"
+      def batch_manager
+        @batch_manager ||= BatchManager.new(self)
       end
 
-      def log(label, statement, *bind_vars)
-        return yield unless logger || slowlog
-        response = nil
-        begin
-          time = Benchmark.ms { response = yield }
-        rescue Exception => e
-          generate_message = proc do
-            sprintf(
-              '%s (ERROR) %s', label,
-              CassandraCQL::Statement.sanitize(statement, bind_vars)
-            )
-          end
-          logger.debug(&generate_message) if self.logger
-          raise
-        end
-        generate_message = proc do
-          sprintf(
-            '%s (%dms) %s', label, time.to_i,
-            CassandraCQL::Statement.sanitize(statement, bind_vars)
-          )
-        end
-        logger.debug(&generate_message) if self.logger
-        threshold = self.slowlog_threshold || 2000
-        if slowlog && time >= threshold
-          slowlog.warn(&generate_message)
-        end
-        response
+      def write_target
+        current_batch || self
       end
-
     end
-
   end
-
 end