riak-client 1.4.5 → 2.0.0.rc1

data/lib/riak/crdt/counter.rb

@@ -0,0 +1,71 @@
+module Riak
+  module Crdt
+
+    # A distributed counter that supports incrementing and decrementing. This
+    # `Counter` uses the Riak 2 Data Types feature. If you're interested in
+    # Riak 1.4 Counters, see {Riak::Counter}.
+    class Counter < Base
+
+      # Create a counter instance. If not provided, the default bucket type
+      # from {Riak::Crdt} will be used.
+      #
+      # @param [Bucket] bucket the {Riak::Bucket} for this counter
+      # @param [String, nil] key The name of the counter. A nil key makes
+      #        Riak assign a key.
+      # @param [String] bucket_type The optional bucket type for this counter.
+      #        The default is in `Crdt::Base::DEFAULT_BUCKET_TYPES[:counter]`.
+      # @param [Hash] options
+      def initialize(bucket, key, bucket_type=nil, options={})
+        super(bucket, key, bucket_type || DEFAULT_BUCKET_TYPES[:counter], options)
+      end
+      
+      # The current value of the counter; hits the server if the value has
+      # not been fetched or if the counter has been incremented.
+      def value
+        reload if dirty?
+        return @value
+      end
+
+      # Increment the counter.
+      #
+      # @param [Integer] amount
+      # @param [Hash] options
+      def increment(amount=1, options={})
+        operate operation(amount), options
+      end
+
+      # Yields a {BatchCounter} to turn multiple increments into a single
+      # Riak hit.
+      #
+      # @yieldparam [BatchCounter] batch_counter collects multiple increments
+      def batch
+        batcher = BatchCounter.new
+
+        yield batcher
+        
+        increment batcher.accumulator
+      end
+      
+      alias :to_i :value
+
+      # Decrement the counter.
+      #
+      # @param [Integer] amount
+      def decrement(amount=1)
+        increment -amount
+      end
+      
+      private
+      def vivify(value)
+        @value = value
+      end
+
+      def operation(amount)
+        Operation::Update.new.tap do |op|
+          op.type = :counter
+          op.value = amount
+        end
+      end
+    end
+  end
+end

data/lib/riak/crdt/inner_counter.rb

@@ -0,0 +1,74 @@
+module Riak
+  module Crdt
+    # The {InnerCounter} lives inside a {Map}, or an {InnerMap} inside of a 
+    # {Map}, and is accessed through a {TypedCollection}.
+    #
+    # Much like the {Riak::Crdt::Counter}, it provides an integer value that can
+    # be incremented and decremented.
+    class InnerCounter
+      # The name of this counter inside a map.
+      #
+      # @api private
+      attr_accessor :name
+
+      # The value of this counter.
+      #
+      # @return [Integer] counter value
+      attr_reader :value
+      alias :to_i :value
+
+      # The parent of this counter.
+      #
+      # @api private
+      attr_reader :parent
+        
+      # @api private
+      def initialize(parent, value=0)
+        @parent = parent
+        @value = value
+      end
+
+      # Increment the counter.
+      #
+      # @param [Integer] amount How much to increment the counter by.
+      def increment(amount = 1)
+        @parent.increment name, amount
+      end
+
+      # Decrement the counter. Opposite of increment.
+      #
+      # @param [Integer] amount How much to decrement from the counter.
+      def decrement(amount = 1)
+        increment -amount
+      end
+
+      # Perform multiple increments against this counter, and collapse
+      # them into a single operation.
+      #
+      # @yieldparam [BatchCounter] batch_counter actually collects the
+      #                            operations.
+      def batch
+        batcher = BatchCounter.new
+
+        yield batcher
+
+        increment batcher.accumulator
+      end
+      
+      # @api private
+      def self.update(increment)
+        Operation::Update.new.tap do |op|
+          op.value = increment
+          op.type = :counter
+        end
+      end
+
+      # @api private
+      def self.delete
+        Operation::Delete.new.tap do |op|
+          op.type = :counter
+        end
+      end
+    end
+  end
+end

data/lib/riak/crdt/inner_flag.rb

@@ -0,0 +1,42 @@
+module Riak
+  module Crdt
+    # The {InnerFlag} is a boolean member of a {Map}. Since flag operations are
+    # extremely simple, this object simply provides internal API methods for
+    # {TypedCollection} to use.
+    #
+    # @api private
+    class InnerFlag
+      def self.new(parent, value)
+        ensure_boolean value
+        
+        return value
+      end
+
+      def self.update(value)
+        ensure_boolean value
+        
+        Operation::Update.new.tap do |op|
+          op.value = value
+          op.type = :flag
+        end
+      end
+
+      def self.delete
+        Operation::Delete.new.tap do |op|
+          op.type = :flag
+        end
+      end
+
+      private
+      def self.ensure_boolean(value)
+        return if value.is_a? TrueClass
+        return if value.is_a? FalseClass
+
+        raise FlagError, t('crdt.flag.not_boolean')
+      end
+
+      class FlagError < ArgumentError
+      end
+    end
+  end
+end

data/lib/riak/crdt/inner_map.rb

@@ -0,0 +1,53 @@
+module Riak
+  module Crdt
+    # A map that exists inside a {TypedCollection} inside another map.
+    class InnerMap
+      attr_reader :counters, :flags, :maps, :registers, :sets
+
+      attr_accessor :name
+
+      # The parent of this counter.
+      #
+      # @api private
+      attr_reader :parent
+
+      # @api private
+      def initialize(parent, value={})
+        @parent = parent
+        @value = value.symbolize_keys
+
+        initialize_collections
+      end
+
+      # @api private
+      def operate(inner_operation)
+        wrapped_operation = Operation::Update.new.tap do |op|
+          op.value = inner_operation
+          op.type = :map
+        end
+
+        @parent.operate(name, wrapped_operation)
+      end
+
+      # @api private
+      def self.delete
+        Operation::Delete.new.tap do |op|
+          op.type = :map
+        end
+      end
+
+      def context?
+        @parent.context?
+      end
+
+      private
+      def initialize_collections
+        @counters = TypedCollection.new InnerCounter, self, @value[:counters]
+        @flags = TypedCollection.new InnerFlag, self, @value[:flags]
+        @maps = TypedCollection.new InnerMap, self, @value[:maps]
+        @registers = TypedCollection.new InnerRegister, self, @value[:registers]
+        @sets = TypedCollection.new InnerSet, self, @value[:sets]
+      end
+    end
+  end
+end

data/lib/riak/crdt/inner_register.rb

@@ -0,0 +1,26 @@
+module Riak
+  module Crdt
+    class InnerRegister < String
+      attr_reader :parent
+      
+      def initialize(parent, *args, &block)
+        @parent = parent
+        super(*args, &block)
+        freeze
+      end
+
+      def self.update(value)
+        Operation::Update.new.tap do |op|
+          op.value = value
+          op.type = :register
+        end
+      end
+
+      def self.delete
+        Operation::Delete.new.tap do |op|
+          op.type = :register
+        end
+      end
+    end
+  end
+end

data/lib/riak/crdt/inner_set.rb

@@ -0,0 +1,95 @@
+module Riak
+  module Crdt
+    # The {InnerSet} is similar to a {Riak::Crdt::Set}, except it is part of
+    # a {Map} (or an {InnerMap} inside of a {Map}). It is usually accessed
+    # through a {TypedCollection}.
+    #
+    # Just like a {Riak::Crdt::Set}, it's a set of {String Strings} that can 
+    # be added to or removed from.
+    class InnerSet
+      # The name of this set inside a map.
+      #
+      # @api private
+      attr_accessor :name
+      
+      # The {::Set} value of this {InnerSet}.
+      #
+      # @return [::Set] set value
+      attr_reader :value
+      alias :members :value
+
+      # The parent of this counter.
+      #
+      # @api private
+      attr_reader :parent
+
+      # @api private
+      def initialize(parent, value=[])
+        @parent = parent
+        frozen_value = value.to_a.tap{ |v| v.each(&:freeze) }
+        @value = ::Set.new frozen_value
+        @value.freeze
+      end
+      
+      # Casts this {InnerSet} to an {Array}.
+      #
+      # @return [Array] an array of all the members of this set
+      def to_a
+        value.to_a
+      end
+
+      # Check if this {InnerSet} is empty.
+      #
+      # @return [Boolean} whether this structure is empty or not
+      def empty?
+        value.empty?
+      end
+
+      # Check if a given string is in this structure.
+      #
+      # @param [String] element candidate string to check for inclusion
+      # @return [Boolean] whether the candidate is in this set or not
+      def include?(element)
+        value.include? element
+      end
+
+      # Add a {String} to the {InnerSet}
+      #
+      # @param [String] element the element to add
+      def add(element)
+        @parent.operate name, update(add: element)
+      end
+
+      # Remove a {String} from this set
+      #
+      # @param [String] element the element to remove
+      def remove(element)
+        raise CrdtError::SetRemovalWithoutContextError unless context?
+        @parent.operate name, update(remove: element)
+      end
+
+            
+      # Does the map containing this set have the context necessary to remove elements?
+      #
+      # @return [Boolean] if the set has a defined context
+      def context?
+        @parent.context?
+      end
+
+      # @api private
+      def update(changes)
+        Operation::Update.new.tap do |op|
+          op.value = changes.symbolize_keys
+          op.type = :set
+        end
+      end
+
+      # @api private
+      def self.delete
+        Operation::Delete.new.tap do |op|
+          op.type = :set
+        end
+      end
+    end
+  end
+end

data/lib/riak/crdt/map.rb

@@ -0,0 +1,88 @@
+module Riak
+  module Crdt
+
+    # A distributed map of multiple fields, such as counters, flags, registers,
+    # sets, and, recursively, other maps, using the Riak 2 Data Types feature.
+    #
+    # Maps are complex, and the implementation is spread across many classes.
+    # You're looking at the top-level {Map} class, but there are also others
+    # that are also responsible for how maps work:
+    #
+    # * {InnerMap}: used for maps that live inside other maps
+    # * {BatchMap}: proxies multiple operations into a single Riak update request
+    # * {TypedCollection}: a collection of members of a single map, similar
+    #   to a Ruby {Hash}
+    # * {InnerFlag}: a boolean value inside a map
+    # * {InnerRegister}: a {String} value inside a map
+    # * {InnerCounter}: a {Riak::Crdt::Counter}, but inside a map
+    # * {InnerSet}: a {Riak::Crdt::Set}, but inside a map
+    # 
+    class Map < Base
+      attr_reader :counters, :flags, :maps, :registers, :sets
+      
+      # Create a map instance. If not provided, the default bucket type
+      # from {Riak::Crdt} will be used.
+      #
+      # @param bucket [Bucket] the {Riak::Bucket} for this map
+      # @param [String, nil] key The name of the map. A nil key makes
+      #        Riak assign a key.
+      # @param [String] bucket_type The optional bucket type for this map.
+      #        The default is in `Crdt::Base::DEFAULT_BUCKET_TYPES[:map]`.
+      # @param options [Hash]
+      def initialize(bucket, key, bucket_type=nil, options={})
+        super(bucket, key, bucket_type || DEFAULT_BUCKET_TYPES[:map], options)
+
+        initialize_collections
+      end
+
+      # Maps are frequently updated in batches. Use this method to get a 
+      # {BatchMap} to turn multiple operations into a single Riak update
+      # request.
+      #
+      # @yieldparam batch_map [BatchMap] collects updates and other operations 
+      def batch(*args)
+        batch_map = BatchMap.new self
+
+        yield batch_map
+
+        write_operations batch_map.operations, *args
+      end
+
+      # This method *for internal use only* is used to collect oprations from
+      # disparate sources to provide a user-friendly API.
+      # 
+      # @api private
+      def operate(operation, *args)
+        batch *args do |m|
+          m.operate operation
+        end
+      end
+      
+      private
+      def vivify(data)
+        @counters = TypedCollection.new InnerCounter, self, data[:counters]
+        @flags = TypedCollection.new InnerFlag, self, data[:flags]
+        @maps = TypedCollection.new InnerMap, self, data[:maps]
+        @registers = TypedCollection.new InnerRegister, self, data[:registers]
+        @sets = TypedCollection.new InnerSet, self, data[:sets]
+      end
+
+      def initialize_collections(data={})
+        reload if dirty?
+      end
+
+      def write_operations(operations, *args)
+        operator do |op|
+          op.operate(bucket.name,
+                     key,
+                     bucket_type,
+                     operations,
+                     *args
+                     )
+        end
+        # collections break dirty tracking
+        reload
+      end
+    end
+  end
+end