cassandra-driver 1.0.0.beta.3 → 1.0.0.rc.1

data/lib/cassandra/protocol/responses/event_response.rb

@@ -22,7 +22,7 @@ module Cassandra
       def self.decode(protocol_version, buffer, length, trace_id=nil)
         type = buffer.read_string
         impl = EVENT_TYPES[type]
-        raise UnsupportedEventTypeError, %(Unsupported event type: "#{type}") unless impl
+        raise Errors::DecodingError, %(Unsupported event type: "#{type}") unless impl
         new_length = length - 4 - type.bytesize
         impl.decode(protocol_version, buffer, new_length, trace_id)
       end

data/lib/cassandra/protocol/responses/raw_rows_result_response.rb

@@ -31,7 +31,7 @@ module Cassandra
       end
 
       def rows
-        raise UnmaterializedRowsError, 'Not materialized!' unless @rows
+        raise Errors::DecodingError, 'Not materialized!' unless @rows
         @rows
       end
 

data/lib/cassandra/protocol/responses/result_response.rb

@@ -28,7 +28,7 @@ module Cassandra
       def self.decode(protocol_version, buffer, length, trace_id=nil)
         kind = buffer.read_int
         impl = RESULT_TYPES[kind]
-        raise UnsupportedResultKindError, %(Unsupported result kind: #{kind}) unless impl
+        raise Errors::DecodingError, %(Unsupported result kind: #{kind}) unless impl
         impl.decode(protocol_version, buffer, length - 4, trace_id)
       end
 

data/lib/cassandra/protocol/responses/rows_result_response.rb

@@ -87,7 +87,7 @@ module Cassandra
             sub_type = read_column_type(buffer)
             [:set, sub_type]
           else
-            raise UnsupportedColumnTypeError, %(Unsupported column type: #{id})
+            raise Errors::DecodingError, %(Unsupported column type: #{id})
           end
         end
         type

data/lib/cassandra/protocol/type_converter.rb

@@ -46,7 +46,7 @@ module Cassandra
         case type
         when Array
           unless value.nil? || value.is_a?(Enumerable)
-            raise InvalidValueError, 'Value for collection must be enumerable'
+            raise EncodingError, 'Value for collection must be enumerable'
           end
           case type.first
           when :list, :set
@@ -75,12 +75,12 @@ module Cassandra
               nil_to_bytes(buffer, size_bytes)
             end
           else
-            raise UnsupportedColumnTypeError, %(Unsupported column collection type: #{type.first})
+            raise EncodingError, %(Unsupported column collection type: #{type.first})
           end
         else
           converter = @to_bytes_converters[type]
           unless converter
-            raise UnsupportedColumnTypeError, %(Unsupported column type: #{type})
+            raise EncodingError, %(Unsupported column type: #{type})
           end
           converter.call(buffer, value, size_bytes)
         end
@@ -140,6 +140,7 @@ module Cassandra
           size = buffer.read_signed_int
           return nil if size & 0x80000000 == 0x80000000
         end
+        return nil if size.zero?
         size
       end
 

data/lib/cassandra/reconnection.rb

@@ -30,7 +30,7 @@ module Cassandra
 
     # A reconnection policy
     # @abstract Actual reconnection policies supplied as `:reconnection_policy`
-    #   option to {Cassandra.connect} don't need to inherit this class, only
+    #   option to {Cassandra.cluster} don't need to inherit this class, only
     #   implement its methods. This class exists for documentation purposes
     #   only.
     class Policy

data/lib/cassandra/retry.rb

@@ -19,7 +19,7 @@
 module Cassandra
   module Retry
     # @abstract Actual retry policies supplied as `:retry_policy` option to
-    #   {Cassandra.connect} don't need to inherit this class, only implement
+    #   {Cassandra.cluster} don't need to inherit this class, only implement
     #   its methods. This class exists for documentation purposes only.
     module Policy
       # Decides wether to retry a read and at what consistency level.
@@ -51,8 +51,7 @@ module Cassandra
       # @param statement [Cassandra::Statement] the original statement that timed out
       # @param consistency [Symbol] the original consistency level for the
       #   request, one of {Cassandra::CONSISTENCIES}
-      # @param type [Symbol] One of `:simple`, `:batch`, `:unlogged_batch`,
-      #   `:counter` or `:batch_log`
+      # @param type [Symbol] One of {Cassandra::WRITE_TYPES}
       # @param required [Integer] the number of acks required to achieve
       #   requested consistency level
       # @param received [Integer] the number of acks received by the time the
@@ -75,8 +74,7 @@ module Cassandra
       #   request, one of {Cassandra::CONSISTENCIES}
       # @param required [Integer] the number of replicas required to achieve
       #   requested consistency level
-      # @param alive [Integer] the number of replicas received by the time the
-      #   query timed out
+      # @param alive [Integer] the number of replicas available for the request
       # @param retries [Integer] the number of retries already performed
       # 
       # @return [Cassandra::Policies::Retry::Decision] a retry decision

data/lib/cassandra/session.rb

@@ -54,14 +54,17 @@ module Cassandra
     #   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.
+    # @see Cassandra.cluster Options that can be specified on the cluster-level
+    #   and their default values.
     #
     # @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>]
+    #
+    # @see Cassandra::Session#execute A list of errors this future can be
+    #   resolved with
     def execute_async(statement, *args)
       if args.last.is_a?(::Hash)
         options = @options.override(args.pop)
@@ -91,8 +94,11 @@ module Cassandra
     # @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
+    # @raise [Cassandra::Errors::NoHostsAvailable] if all hosts fail
+    # @raise [Cassandra::Errors::ExecutionError] if Cassandra fails to execute
+    # @raise [Cassandra::Errors::ValidationError] if Cassandra fails to validate
+    # @raise [Cassandra::Errors::TimeoutError] if request has not completed
+    #   within the `:timeout` given
     def execute(*args)
       execute_async(*args).get
     end
@@ -131,7 +137,7 @@ module Cassandra
     #
     # @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
+    # @raise [Cassandra::Errors::ExecutionError] if Cassandra returns an error response
     def prepare(*args)
       prepare_async(*args).get
     end

data/lib/cassandra/table.rb

@@ -247,7 +247,7 @@ module Cassandra
     # @private
     def create_partition_key(values)
       partition_key = @partition_key
-      return nil unless partition_key.size == values.size
+      return nil if partition_key.size > values.size
 
       if partition_key.one?
         column      = partition_key.first

data/lib/cassandra/time_uuid.rb

@@ -19,6 +19,7 @@
 module Cassandra
   # A variant of UUID which can extract its time component.
   #
+  # You can use {Cassandra::Uuid::Generator} to generate {Cassandra::TimeUuid}s
   class TimeUuid < Uuid
     include Comparable
 
@@ -29,18 +30,37 @@ module Cassandra
       t = time_bits - GREGORIAN_OFFSET
       seconds = t/10_000_000
       microseconds = (t - seconds * 10_000_000)/10.0
+
       Time.at(seconds, microseconds).utc
     end
 
+    # Returns the date component from this UUID as Date.
+    #
+    # This just sugar around {#to_time}
+    #
+    # @return [Date]
+    def to_date
+      to_time.to_date
+    end
+
+    # Compares this timeuuid with another timeuuid
+    #
+    # @param other [Cassandra::TimeUuid] another timeuuid to compare
+    # @see Comparable
+    #
+    # @return [nil] when other is not a {Cassandra::Uuid}
+    # @return [Integer] `-1` when less than `other`, `0` when equal to `other`
+    #   and `1` when greater than `other`
     def <=>(other)
       return nil unless other.kind_of?(Cassandra::Uuid)
       c = self.value <=> other.value
-      return c if c == 0
+      return c if c == 0 || !other.is_a?(Cassandra::TimeUuid)
       self.time_bits <=> other.time_bits
     end
 
     protected
 
+    # @private
     def time_bits
       n = (value >> 64)
       t = 0
@@ -54,88 +74,6 @@ module Cassandra
 
     # @private
     LOWER_HALF_MASK = 0xffffffff_ffffffff
-
-    public
-
-    # A UUID version 1, variant 1 generator. It can generate a sequence of UUIDs
-    # with reasonable uniqueness guarantees:
-    #
-    # * The clock ID and node ID components are set to random numbers when the
-    #   generator is created.
-    # * If two calls to {#next} happen within the time afforded by the system
-    #   clock resolution a counter is incremented and added to the time
-    #   component.
-    # * If the clock moves backwards the clock ID is reset to a new random
-    #   number.
-    #
-    # Instances of this class are absolutely not threadsafe. You should
-    # never share instances between threads.
-    #
-    class Generator
-      # Create a new UUID generator.
-      #
-      # @param [Integer] node_id an alternate node ID (defaults to a random number)
-      # @param [Integer] clock_id an alternate clock ID (defaults to a random number)
-      #
-      def initialize(node_id=nil, clock_id=nil, clock=Time)
-        @node_id = node_id || (rand(2**47) | 0x010000000000)
-        @clock_id = clock_id || rand(2**16)
-        @clock = clock
-      end
-
-      # Returns a new UUID with a time component that is the current time.
-      #
-      # @return [Cassandra::TimeUuid] a new UUID
-      #
-      def next
-        now = @clock.now
-        usecs = now.to_i * 1_000_000 + now.usec
-        if @last_usecs && @last_usecs - @sequence <= usecs && usecs <= @last_usecs
-          @sequence += 1
-        elsif @last_usecs && @last_usecs > usecs
-          @sequence = 0
-          @clock_id = rand(2**16)
-        else
-          @sequence = 0
-        end
-        @last_usecs = usecs + @sequence
-        from_usecs(@last_usecs)
-      end
-
-      # Returns a new UUID with a time component based on the specified Time.
-      # A piece of jitter is added to ensure that multiple calls with the same
-      # time do not generate the same UUID (if you want determinism you can set
-      # the second parameter to zero).
-      #
-      # @param [Time] time the time to encode into the UUID
-      # @param [Integer] jitter a number of microseconds to add to the time to make it unique
-      # @return [Cassandra::TimeUuid] a new UUID
-      #
-      def from_time(time, jitter=rand(2**16))
-        usecs = time.to_i * 1_000_000 + time.usec + jitter
-        from_usecs(usecs)
-      end
-
-      # @private
-      def from_usecs(usecs)
-        t = GREGORIAN_OFFSET + usecs * 10
-        time_hi  = t & 0x0fff000000000000
-        time_mid = t & 0x0000ffff00000000
-        time_low = t & 0x00000000ffffffff
-        version = 1
-        clock_id = @clock_id & 0x3fff
-        node_id = @node_id & 0xffffffffffff
-        variant = 0x8000
-        n = (time_low << 96) | (time_mid << 48) | (time_hi << 16)
-        n |= version << 76
-        n |= (clock_id | variant) << 48
-        n |= node_id
-        TimeUuid.new(n)
-      end
-    end
-
-    private
-
     # @private
     GREGORIAN_OFFSET = 122192928000000000
   end

data/lib/cassandra/util.rb

@@ -103,7 +103,7 @@ module Cassandra
       when false     then io.print(FALSE_STR)
       when true      then io.print(TRUE_STR)
       else
-        raise "unsupported type: #{object.inspect}"
+        raise ::ArgumentError, "unsupported type: #{object.inspect}"
       end
 
       io.string

data/lib/cassandra/uuid.rb

@@ -22,7 +22,7 @@ module Cassandra
   # This is a very basic implementation of UUIDs and exists more or less just
   # to encode and decode UUIDs from and to Cassandra.
   #
-  # If you want to generate UUIDs see {Cassandra::TimeUuid::Generator}.
+  # If you want to generate UUIDs see {Cassandra::Uuid::Generator}.
   #
   class Uuid
     # Creates a new UUID either from a string (expected to be on the standard 8-4-4-4-12 form, or just 32 characters without hyphens), or from a 128 bit number.
@@ -88,17 +88,19 @@ module Cassandra
       # @private
       def from_s(str)
         str = str.gsub(HYPHEN, EMPTY_STRING)
-        raise ArgumentError, "Expected 32 hexadecimal digits but got #{str.length}" unless str.length == 32
-        raise ArgumentError, "invalid value for Integer(): \"#{str}\"" unless str =~ HEX_RE
+        raise ::ArgumentError, "Expected 32 hexadecimal digits but got #{str.length}" unless str.length == 32
+        raise ::ArgumentError, "invalid value for Integer(): \"#{str}\"" unless str =~ HEX_RE
         Integer(str, 16)
       end
     else
       # @private
       def from_s(str)
         str = str.gsub(HYPHEN, EMPTY_STRING)
-        raise ArgumentError, "Expected 32 hexadecimal digits but got #{str.length}" unless str.length == 32
+        raise ::ArgumentError, "Expected 32 hexadecimal digits but got #{str.length}" unless str.length == 32
         Integer(str, 16)
       end
     end
   end
 end
+
+require 'cassandra/uuid/generator'

data/lib/cassandra/uuid/generator.rb

@@ -0,0 +1,207 @@
+# 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 Uuid
+    # A UUID generator.
+    #
+    # This class can be used to genereate Apache Cassandra timeuuid and uuid
+    # values.
+    #
+    # @see Cassandra::Uuid::Generator#now Generating a sequence time UUIDs
+    #   with reasonable uniqueness guarantees.
+    # @see Cassandra::Uuid::Generator#at Generating a time UUID for a given
+    #   time object or unix timestamp.
+    # @see Cassandra::Uuid::Generator#uuid Generating completely random v4
+    #   UUIDs.
+    #
+    # @note Instances of this class are absolutely not threadsafe. You should
+    #   never share instances between threads.
+    #
+    class Generator
+      # Create a new UUID generator.
+      #
+      # The clock ID and node ID components are set to random numbers when the
+      # generator is created. These are used for generation of time UUIDs only.
+      #
+      # @param [Integer] node_id an alternate node ID
+      # @param [Integer] clock_id an alternate clock ID
+      # @param [Object<#now>] clock used to generate timeuuid from current time
+      #
+      # @raise [ArgumentError] if clock doesn't respond to `now`
+      def initialize(node_id = (SecureRandom.random_number(2**47) | 0x010000000000), clock_id = SecureRandom.random_number(65536), clock = Time)
+        raise ::ArgumentError, "invalid clock" unless clock.respond_to?(:now)
+
+        @node_id  = Integer(node_id)
+        @clock_id = Integer(clock_id)
+        @clock    = clock
+      end
+
+      # Returns a new UUID with a time component that is the current time.
+      #
+      # If two calls to {#now} happen within the time afforded by the system
+      # clock resolution a counter is incremented and added to the time
+      # component.
+      #
+      # If the clock moves backwards the clock ID is reset to a new random
+      # number.
+      #
+      # @example Creating a sequential TimeUuids for the current time
+      #   generator = Cassandra::Uuid::Generator.new
+      #   timeuuids = 5.times.map { generator.now }
+      #
+      #   puts timeuuids.zip(timeuuids.map(&:to_time)).map(&:inspect)
+      #
+      #   # Outputs:
+      #   # [8614b7d0-5646-11e4-8e54-6761d3995ef3, 2014-10-17 21:42:42 UTC]
+      #   # [8614b91a-5646-11e4-8e54-6761d3995ef3, 2014-10-17 21:42:42 UTC]
+      #   # [8614b960-5646-11e4-8e54-6761d3995ef3, 2014-10-17 21:42:42 UTC]
+      #   # [8614b99c-5646-11e4-8e54-6761d3995ef3, 2014-10-17 21:42:42 UTC]
+      #   # [8614b9ce-5646-11e4-8e54-6761d3995ef3, 2014-10-17 21:42:42 UTC]
+      #
+      # @see Time.now
+      #
+      # @return [Cassandra::TimeUuid] a new UUID
+      def now
+        now   = @clock.now
+        usecs = now.to_i * 1_000_000 + now.usec
+        if @last_usecs && @last_usecs - @sequence <= usecs && usecs <= @last_usecs
+          @sequence += 1
+        elsif @last_usecs && @last_usecs > usecs
+          @sequence = 0
+          @clock_id = SecureRandom.random_number(65536)
+        else
+          @sequence = 0
+        end
+        @last_usecs = usecs + @sequence
+        from_usecs(@last_usecs)
+      end
+
+      # Returns a new UUID with a time component based on the specified Time.
+      # A piece of jitter is added to ensure that multiple calls with the same
+      # time do not generate the same UUID (if you want determinism you can set
+      # the second parameter to zero).
+      #
+      # @overload at(time, jitter = SecureRandom.random_number(65536))
+      #   @param [Time] time a Time instance
+      #   @param [Integer] jitter a number of microseconds to add to the time
+      #   @return [Cassandra::TimeUuid] a new UUID
+      # @overload at(seconds_with_frac, jitter = SecureRandom.random_number(65536))
+      #   @param [Numeric] seconds_with_frac can be {Integer}, {Float},
+      #     {Rational}, or other {Numeric}
+      #   @param [Integer] jitter a number of microseconds to add to the time
+      #   @return [Cassandra::TimeUuid] a new UUID
+      # @overload at(seconds, microseconds_with_frac, jitter = SecureRandom.random_number(65536))
+      #   @param [Integer] seconds
+      #   @param [Numeric] microseconds_with_frac can be {Integer}, {Float},
+      #     {Rational}, or other {Numeric}
+      #   @param [Integer] jitter a number of microseconds to add to the time
+      #   @return [Cassandra::TimeUuid] a new UUID
+      #
+      # @note the `jitter` argument accepted by all variants of this method is
+      #   required to add randomness to generated {Cassandra::TimeUuid} and
+      #   might affect the order of generated timestamps. You should set
+      #   `jitter` to 0 when the source time(stamp)s are unique.
+      #
+      # @example Creating a TimeUuid from a Time instance
+      #   generator = Cassandra::Uuid::Generator.new
+      #   timeuuid  = generator.at(Time.at(1413582460))
+      #
+      #   puts timeuuid.to_time
+      #
+      #   # Outputs:
+      #   # 2014-10-17 21:47:40 UTC
+      #
+      # @example Creating a TimeUuid from a timestamp
+      #   generator = Cassandra::Uuid::Generator.new
+      #   timeuuid  = generator.at(1413582423)
+      #
+      #   puts timeuuid.to_time
+      #
+      #   # Outputs:
+      #   # 2014-10-17 21:47:03 UTC
+      #
+      # @example Avoid jitter in generated TimeUuid
+      #   timestamp = 1413582418
+      #   generator = Cassandra::Uuid::Generator.new
+      #   timeuuid  = generator.at(timestamp, 0)
+      #
+      #   puts timeuuid.to_time.to_i
+      #
+      #   # Outputs:
+      #   # 1413582418
+      #
+      # @raise [ArgumentError] when given no arguments or more than 3 arguments
+      #
+      # @see Time.at
+      def at(*args)
+        raise ::ArgumentError, "not enough arguments" if args.empty?
+        raise ::ArgumentError, "too many arguments"   if args.size > 3
+
+        if args.first.is_a?(Time)
+          time   = args.shift
+          jitter = args.empty? ? SecureRandom.random_number(65536) : Integer(args.shift)
+        else
+          jitter = args.size > 2 ? Integer(args.pop) : SecureRandom.random_number(65536)
+          time   = Time.at(*args)
+        end
+
+        from_usecs(time.to_i * 1_000_000 + time.usec + jitter)
+      end
+
+      # Returns a completely random version 4 UUID.
+      #
+      # @example Generating a random Uuid
+      #   generator = Cassandra::Uuid::Generator.new
+      #   uuid      = generator.uuid
+      #
+      #   puts uuid
+      #
+      #   # Outputs:
+      #   # 664dedae-e162-4bc0-9066-b9f1968252aa
+      #
+      # @see SecureRandom.uuid
+      #
+      # @return [Cassandra::Uuid] a new UUID
+      def uuid
+        Uuid.new(SecureRandom.uuid)
+      end
+
+      private
+
+      # @private
+      def from_usecs(usecs)
+        t = TimeUuid::GREGORIAN_OFFSET + usecs * 10
+        time_hi  = t & 0x0fff000000000000
+        time_mid = t & 0x0000ffff00000000
+        time_low = t & 0x00000000ffffffff
+        version  = 1
+        clock_id = @clock_id & 0x3fff
+        node_id  = @node_id & 0xffffffffffff
+        variant  = 0x8000
+
+        n  = (time_low << 96) | (time_mid << 48) | (time_hi << 16)
+        n |= version << 76
+        n |= (clock_id | variant) << 48
+        n |= node_id
+
+        TimeUuid.new(n)
+      end
+    end
+  end
+end