cassandra-driver 0.1.0.alpha1 → 1.0.0.beta.1

data/lib/cassandra/retry/policies.rb

@@ -0,0 +1,21 @@
+# encoding: utf-8
+
+#--
+# Copyright 2013-2014 DataStax, Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#++
+
+require 'cassandra/retry/policies/default'
+require 'cassandra/retry/policies/downgrading_consistency'
+require 'cassandra/retry/policies/fallthrough'

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

@@ -0,0 +1,47 @@
+# encoding: utf-8
+
+#--
+# Copyright 2013-2014 DataStax, Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#++
+
+module Cassandra
+  module Retry
+    module Policies
+      class Default
+        include Policy
+
+        def read_timeout(statement, consistency, required, received, retrieved, retries)
+          return reraise if retries > 0
+
+          if received >= required && !retrieved
+            try_again(consistency)
+          else
+            reraise
+          end
+        end
+
+        def write_timeout(statement, consistency, type, required, received, retries)
+          return reraise if retries > 0
+
+          type == :batch_log ? try_again(consistency) : reraise
+        end
+
+        def unavailable(statement, consistency, required, alive, retries)
+          reraise
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,71 @@
+# encoding: utf-8
+
+#--
+# Copyright 2013-2014 DataStax, Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#++
+
+module Cassandra
+  module Retry
+    module Policies
+      class DowngradingConsistency
+        include Policy
+
+        def read_timeout(statement, consistency, required, received, retrieved, retries)
+          return reraise if retries > 0 || SERIAL_CONSISTENCIES.include?(consistency)
+          return max_likely_to_work(consistency, required, received) if received < required
+
+          retrieved ? reraise : try_again(consistency)
+        end
+
+        def write_timeout(statement, consistency, type, required, received, retries)
+          return reraise if retries > 0
+
+          case type
+          when :simple, :batch
+            ignore
+          when :unlogged_batch
+            max_likely_to_work(consistency, required, received)
+          when :batch_log
+            try_again(consistency)
+          else
+            reraise
+          end
+        end
+
+        def unavailable(statement, consistency, required, alive, retries)
+          return reraise if retries > 0
+
+          max_likely_to_work(consistency, required, alive)
+        end
+
+        private
+
+        def max_likely_to_work(consistency, required, received)
+          if consistency == :all && required > 1 && received >= (required.to_f / 2).floor + 1
+            try_again(:quorum)
+          elsif received >= 3
+            try_again(:three)
+          elsif received >= 2
+            try_again(:two)
+          elsif received >= 1
+            try_again(:one)
+          else
+            reraise
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,39 @@
+# encoding: utf-8
+
+#--
+# Copyright 2013-2014 DataStax, Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#++
+
+module Cassandra
+  module Retry
+    module Policies
+      class Fallthrough
+        include Policy
+
+        def read_timeout(statement, consistency, required, received, retrieved, retries)
+          reraise
+        end
+
+        def write_timeout(statement, consistency, type, required, received, retries)
+          reraise
+        end
+
+        def unavailable(statement, consistency, required, alive, retries)
+          reraise
+        end
+      end
+    end
+  end
+end

data/lib/cassandra/session.rb

@@ -0,0 +1,195 @@
+# encoding: utf-8
+
+#--
+# Copyright 2013-2014 DataStax, Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#++
+
+module Cassandra
+  # Sessions are used for query execution. Each session tracks its current keyspace. A session should be reused as much as possible, however it is ok to create several independent session for interacting with different keyspaces in the same application.
+  class Session
+    # @private
+    def initialize(client, default_options, futures_factory)
+      @client  = client
+      @options = default_options
+      @futures = futures_factory
+    end
+
+    # Executes a given statement and returns a future result
+    # @!method execute_async(statement, *args, options = {})
+    #
+    # @param statement [String, Cassandra::Statements::Simple,
+    #   Cassandra::Statements::Bound, Cassandra::Statements::Prepared]
+    #   statement to execute
+    # @param args [*Object] arguments to paramterized query or prepared
+    #   statement
+    #
+    # @option options [Symbol] :consistency consistency level for the request.
+    #   Must be one of {Cassandra::CONSISTENCIES}
+    # @option options [Integer] :page_size size of results page. You can page
+    #   through results using {Cassandra::Result#next_page} or
+    #   {Cassandra::Result#next_page_async}
+    # @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
+    # @option options [Symbol] :serial_consistency (nil) this option is only
+    #   relevant for conditional updates and specifies a serial consistency to
+    #   be used, one of {Cassandra::SERIAL_CONSISTENCIES}
+    #
+    # @see Cassandra.connect for description of options that can be specified
+    #   on the cluster-level as well as default values chosen.
+    #
+    # @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.
+    #
+    # @return [Cassandra::Future<Cassandra::Result>]
+    def execute_async(statement, *args)
+      if args.last.is_a?(::Hash)
+        options = @options.override(args.pop)
+      else
+        options = @options
+      end
+
+      case statement
+      when ::String
+        @client.query(Statements::Simple.new(statement, *args), options)
+      when Statements::Simple
+        @client.query(statement, options)
+      when Statements::Prepared
+        @client.execute(statement.bind(*args), options)
+      when Statements::Bound
+        @client.execute(statement, options)
+      when Statements::Batch
+        @client.batch(statement, options)
+      else
+        @futures.error(::ArgumentError.new("unsupported statement #{statement.inspect}"))
+      end
+    end
+
+    # A blocking wrapper around {Cassandra::Session#execute_async}
+    # @!method execute(statement, *args, options = {})
+    # @see Cassandra::Session#execute_async
+    # @see Cassandra::Future#get
+    #
+    # @return [Cassandra::Result] query result
+    # @raise [Cassandra::Errors::NoHostsAvailable] if none of the hosts can be reached
+    # @raise [Cassandra::Errors::QueryError] if Cassandra returns an error response
+    def execute(*args)
+      execute_async(*args).get
+    end
+
+    # Prepares a given statement and returns a future prepared statement
+    #
+    # @param statement [String, Cassandra::Statements::Simple] a statement to
+    #   prepare
+    #
+    # @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
+    #
+    # @return [Cassandra::Future<Cassandra::Statements::Prepared>] future
+    #   prepared statement
+    def prepare_async(statement, options = nil)
+      if options.is_a?(::Hash)
+        options = @options.override(options)
+      else
+        options = @options
+      end
+
+      case statement
+      when ::String
+        @client.prepare(statement, options)
+      when Statements::Simple
+        @client.prepare(statement.cql, options)
+      else
+        @futures.error(::ArgumentError.new("unsupported statement #{statement.inspect}"))
+      end
+    end
+
+    # A blocking wrapper around {Cassandra::Session#prepare_async}
+    # @see Cassandra::Session#prepare_async
+    # @see Cassandra::Future#get
+    #
+    # @return [Cassandra::Statements::Prepared] prepared statement
+    # @raise [Cassandra::Errors::NoHostsAvailable] if none of the hosts can be reached
+    # @raise [Cassandra::Errors::QueryError] if Cassandra returns an error response
+    def prepare(*args)
+      prepare_async(*args).get
+    end
+
+    # Returns a logged {Statements::Batch} instance and optionally yields it to
+    # a given block
+    # @yieldparam batch [Statements::Batch] a logged batch
+    # @return [Statements::Batch] a logged batch
+    def logged_batch(&block)
+      statement = Statements::Batch::Logged.new
+      yield(statement) if block_given?
+      statement
+    end
+    alias :batch :logged_batch
+
+    # Returns a unlogged {Statements::Batch} instance and optionally yields it
+    # to a given block
+    # @yieldparam batch [Statements::Batch] an unlogged batch
+    # @return [Statements::Batch] an unlogged batch
+    def unlogged_batch
+      statement = Statements::Batch::Unlogged.new
+      yield(statement) if block_given?
+      statement
+    end
+
+    # Returns a counter {Statements::Batch} instance and optionally yields it
+    # to a given block
+    # @yieldparam batch [Statements::Batch] a counter batch
+    # @return [Statements::Batch] a counter batch
+    def counter_batch
+      statement = Statements::Batch::Counter.new
+      yield(statement) if block_given?
+      statement
+    end
+
+    # Asynchronously closes current session
+    #
+    # @return [Cassandra::Future<Cassandra::Session>] a future that resolves to
+    #   self once closed
+    def close_async
+      promise = @futures.promise
+
+      @client.close.on_complete do |f|
+        if f.resolved?
+          promise.fulfill(self)
+        else
+          f.on_failure {|e| promise.break(e)}
+        end
+      end
+
+      promise.future
+    end
+
+    # Synchronously closes current session
+    #
+    # @return [self] this session
+    #
+    # @see Cassandra::Session#close_async
+    def close
+      close_async.get
+    end
+
+    # @return [String] a CLI-friendly session representation
+    def inspect
+      "#<#{self.class.name}:0x#{self.object_id.to_s(16)}>"
+    end
+  end
+end

data/lib/cassandra/statement.rb

@@ -0,0 +1,22 @@
+# encoding: utf-8
+
+#--
+# Copyright 2013-2014 DataStax, Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#++
+
+module Cassandra
+  module Statement
+  end
+end

data/lib/cassandra/statements.rb

@@ -0,0 +1,23 @@
+# encoding: utf-8
+
+#--
+# Copyright 2013-2014 DataStax, Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#++
+
+require 'cassandra/statements/batch'
+require 'cassandra/statements/bound'
+require 'cassandra/statements/prepared'
+require 'cassandra/statements/simple'
+require 'cassandra/statements/void'

data/lib/cassandra/statements/batch.rb

@@ -0,0 +1,95 @@
+# encoding: utf-8
+
+#--
+# Copyright 2013-2014 DataStax, Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#++
+
+module Cassandra
+  module Statements
+    # Batch statement groups several {Cassandra::Statement}. There are several types of Batch statements available:
+    # @see Cassandra::Session#batch
+    # @see Cassandra::Session#logged_batch
+    # @see Cassandra::Session#unlogged_batch
+    # @see Cassandra::Session#counter_batch
+    class Batch
+      # @private
+      class Logged < Batch
+        def type
+          :logged
+        end
+      end
+
+      # @private
+      class Unlogged < Batch
+        def type
+          :unlogged
+        end
+      end
+
+      # @private
+      class Counter < Batch
+        def type
+          :counter
+        end
+      end
+
+      include Statement
+
+      # @private
+      attr_reader :statements
+
+      # @private
+      def initialize
+        @statements = []
+      end
+
+      # Adds a statement to this batch
+      # @param statement [String, Cassandra::Statements::Simple,
+      #   Cassandra::Statements::Prepared, Cassandra::Statements::Bound] statement to add
+      # @param args [*Object] arguments to paramterized query or prepared
+      #   statement
+      # @return [self]
+      def add(statement, *args)
+        case statement
+        when String
+          @statements << Simple.new(statement, *args)
+        when Prepared
+          @statements << statement.bind(*args)
+        when Bound, Simple
+          @statements << statement
+        else
+          raise ::ArgumentError, "a batch can only consist of simple or prepared statements, #{statement.inspect} given"
+        end
+
+        self
+      end
+
+      # A batch statement doesn't really have any cql of its own as it is composed of multiple different statements
+      # @return [nil] nothing
+      def cql
+        nil
+      end
+
+      # @return [Symbol] one of `:logged`, `:unlogged` or `:counter`
+      def type
+      end
+
+      # @return [String] a CLI-friendly batch statement representation
+      def inspect
+        "#<#{self.class.name}:0x#{self.object_id.to_s(16)} @type=#{type.inspect}>"
+      end
+    end
+  end
+end