persistence 0.0.1.alpha → 0.0.1

data/lib/persistence/cursor/cursor_interface.rb

@@ -0,0 +1,337 @@
+
+###
+# Interface implementation for Cursor class instances.
+#
+module ::Persistence::Cursor::CursorInterface
+
+  include ::Enumerable
+
+  ################
+  #  initialize  #
+  ################
+  
+  ###
+  #
+  # @param bucket_instance Bucket to use for cursor context.
+  # @param index_instance Index to use for cursor context.
+  #
+  def initialize( bucket_instance, index_instance = nil )
+
+    @persistence_bucket = bucket_instance
+    @parent_index = index_instance
+    
+    # use persistence port, bucket, index, value to instantiate adapter cursor
+    if index_instance
+      @adapter_cursor = index_instance.adapter_index.cursor
+    else
+      @adapter_cursor = bucket_instance.adapter_bucket.cursor
+    end
+    
+  end
+  
+  ###########
+  #  close  #
+  ###########
+  
+  ###
+  # Declare cursor use complete.
+  #
+  # @return self
+  #
+  def close
+    
+    @adapter_cursor.close
+    
+    return self
+    
+  end
+
+  #############
+  #  atomize  #
+  #############
+
+  ###
+  # Enable cursor as atomic cursor, causing objects to be loaded with atomic properties, 
+  #   regardless how they are configured.
+  #
+  # @return self
+  #
+  def atomize
+    
+    extend( ::Persistence::Cursor::Atomic )
+    
+    return self
+    
+  end
+
+  ################
+  #  persisted?  #
+  ################
+  
+  ###
+  # Query whether keys are persisted in cursor's current context.
+  #
+  # @overload persisted?( key, ... )
+  #
+  #   @param [Object] Key to look up.
+  #
+  # @return [true,false] Whether key(s) exist in cursor's current context.
+  #
+  def persisted?( *args )
+
+    # [ global_id, ... ]
+
+    persisted = false
+
+    # args => global_id, ...
+    # positions on last id or false if one of ids is not persisted
+    if args.count > 0
+
+      args.each do |this_global_id|
+        break unless persisted = @adapter_cursor.persisted?( this_global_id )
+      end
+
+    # no args
+    # positions on first if keys or false if no keys
+    else
+
+      persisted = @adapter_cursor.persisted?
+
+    end
+
+    return @has_position = persisted
+
+  end
+
+  #############
+  #  persist  #
+  #############
+
+  ###
+  # Load object with specified persistence ID.
+  #
+  # @param global_id Object persistence ID for retrieval.
+  #
+  # @return [Object] Object for persistence ID.
+  #
+  def persist( global_id )
+
+    object = nil
+
+    if @has_position = @adapter_cursor.persisted?( global_id )
+      object = get_object( @adapter_cursor.current )
+    end
+
+    return object
+
+  end
+
+  ##########
+  #  each  #
+  ##########
+  
+  ###
+  # Iterate objects in current cursor context.
+  #
+  # @yield [object] Current object for cursor context.
+  #
+  # @yieldparam object Object stored in cursor context.
+  #
+  def each
+
+    # we have to set position if it's not already set before we can iterate
+    first unless @has_position
+
+    return to_enum unless block_given?
+
+    # support for Enumerator#feed - permit a return value
+    feed_value = nil
+
+    begin
+      while yield_object = self.next
+        feed_value = yield( yield_object )
+      end
+    rescue StopIteration
+    end
+
+    return feed_value
+    
+  end
+
+  ###########
+  #  first  #
+  ###########
+  
+  ###
+  # Persist first object in cursor context.
+  #
+  # @param [Integer] first_count How many objects to persist from start of cursor context.
+  #
+  # @return [Object,Array<Object>] Object or objects requested.
+  #
+  def first( first_count = 1 )
+
+    objects = nil
+
+    if @has_position = persisted?
+      begin
+        if first_count == 1
+          objects = current
+        else
+          objects = [ ]
+          first_count.times do
+            objects.push( self.next )
+          end
+        end
+        # reset to first
+        @adapter_cursor.first
+      rescue StopIteration
+      end
+    end
+
+    return objects
+
+  end
+
+  ##########
+  #  last  #
+  ##########
+  
+  ###
+  # Persist last object in cursor context.
+  #
+  # @param [Integer] last_count How many objects to persist from end of cursor context.
+  #
+  # @return [Object,Array<Object>] Object or objects requested.
+  #
+  def last( last_count = 1 )
+    
+    objects = nil
+    
+    if total_count = count
+      begin
+        first
+        skip_records = total_count - last_count
+        skip_records.times do
+          @adapter_cursor.next
+        end
+        if last_count == 1
+          objects = self.next
+        else
+          objects = [ ]
+          last_count.times do
+            objects.push( self.next )
+          end
+        end
+        # reset to first
+        @adapter_cursor.first
+      rescue StopIteration
+      end
+    end
+    
+    return objects
+    
+  end
+  
+  #########
+  #  any  #
+  #########
+  
+  ###
+  # Persist any object in cursor context.
+  #
+  # @param [Integer] any_count How many objects to persist from cursor context.
+  #
+  # @return [Object,Array<Object>] Object or objects requested.
+  #
+  def any( any_count = 1 )
+    
+    object = nil
+    
+    if total_count = count
+      begin
+        @adapter_cursor.first
+        objects = [ ]
+        any_count.times do
+          skip_records = rand( total_count - ( any_count + 1 ) )
+          skip_records.times do
+            @adapter_cursor.next
+          end
+          objects.push( self.next )
+        end
+        objects = objects[ 0 ] if objects.count <= 1
+        # reset to first
+        @adapter_cursor.first
+      rescue StopIteration
+      end      
+    end
+    
+    return objects
+    
+  end
+
+  #############
+  #  current  #
+  #############
+  
+  ###
+  # Persist current object in cursor context.
+  #
+  # @return [Object,Array<Object>] Object requested.
+  #
+  def current
+
+    first unless @has_position
+
+    return get_object( @adapter_cursor.current )
+
+  end
+
+  ##########
+  #  next  #
+  ##########
+  
+  ###
+  # Return the next object in cursor's current context.
+  #
+  # @return [Object] Next object in cursor's current context.
+  #  
+  def next( count = 1 )
+
+    objects = nil
+
+    if count > 1
+
+      objects = [ ]
+      count.times do
+        objects.push( get_object( @adapter_cursor.next ) )
+      end
+
+    else
+
+      objects = get_object( @adapter_cursor.next )
+
+    end
+
+    return objects
+
+  end
+
+  ################
+  #  get_object  #
+  ################
+
+  ###
+  # Get persistence hash for object with specified persistence ID.
+  #
+  # @param global_id Object persistence ID for retrieval.
+  #
+  # @return [Hash{String,Symbol=>Object}] Persistence hash of object properties for persistence ID.
+  #
+  def get_object( global_id )
+
+    return @persistence_bucket.get_object( global_id )
+
+  end
+
+end

data/lib/persistence/exception/block_required.rb

@@ -0,0 +1,7 @@
+
+###
+# Exception thrown when required block is not provided.
+#
+class ::Persistence::Exception::BlockRequired < Exception
+
+end

data/lib/persistence/exception/conflicting_index_already_declared.rb

@@ -0,0 +1,7 @@
+
+###
+# Exception thrown when an index is already declared with conflicting settings.
+#
+class ::Persistence::Exception::ConflictingIndexAlreadyDeclared < Exception
+  
+end

data/lib/persistence/exception/duplicate_violates_unique_index.rb

@@ -0,0 +1,7 @@
+
+###
+# Exception thrown when keys would create duplicate entries in an index that has been declared unique.
+#
+class ::Persistence::Exception::DuplicateViolatesUniqueIndex < Exception
+
+end

data/lib/persistence/exception/explicit_index_required.rb

@@ -0,0 +1,7 @@
+
+###
+# Exception thrown when an index that permits explicit keys is required but not provided.
+#
+class ::Persistence::Exception::ExplicitIndexRequired < Exception
+
+end

data/lib/persistence/exception/indexing_block_failed_to_generate_keys.rb

@@ -0,0 +1,7 @@
+
+###
+# Exception thrown when index fails to generate keys and requires keys to be generated.
+#
+class ::Persistence::Exception::IndexingBlockFailedToGenerateKeys < Exception
+
+end

data/lib/persistence/exception/indexing_object_requires_keys.rb

@@ -0,0 +1,7 @@
+
+###
+# Exception thrown when indexing should have created keys but did not.
+#
+class ::Persistence::Exception::IndexingObjectRequiresKeys < Exception
+
+end

data/lib/persistence/exception/key_value_required.rb

@@ -0,0 +1,7 @@
+
+###
+# Exception thrown when required key value is not provided.
+#
+class ::Persistence::Exception::KeyValueRequired < Exception
+
+end

data/lib/persistence/exception/no_port_enabled.rb

@@ -0,0 +1,7 @@
+
+###
+# Exception thrown when no persistence port is enabled and a function depending on a port is called.
+#
+class ::Persistence::Exception::NoPortEnabled < Exception
+
+end

data/lib/persistence/object.rb

@@ -0,0 +1,21 @@
+
+###
+# Convenience module for extending object of any type with persistence capabilities.
+#
+# If object is a {::Bignum}, {::Fixnum}, {::Complex}, {::Rational}, {::TrueClass}, {::FalseClass}, 
+# {::String}, {::Symbol}, {::Regexp}, or {::NilClass} then object will include 
+# {::Persistence::Object::Flat Persistence::Object::Flat}.
+#
+# If object is a File then object will include {::Persistence::Object::Flat::File Persistence::Object::Flat::File}.
+#
+# If object is an Array then object will include {::Persistence::Object::Complex::Array Persistence::Object::Complex::Array}.
+#
+# If object is a Hash then object will include {::Persistence::Object::Complex::Hash Persistence::Object::Complex::Hash}.
+#
+# If object is any other class then object will include {::Persistence::Object::Complex Persistence::Object::Complex}.
+#
+module ::Persistence::Object
+  
+  extend ::Persistence::Object::Autodetermine
+  
+end

data/lib/persistence/object/autodetermine.rb

@@ -0,0 +1,74 @@
+
+###
+# @private
+###
+# Module used internally to extend Persistence and Persistence::Object to automatically determine what type of object
+#   (of types: Complex, Flat, Hash, Array, File) module is being included in, and to include the appropriate
+#   corresponding module branch.
+module ::Persistence::Object::Autodetermine
+
+  ###################
+  #  self.extended  #
+  ###################
+  
+  def self.extended( persistence_object_module )
+
+    persistence_object_module.extend ModuleCluster::Define::Block::ClassOrModuleOrInstance
+    
+    persistence_object_module.class_or_module_include do |class_or_module|
+
+      # two types of objects: complex and flat
+      # * complex objects persist ivars
+      # * flat objects persist themselves (no ivars)
+      #
+      # if you want a different result, use the appropriate module directly
+      # * ::Persistence::Complex
+      # * ::Persistence::Flat
+
+      # if we have a flat object, extend for flat object
+      if class_or_module <= ::Array
+        
+        class_or_module.module_eval do
+          include ::Persistence::Object::Complex::Array
+        end
+        
+      elsif class_or_module <= ::Hash
+        
+        class_or_module.module_eval do
+          include ::Persistence::Object::Complex::Hash
+        end
+        
+      elsif  class_or_module <= ::Bignum      or
+             class_or_module <= ::Fixnum      or
+             class_or_module <= ::Complex     or
+             class_or_module <= ::Rational    or
+             class_or_module <= ::TrueClass   or
+             class_or_module <= ::FalseClass  or
+             class_or_module <= ::String      or
+             class_or_module <= ::Symbol      or
+             class_or_module <= ::Regexp      or
+             class_or_module <= ::File        or
+             class_or_module <= ::NilClass
+
+        class_or_module.module_eval do
+          include ::Persistence::Object::Flat
+        end
+
+      # otherwise extend as a complex object
+      else
+
+        class_or_module.module_eval do
+          include ::Persistence::Object::Complex
+        end
+
+      end
+
+    end
+
+    persistence_object_module.class_or_module_or_instance_extend do
+      raise 'Persistence does not expect to be used without class-level support.'
+    end
+    
+  end
+  
+end