cassandra-driver 2.0.1 → 2.1.0

data/lib/cassandra/retry/policies/default.rb

@@ -1,7 +1,7 @@
 # encoding: utf-8
 
 #--
-# Copyright 2013-2014 DataStax, Inc.
+# Copyright 2013-2015 DataStax, Inc.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.

data/lib/cassandra/retry/policies/downgrading_consistency.rb

@@ -1,7 +1,7 @@
 # encoding: utf-8
 
 #--
-# Copyright 2013-2014 DataStax, Inc.
+# Copyright 2013-2015 DataStax, Inc.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.

data/lib/cassandra/retry/policies/fallthrough.rb

@@ -1,7 +1,7 @@
 # encoding: utf-8
 
 #--
-# Copyright 2013-2014 DataStax, Inc.
+# Copyright 2013-2015 DataStax, Inc.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.

data/lib/cassandra/session.rb

@@ -1,7 +1,7 @@
 # encoding: utf-8
 
 #--
-# Copyright 2013-2014 DataStax, Inc.
+# Copyright 2013-2015 DataStax, Inc.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -33,14 +33,13 @@ module Cassandra
       @futures = futures_factory
     end
 
-    # @!method execute_async(statement, options = nil)
     # Executes a given statement and returns a future result
     #
     # @param statement [String, Cassandra::Statements::Simple,
     #   Cassandra::Statements::Bound, Cassandra::Statements::Prepared]
     #   statement to execute
     #
-    # @param options [nil, Hash] a customizable set of options
+    # @param options [Hash] (nil) a customizable set of options
     #
     # @option options [Symbol] :consistency consistency level for the request.
     #   Must be one of {Cassandra::CONSISTENCIES}
@@ -56,53 +55,23 @@ module Cassandra
     # @option options [String] :paging_state (nil) this option is used for
     #   stateless paging, where result paging is resumed some time after the
     #   initial request.
-    # @option options [Array] :arguments (nil) positional arguments for the
-    #   statement.
-    #
-    # @overload execute_async(statement, *args, options = nil)
-    #   Executes a statement using the deprecated splat-style way of passing
-    #   positional arguments/
-    #
-    #   @deprecated This style will soon be removed, use the `:arguments`
-    #     option to provide positional arguments instead.
-    #
-    #   @param statement [String, Cassandra::Statements::Simple,
-    #     Cassandra::Statements::Bound, Cassandra::Statements::Prepared]
-    #     statement to execute
-    #
-    #   @param args [*Object] **this style of positional arguments is
-    #     deprecated, please use the `:arguments` options instead** -
-    #     positional arguments to paramterized query or prepared statement.
-    #
-    #   @param options [nil, Hash] a customizable set of options
-    #
-    #   @note Last argument will be treated as `options` if it is a {Hash}.
-    #     Therefore, make sure to pass empty `options` when executing a
-    #     statement with the last parameter required to be a map datatype.
+    # @option options [Array, Hash] :arguments (nil) positional or named
+    #   arguments for the statement.
     #
     # @see Cassandra.cluster Options that can be specified on the cluster-level
     #   and their default values.
     #
-    # @note Positional arguments for simple statements are only supported on
+    # @note Positional arguments for simple statements are only supported
     #   starting with Apache Cassandra 2.0 and above.
     #
+    # @note Named arguments for simple statements are only supported
+    #   starting with Apache Cassandra 2.1 and above.
+    #
     # @return [Cassandra::Future<Cassandra::Result>]
     #
     # @see Cassandra::Session#execute A list of errors this future can be
     #   resolved with
-    def execute_async(statement, *args)
-      options = nil
-      options = args.pop if args.last.is_a?(::Hash)
-
-      unless args.empty?
-        ::Kernel.warn "[WARNING] Splat style (*args) positional arguments " \
-                      "are deprecated, use the :arguments option instead, " \
-                      "called from #{caller.first}"
-
-        options ||= {}
-        options[:arguments] = args
-      end
-
+    def execute_async(statement, options = nil)
       if options
         options = @options.override(options)
       else
@@ -134,28 +103,7 @@ module Cassandra
     #   Cassandra::Statements::Bound, Cassandra::Statements::Prepared]
     #   statement to execute
     #
-    # @param options [nil, Hash] a customizable set of options
-    #
-    # @overload execute(statement, *args, options = nil)
-    #   Executes a statement using the deprecated splat-style way of passing
-    #   positional arguments/
-    #
-    #   @deprecated This style will soon be removed, use the `:arguments`
-    #     option to provide positional arguments instead.
-    #
-    #   @param statement [String, Cassandra::Statements::Simple,
-    #     Cassandra::Statements::Bound, Cassandra::Statements::Prepared]
-    #     statement to execute
-    #
-    #   @param args [*Object] **this style of positional arguments is
-    #     deprecated, please use the `:arguments` options instead** -
-    #     positional arguments to paramterized query or prepared statement.
-    #
-    #   @param options [nil, Hash] a customizable set of options
-    #
-    #   @note Last argument will be treated as `options` if it is a {Hash}.
-    #     Therefore, make sure to pass empty `options` when executing a
-    #     statement with the last parameter required to be a map datatype.
+    # @param options [Hash] (nil) a customizable set of options
     #
     # @see Cassandra::Session#execute_async
     # @see Cassandra::Future#get
@@ -166,24 +114,8 @@ module Cassandra
     # @raise [Cassandra::Errors::ValidationError] if Cassandra fails to validate
     # @raise [Cassandra::Errors::TimeoutError] if request has not completed
     #   within the `:timeout` given
-    def execute(statement, *args)
-      options = nil
-      options = args.pop if args.last.is_a?(::Hash)
-
-      unless args.empty?
-        ::Kernel.warn "[WARNING] Splat style (*args) positional arguments " \
-                      "are deprecated, use the :arguments option instead, " \
-                      "called from #{caller.first}"
-
-        options ||= {}
-        options[:arguments] = args
-      end
-
-      if options
-        execute_async(statement, options).get
-      else
-        execute_async(statement).get
-      end
+    def execute(statement, options = nil)
+      execute_async(statement, options).get
     end
 
     # Prepares a given statement and returns a future prepared statement
@@ -191,6 +123,8 @@ module Cassandra
     # @param statement [String, Cassandra::Statements::Simple] a statement to
     #   prepare
     #
+    # @param options [Hash] (nil) a customizable set of options
+    #
     # @option options [Boolean] :trace (false) whether to enable request tracing
     # @option options [Numeric] :timeout (nil) if specified, it is a number of
     #   seconds after which to time out the request if it hasn't completed

data/lib/cassandra/statement.rb

@@ -1,7 +1,7 @@
 # encoding: utf-8
 
 #--
-# Copyright 2013-2014 DataStax, Inc.
+# Copyright 2013-2015 DataStax, Inc.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.

data/lib/cassandra/statements.rb

@@ -1,7 +1,7 @@
 # encoding: utf-8
 
 #--
-# Copyright 2013-2014 DataStax, Inc.
+# Copyright 2013-2015 DataStax, Inc.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.

data/lib/cassandra/statements/batch.rb

@@ -1,7 +1,7 @@
 # encoding: utf-8
 
 #--
-# Copyright 2013-2014 DataStax, Inc.
+# Copyright 2013-2015 DataStax, Inc.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -55,39 +55,24 @@ module Cassandra
         @statements = []
       end
 
-      # @!method add(statement, args)
       # Adds a statement to this batch.
       #
       # @param statement [String, Cassandra::Statements::Simple,
       #   Cassandra::Statements::Prepared, Cassandra::Statements::Bound]
       #   statement to add.
-      # @param args [Array] positional arguments to bind, must contain
-      #   the same number of parameters as the number of positional (`?`)
-      #   markers in the original CQL passed to {Cassandra::Session#prepare}
+      # @param args [Array, Hash] (nil) positional or named arguments to bind,
+      #   must contain the same number of parameters as the number of positional
+      #   (`?`) or named (`:name`) markers in the CQL passed.
       #
-      # @overload add(statement, *args)
-      #   Adds a statement to this batch using the deprecated splat-style way of
-      #   passing positional arguments
+      # @note Positional arguments for simple statements are only supported
+      #   starting with Apache Cassandra 2.0 and above.
       #
-      #   @deprecated Please pass a single {Array} of positional arguments, the
-      #     `*args` style is deprecated.
-      #
-      #   @param statement [String, Cassandra::Statements::Simple,
-      #     Cassandra::Statements::Prepared, Cassandra::Statements::Bound]
-      #     statement to add.
-      #   @param args [*Object] **this style of positional arguments is
-      #     deprecated, please pass a single {Array} instead** - arguments to
-      #     paramterized query or prepared statement
+      # @note Named arguments for simple statements are only supported
+      #   starting with Apache Cassandra 2.1 and above.
       #
       # @return [self]
-      def add(statement, *args)
-        if args.one? && args.first.is_a?(::Array)
-          args = args.first
-        elsif !args.empty?
-          ::Kernel.warn "[WARNING] Splat style (*args) positional arguments " \
-                        "are deprecated, pass an Array instead - called " \
-                        "from #{caller.first}"
-        end
+      def add(statement, args = nil)
+        args ||= EMPTY_LIST
 
         case statement
         when String

data/lib/cassandra/statements/bound.rb

@@ -1,7 +1,7 @@
 # encoding: utf-8
 
 #--
-# Copyright 2013-2014 DataStax, Inc.
+# Copyright 2013-2015 DataStax, Inc.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.

data/lib/cassandra/statements/prepared.rb

@@ -1,7 +1,7 @@
 # encoding: utf-8
 
 #--
-# Copyright 2013-2014 DataStax, Inc.
+# Copyright 2013-2015 DataStax, Inc.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -18,6 +18,8 @@
 
 module Cassandra
   module Statements
+    # A prepared statement is created by calling {Cassandra::Session#prepare}
+    # or  {Cassandra::Session#prepare_async}.
     class Prepared
       include Statement
 
@@ -42,45 +44,36 @@ module Cassandra
         @schema          = schema
       end
 
-      # @!method bind(args)
       # Creates a statement bound with specific arguments
       #
-      # @param args [Array] positional arguments to bind, must contain the same
-      #   number of parameters as the number of positional (`?`) markers in the
-      #   original CQL passed to {Cassandra::Session#prepare}
-      #
-      # @note Positional arguments are only supported on Apache Cassandra 2.1
-      #   and above.
-      #
-      # @overload bind(*args)
-      #   Creates a statement bound with specific arguments using the
-      #   deprecated splat-style way of passing positional arguments.
-      #
-      #   @deprecated Please pass a single {Array} of positional arguments, the
-      #     `*args` style is deprecated.
-      #
-      #   @param args [*Object] **this style of positional arguments is
-      #     deprecated, please pass a single {Array} instead** - positional
-      #     arguments to bind, must contain the same number of parameters as
-      #     the number of positional argument markers (`?`) in the CQL passed
-      #     to {Cassandra::Session#prepare}.
+      # @param args [Array, Hash] (nil) positional or named arguments to bind,
+      #   must contain the same number of parameters as the number of positional
+      #   (`?`) or named (`:name`) markers in the original CQL passed to
+      #   {Cassandra::Session#prepare}
       #
       # @return [Cassandra::Statements::Bound] bound statement
-      def bind(*args)
-        if args.one? && args.first.is_a?(::Array)
-          args = args.first
+      def bind(args = nil)
+        if args
+          Util.assert_instance_of_one_of([::Array, ::Hash], args) { "args must be an Array or a Hash, #{args.inspect} given" }
         else
-          unless args.empty?
-            ::Kernel.warn "[WARNING] Splat style (*args) positional " \
-                          "arguments are deprecated, pass an Array instead " \
-                          "- called from #{caller.first}"
-          end
+          args = EMPTY_LIST
         end
 
-        Util.assert_equal(@params_metadata.size, args.size) { "expecting exactly #{@params_metadata.size} bind parameters, #{args.size} given" }
+        if args.is_a?(Hash)
+          args = @params_metadata.map do |(_, _, name, type)|
+            unless args.has_key?(name)
+              name = name.to_sym
+              raise ::ArgumentError, "argument :#{name} must be present in #{args.inspect}, but isn't" unless args.has_key?(name)
+            end
+
+            args[name]
+          end
+        else
+          Util.assert_equal(@params_metadata.size, args.size) { "expecting exactly #{@params_metadata.size} bind parameters, #{args.size} given" }
+        end
 
         params_types = @params_metadata.each_with_index.map do |(_, _, name, type), i|
-          Util.assert_type(type, args[i]) { "argument for #{name.inspect} must be #{type.inspect}, #{args[i]} given" }
+          Util.assert_type(type, args[i]) { "argument for #{name.inspect} must be #{type}, #{args[i]} given" }
           type
         end
 

data/lib/cassandra/statements/simple.rb

@@ -1,7 +1,7 @@
 # encoding: utf-8
 
 #--
-# Copyright 2013-2014 DataStax, Inc.
+# Copyright 2013-2015 DataStax, Inc.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -29,45 +29,39 @@ module Cassandra
       # @private
       attr_reader :params_types
 
-      # @!method initialize(cql, params)
+      # @private
+      attr_reader :params_names
+
       # @param cql [String] a cql statement
-      # @param params [Array] positional arguments for the query
+      # @param params [Array] (nil) positional arguments for the query
       #
-      # @note Positional arguments for simple statements are only supported on
+      # @note Positional arguments for simple statements are only supported
       #   starting with Apache Cassandra 2.0 and above.
       #
-      # @overload initialize(cql, *params)
-      #   Uses the deprecated splat-style way of passing positional arguments.
-      #
-      #   @deprecated Please pass a single {Array} of positional arguments, the
-      #     `*params` style is deprecated.
-      #
-      #   @param cql [String] a cql statement
-      #   @param params [*Object] **this style of positional arguments is
-      #     deprecated, please pass a single {Array} instead** - positional
-      #     arguments for the query
+      # @note Named arguments for simple statements are only supported
+      #   starting with Apache Cassandra 2.1 and above.
       #
       # @raise [ArgumentError] if cql statement given is not a String
-      def initialize(cql, *params)
-        unless cql.is_a?(::String)
-          raise ::ArgumentError, "cql must be a string, #{cql.inspect} given"
-        end
+      def initialize(cql, params = nil)
+        Util.assert_instance_of(::String, cql) { "cql must be a string, #{cql.inspect} given" }
 
-        if params.one? && params.first.is_a?(::Array)
-          params = params.first
-        else
-          unless params.empty?
-            ::Kernel.warn "[WARNING] Splat style (*params) positional " \
-                          "arguments are deprecated, pass an Array instead " \
-                          "- called from #{caller.first}"
+        params ||= EMPTY_LIST
+
+        if params.is_a?(::Hash)
+          params_names = []
+          params = params.each_with_object([]) do |(name, value), params|
+            params_names << name
+            params       << value
           end
+        else
+          Util.assert_instance_of(::Array, params) { "params must be an Array or a Hash, #{params.inspect} given" }
+          params_names = EMPTY_LIST
         end
 
-        params_types = params.map {|value| guess_type(value)}
-
         @cql          = cql
         @params       = params
-        @params_types = params_types
+        @params_types = params.map {|value| Util.guess_type(value)}
+        @params_names = params_names
       end
 
       # @return [String] a CLI-friendly simple statement representation
@@ -84,44 +78,6 @@ module Cassandra
       end
 
       alias :== :eql?
-
-      private
-
-      # @private
-      @@type_guesses = {
-        ::String     => :varchar,
-        ::Fixnum     => :bigint,
-        ::Float      => :double,
-        ::Bignum     => :varint,
-        ::BigDecimal => :decimal,
-        ::TrueClass  => :boolean,
-        ::FalseClass => :boolean,
-        ::NilClass   => :bigint,
-        Uuid         => :uuid,
-        TimeUuid     => :uuid,
-        ::IPAddr     => :inet,
-        ::Time       => :timestamp,
-        ::Hash       => :map,
-        ::Array      => :list,
-        ::Set        => :set,
-      }.freeze
-
-      def guess_type(value)
-        type = @@type_guesses[value.class]
-
-        raise ::ArgumentError, "Unable to guess the type of the argument: #{value.inspect}" unless type
-
-        if type == :map
-          pair = value.first
-          [type, guess_type(pair[0]), guess_type(pair[1])]
-        elsif type == :list
-          [type, guess_type(value.first)]
-        elsif type == :set
-          [type, guess_type(value.first)]
-        else
-          type
-        end
-      end
     end
   end
 end