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

data/lib/cassandra/host.rb

@@ -0,0 +1,75 @@
+# 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
+  class Host
+    # @return [IPAddr] host ip
+    attr_reader :ip
+    # @note Host id can be `nil` before cluster connected.
+    # @return [Cassandra::Uuid, nil] host id.
+    attr_reader :id
+    # @note Host datacenter can be `nil` before cluster connected.
+    # @return [String, nil] host datacenter
+    attr_reader :datacenter
+    # @note Host rack can be `nil` before cluster connected.
+    # @return [String, nil] host rack
+    attr_reader :rack
+    # @note Host's cassandra version can be `nil` before cluster connected.
+    # @return [String, nil] version of cassandra that a host is running
+    attr_reader :release_version
+    # @return [Symbol] host status. Must be `:up` or `:down`
+    attr_reader :status
+
+    # @private
+    def initialize(ip, id = nil, rack = nil, datacenter = nil, release_version = nil, status = :up)
+      @ip              = ip
+      @id              = id
+      @rack            = rack
+      @datacenter      = datacenter
+      @release_version = release_version
+      @status          = status
+    end
+
+    # @return [Boolean] whether this host's status is `:up`
+    def up?
+      @status == :up
+    end
+
+    # @return [Boolean] whether this host's status is `:down`
+    def down?
+      @status == :down
+    end
+
+    # @private
+    def hash
+      @hash ||= @ip.hash
+    end
+
+    # @param other [Cassandra::Host] a host to compare
+    # @return [Boolean] whether this host has the same ip as the other
+    def eql?(other)
+      other.eql?(@ip)
+    end
+    alias :== :eql?
+
+    # @return [String] a CLI-friendly host representation
+    def inspect
+      "#<#{self.class.name}:0x#{self.object_id.to_s(16)} @ip=#{@ip}>"
+    end
+  end
+end

data/lib/cassandra/keyspace.rb

@@ -0,0 +1,120 @@
+# 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
+  # Represents a cassandra keyspace
+  # @see Cassandra::Cluster#each_keyspace
+  # @see Cassandra::Cluster#keyspace
+  class Keyspace
+    # @private
+    class Replication
+      attr_reader :klass, :options
+
+      def initialize(klass, options)
+        @klass   = klass
+        @options = options
+      end
+
+      def to_cql
+        replication = {'class' => @klass}
+        replication.merge!(@options)
+
+        Util.encode_hash(replication)
+      end
+
+      def eql?(other)
+        other.is_a?(Replication) &&
+          @klass == other.klass &&
+          @options == other.options
+      end
+      alias :== :eql?
+    end
+
+    # @return [String] this keyspace name
+    attr_reader :name
+    # @private
+    attr_reader :replication
+
+    # @private
+    def initialize(name, durable_writes, replication, tables)
+      @name           = name
+      @durable_writes = durable_writes
+      @replication    = replication
+      @tables         = tables
+    end
+
+    # @return [Boolean] whether durables writes are enabled for this keyspace
+    def durable_writes?
+      @durable_writes
+    end
+
+    # @return [Boolean] whether this keyspace has a table with the given name
+    # @param name [String] table name
+    def has_table?(name)
+      @tables.has_key?(name)
+    end
+
+    # @return [Cassandra::Table, nil] a table or nil
+    # @param name [String] table name
+    def table(name)
+      @tables[name]
+    end
+
+    # Yield or enumerate each table defined in this keyspace
+    # @overload each_table
+    #   @yieldparam table [Cassandra::Table] current table
+    #   @return [Array<Cassandra::Table>] a list of tables
+    # @overload each_table
+    #   @return [Enumerator<Cassandra::Table>] an enumerator
+    def each_table(&block)
+      @tables.values.each(&block)
+    end
+    alias :tables :each_table
+
+    # @return [String] a cql representation of this table
+    def to_cql
+      "CREATE KEYSPACE #{Util.escape_name(@name)} WITH REPLICATION = #{@replication.to_cql} AND DURABLE_WRITES = #{@durable_writes};"
+    end
+
+    # @return [Boolean] whether this keyspace is equal to the other
+    def eql?(other)
+      other.is_a?(Keyspace) &&
+        @name == other.name &&
+        @durable_writes == other.durable_writes &&
+        @replication == other.replication &&
+        @tables == other.raw_tables
+    end
+    alias :== :eql?
+
+    # @private
+    def update_table(table)
+      Keyspace.new(@name, @durable_writes, @replication, @tables.merge(table.name => table))
+    end
+
+    # @private
+    attr_reader :durable_writes
+    protected :durable_writes
+
+    protected
+
+    # @private
+    def raw_tables
+      @tables
+    end
+  end
+end

data/lib/cassandra/listener.rb

@@ -0,0 +1,87 @@
+# 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
+  # Cassandra state listener.
+  #
+  # @note Actual state listener implementations don't need to inherit from this
+  #   class as long as they conform to its interface. This class exists solely
+  #   for documentation purposes
+  #
+  # @see Cassandra::Cluster#register
+  class Listener
+    # This method is called whenever a host is considered to be up, whether
+    #   by Cassandra's gossip exchange or when the driver has successfully
+    #   established a connection to it.
+    #
+    # @param host [Cassandra::Host] a host instance
+    # @return [void]
+    def host_up(host)
+    end
+
+    # This method is called whenever a host is considered to be down, whether
+    #   by Cassandra's gossip exchange or when the driver failed to establish
+    #   any connections to it.
+    #
+    # @param host [Cassandra::Host] a host instance
+    # @return [void]
+    def host_down(host)
+    end
+
+    # This method is called whenever a host is discovered by the driver,
+    #   whether because it is a completely new node or if its
+    #   {Cassandra::Host#datacenter} or {Cassandra::Host#rack} have changed.
+    #
+    # @param host [Cassandra::Host] a host instance
+    # @return [void]
+    def host_found(host)
+    end
+
+    # This method is called whenever a host leaves the cluster, whether
+    #   because it is completely gone or if its {Cassandra::Host#datacenter} or
+    #   {Cassandra::Host#rack} have changed.
+    #
+    # @param host [Cassandra::Host] a host instance
+    # @return [void]
+    def host_lost(host)
+    end
+
+    # This method is called whenever a new keyspace is created.
+    #
+    # @param keyspace [Cassandra::Keyspace] a keyspace instance
+    # @return [void]
+    def keyspace_created(keyspace)
+    end
+
+    # This method is called whenever an existing keyspace is changed. This
+    # happens when a new table is created or an existing table is dropped or
+    # altered.
+    #
+    # @param keyspace [Cassandra::Keyspace] a keyspace instance
+    # @return [void]
+    def keyspace_changed(keyspace)
+    end
+
+    # This method is called whenever an existing keyspace is dropped.
+    #
+    # @param keyspace [Cassandra::Keyspace] a keyspace instance
+    # @return [void]
+    def keyspace_dropped(keyspace)
+    end
+  end
+end

data/lib/cassandra/load_balancing.rb

@@ -0,0 +1,112 @@
+# 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 LoadBalancing
+    # A list of possible load balancing distances that
+    # {Cassandra::LoadBalancing::Policy#distance} must return
+    DISTANCES = [:ignore, :local, :remote].freeze
+
+    # @note Actual load balancing policies don't need to extend this class,
+    #   only implement its methods. This class exists for documentation
+    #   purposes only
+    class Policy
+      # @abstract implementation should be provided by an actual policy
+      # @see Cassandra::Listener#host_up
+      def host_up(host)
+      end
+
+      # @abstract implementation should be provided by an actual policy
+      # @see Cassandra::Listener#host_down
+      def host_down(host)
+      end
+
+      # @abstract implementation should be provided by an actual policy
+      # @see Cassandra::Listener#host_found
+      def host_found(host)
+      end
+
+      # @abstract implementation should be provided by an actual policy
+      # @see Cassandra::Listener#host_lost
+      def host_lost(host)
+      end
+
+      # Returns a distance that lets the driver to determine host many
+      #   connections (if any) to open to the host
+      #
+      # @abstract implementation should be provided by an actual policy
+      # @param host [Cassandra::Host] a host instance
+      # @return [Symbol] distance to host. Must be one of
+      #   {Cassandra::LoadBalancing::DISTANCES}
+      def distance(host)
+        :ignore
+      end
+
+      # Load balancing plan is used to determine the order in which hosts
+      #   should be tried in case of a network failure.
+      #
+      # @note Hosts that should be ignored, must not be included in the Plan
+      #
+      # @abstract implementation should be provided by an actual policy
+      # @param keyspace [String] current keyspace of the {Cassandra::Session}
+      # @param statement [Cassandra::Statement] actual statement to be executed
+      # @param options [Cassandra::Execution::Options] execution options to be used
+      # @raise [NotImplementedError] override this method to return a plan
+      # @return [Cassandra::LoadBalancing::Plan] a load balancing plan
+      def plan(keyspace, statement, options)
+        raise ::NotImplementedError, "must be implemented by a child"
+      end
+
+      # @return [String] a console-friendly representation of this policy
+      def inspect
+        "#<#{self.class.name}:0x#{self.object_id.to_s(16)}>"
+      end
+    end
+
+    # A load balancing plan is used to determine the order of hosts for running
+    # queries, preparing statements and establishing connections.
+    # @note Plans returned by {Cassandra::LoadBalancing::Policy}
+    #   implementations don't need to extend this class, only implement its
+    #   methods. This class exists for documentation purposes only.
+    class Plan
+      # @return [Boolean] whether the plan contains any more hosts
+      def has_next?
+      end
+
+      # @return [Cql::Host] next host to try
+      def next
+      end
+    end
+
+    # @private
+    class EmptyPlan
+      def has_next?
+        false
+      end
+
+      def next
+        nil
+      end
+    end
+
+    # @private
+    EMPTY_PLAN = EmptyPlan.new
+  end
+end
+
+require 'cassandra/load_balancing/policies'

data/lib/cassandra/load_balancing/policies.rb

@@ -0,0 +1,18 @@
+# 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/load_balancing/policies/round_robin'
+require 'cassandra/load_balancing/policies/dc_aware_round_robin'
+require 'cassandra/load_balancing/policies/white_list'

data/lib/cassandra/load_balancing/policies/dc_aware_round_robin.rb

@@ -0,0 +1,149 @@
+# 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 LoadBalancing
+    module Policies
+      class DCAwareRoundRobin < Policy
+        # @private
+        class Plan
+          def initialize(local, remote, index)
+            @local  = local
+            @remote = remote
+            @index  = index
+
+            @local_remaining  = @local_total  = local.size
+            @remote_remaining = @remote_total = remote.size
+          end
+
+          def has_next?
+            @local_remaining > 0 || @remote_remaining > 0
+          end
+
+          def next
+            if @local_remaining > 0
+              @local_remaining -= 1
+              i = (@index % @local_total)
+              @index += 1
+
+              return @local[i]
+            end
+
+            if @remote_remaining > 0
+              @remote_remaining -= 1
+              i = (@index % @remote_total)
+              @index += 1
+
+              return @remote[i]
+            end
+          end
+        end
+
+        include MonitorMixin
+
+        def initialize(datacenter, max_remote_hosts_to_use = nil, use_remote_hosts_for_local_consistency = false)
+          datacenter              = String(datacenter)
+          max_remote_hosts_to_use = max_remote_hosts_to_use && Integer(max_remote_hosts_to_use)
+
+          raise ::ArgumentError, "datacenter cannot be nil" if datacenter.nil?
+          raise ::ArgumentError, "max_remote_hosts_to_use must be nil or >= 0" if max_remote_hosts_to_use && max_remote_hosts_to_use < 0
+
+          @datacenter = datacenter
+          @max_remote = max_remote_hosts_to_use
+          @local      = ::Array.new
+          @remote     = ::Array.new
+          @position   = 0
+
+          @use_remote = !!use_remote_hosts_for_local_consistency
+
+          mon_initialize
+        end
+
+        def host_up(host)
+          if host.datacenter.nil? || host.datacenter == @datacenter
+            synchronize { @local = @local.dup.push(host) }
+          else
+            if @max_remote.nil? || @remote.size < @max_remote
+              synchronize { @remote = @remote.dup.push(host) }
+            end
+          end
+
+          self
+        end
+
+        def host_down(host)
+          if host.datacenter.nil? || host.datacenter == @datacenter
+            synchronize do
+              @local = @local.dup
+              @local.delete(host)
+            end
+          else
+            synchronize do
+              @remote = @remote.dup
+              @remote.delete(host)
+            end
+          end
+
+          self
+        end
+
+        def host_found(host)
+          self
+        end
+
+        def host_lost(host)
+          self
+        end
+
+        def distance(host)
+          if host.datacenter.nil? || host.datacenter == @datacenter
+            @local.include?(host) ? :local : :ignore
+          else
+            @remote.include?(host) ? :remote : :ignore
+          end
+        end
+
+        def plan(keyspace, statement, options)
+          local = @local
+
+          if LOCAL_CONSISTENCIES.include?(options.consistency) && !@use_remote
+            remote = EMPTY_ARRAY
+          else
+            remote   = @remote
+          end
+
+          position = @position
+          total    = local.size + remote.size
+
+          return EMPTY_PLAN if total == 0
+
+          @position = (@position + 1) % total
+
+          Plan.new(local, remote, position)
+        end
+
+        private
+
+        # @private
+        LOCAL_CONSISTENCIES = [:local_quorum, :local_one].freeze
+        # @private
+        EMPTY_ARRAY         = [].freeze
+      end
+    end
+  end
+end