persistence 0.0.1.alpha → 0.0.1

data/lib/persistence/object/index/block_index.rb

@@ -0,0 +1,10 @@
+
+###
+# Class used for block index instances, which index keys provided by running a Proc on an object instance. 
+#   Interface provided in module so interface can be easily overridden.
+#
+class ::Persistence::Object::Index::BlockIndex
+  
+  include ::Persistence::Object::Index::BlockIndex::BlockIndexInterface
+    
+end

data/lib/persistence/object/index/block_index/block_index_interface.rb

@@ -0,0 +1,110 @@
+
+###
+# Interface for block index instances, which index keys provided by running a Proc on an object instance.
+#
+module ::Persistence::Object::Index::BlockIndex::BlockIndexInterface
+  
+  include ::Persistence::Object::Index
+  
+  include ::CascadingConfiguration::Setting
+  include ::CascadingConfiguration::Array
+  
+  ###
+  #
+  # @yield [object] Block to create index keys on object.
+  # @yieldparam object [Object] Object to index.
+  #
+  def initialize( index_name, 
+                  parent_bucket, 
+                  permits_duplicates = nil, 
+                  sorting_proc_or_sort_names = nil, 
+                  duplicates_sorting_proc_or_sort_names = nil,
+                  ancestor_index_instance = nil,
+                  & indexing_block )
+    
+    super
+    
+    if block_given?
+      indexing_procs.push( indexing_block )
+    elsif indexing_procs.empty?
+      raise ::Persistence::Exception::BlockRequired, 'Block required for index.'
+    end
+    
+        
+  end
+
+  ###################
+  #  requires_keys  #
+  ###################
+
+  ###
+  # Whether index requires keys be generated when block is run.
+  #
+  # @return [true,false] Whether keys must be generated.
+  #
+  attr_setting  :requires_keys
+
+  #######################
+  #  permits_nil_keys?  #
+  #######################
+  
+  ###
+  # Whether index permits nil keys be generated when block is run.
+  #
+  # @return [true,false] Whether keys must be non-nil.
+  #
+  attr_setting  :permits_nil_keys?
+
+  ####################
+  #  indexing_procs  #
+  ####################
+  
+  ###
+  # Procs used to generate keys.
+  #
+  # @return [CompositingArray<Proc>] Procs for key generation.
+  #
+  attr_array  :indexing_procs
+    
+  ##################
+  #  index_object  #
+  ##################
+
+  ###
+  # Index keys for object instance.
+  #
+  # @param object [Object] Object to index.
+  #
+  def index_object( object )
+
+    # get key(s) from block(s)
+    keys = [ ]
+    indexing_procs.each do |this_indexing_proc|
+
+      if block_return = object.instance_eval( & this_indexing_proc ) or
+         permits_nil_keys?
+
+        keys.push( block_return )
+
+      end
+
+    end
+
+    if keys.empty?
+
+      if requires_keys
+        raise ::Persistence::Exception::IndexingBlockFailedToGenerateKeys.new,
+              'Index block failed to generate keys, which were required.'      
+      end
+
+    else
+      
+      super( object, *keys )
+
+    end
+    
+    return self
+    
+  end
+  
+end

data/lib/persistence/object/index/explicit_index.rb

@@ -0,0 +1,10 @@
+
+###
+# Class used for explicit index instances, which index keys that are explicitly provided. 
+#   Interface provided in module so interface can be easily overridden.
+#
+class ::Persistence::Object::Index::ExplicitIndex
+
+  include ::Persistence::Object::Index::ExplicitIndex::ExplicitIndexInterface
+  
+end

data/lib/persistence/object/index/explicit_index/explicit_index_interface.rb

@@ -0,0 +1,57 @@
+
+###
+# Interface for explicit index instances, which index keys that are explicitly provided.
+#
+module ::Persistence::Object::Index::ExplicitIndex::ExplicitIndexInterface
+  
+  include ::Persistence::Object::Index
+  
+  ###
+  #
+  # @method index_existing_objects
+  #
+  # We undefine :index_existing_objects because it makes no sense on an index requiring explicit keys.
+  # 
+  undef_method( :index_existing_objects )
+
+  ##################
+  #  index_object  #
+  ##################
+
+  ###
+  # Index keys for object instance.
+  #
+  # @param object [Object] Object to index.
+  #
+  # @param keys [Array<Object>] Keys to use for index entries.
+  #
+  def index_object( object, *keys )
+    
+    if keys.empty?
+      raise ::Persistence::Exception::IndexingObjectRequiresKeys.new,
+            'No keys provided for index.'
+    end
+    
+    # check for existing index on keys if we don't permit duplicates
+    unless permits_duplicates?
+
+      keys.each do |this_key|
+        if global_id = adapter_index.get_object_id( this_key ) and
+           global_id != object.persistence_id
+          raise ::Persistence::Exception::DuplicateViolatesUniqueIndex.new,
+                'Attempt to create index for key ' + this_key.to_s +
+                ' would create duplicates in unique index :' + @name.to_s + '.'
+        end
+      end
+    
+    end
+
+    keys.each do |this_key|
+      adapter_index.index_object_id( object.persistence_id, this_key )
+    end
+
+    return self
+    
+  end
+  
+end

data/lib/persistence/object/index_hash.rb

@@ -0,0 +1,40 @@
+
+###
+# @private
+#
+# Internal helper module with common features for hashes that store indexes.
+#
+module ::Persistence::Object::IndexHash
+
+  ###################
+  #  post_set_hook  #
+  ###################
+  
+  def post_set_hook( index_name, index_instance )
+
+    configuration_instance.indexes[ index_name ] = index_instance
+    
+  end
+  
+  ########################
+  #  child_pre_set_hook  #
+  ########################
+  
+  def child_pre_set_hook( index_name, index_instance )
+    
+    parent_bucket = nil
+    
+    case configuration_instance
+      when ::Module
+        parent_bucket = configuration_instance.instance_persistence_bucket
+      else
+        parent_bucket = configuration_instance.persistence_bucket
+    end
+    
+    child_index_instance = index_instance.class.new( nil, parent_bucket, nil, nil, nil, index_instance )
+    
+    return child_index_instance
+    
+  end
+  
+end

data/lib/persistence/object/object_instance.rb

@@ -0,0 +1,322 @@
+
+###
+# Instance methods for any objects enabled with persistence capabilities.
+#
+module ::Persistence::Object::ObjectInstance
+  
+  include ::Persistence::Object::ParsePersistenceArgs
+
+  include ::CascadingConfiguration::Setting
+  include ::CascadingConfiguration::Hash
+  
+  #######################
+  #  persistence_port=  #
+  #######################
+
+  attr_local_configuration :persistence_port
+
+  ###
+  # Assign a persistence port to be used with this object.
+  #
+  # @overload persistence_port=( port_name )
+  #    
+  #   @param port_name Name of port to be used. Expects port by name to be available in Persistence controller.
+  #
+  # @overload persistence_port=( port_instance )
+  #
+  #   @param port_instance Port instance to use.
+  #
+  def persistence_port=( persistence_port_class_or_name )
+
+    case persistence_port_class_or_name
+      
+      when ::Symbol, ::String
+      
+        super( ::Persistence.port_for_name_or_port( persistence_port_class_or_name, true ) )
+      
+      else
+
+        if persistence_port_class_or_name.respond_to?( :persistence_port )
+          super( persistence_port_class_or_name.persistence_port )
+        end
+      
+    end
+      
+    
+    return self
+    
+  end
+
+  ######################
+  #  persistence_port  #
+  ######################
+  
+  ###
+  # Get persistence port that will be used with this object. Will use instance persistence port if no port is assigned,
+  #   which will result in using the current port if no instance persistence port is specified.
+  #
+  # @return [Persistence::Port,nil] Persistence port instance.
+  #
+  def persistence_port
+
+    # if specified at instance level, use specified value
+    # otherwise, use value stored in class  
+    return super || self.class.instance_persistence_port
+
+  end
+  
+  #########################
+  #  persistence_bucket=  #
+  #########################
+
+  attr_instance_setting :persistence_bucket
+
+  ###
+  # Assign a persistence bucket to be used with this object.
+  #
+  # @overload instance_persistence_bucket=( bucket_name )
+  #    
+  #   @param port_name [Symbol,String] Name of port to be used. Expects port by name to be available 
+  #     in Persistence controller.
+  #
+  # @overload instance_persistence_bucket=( bucket_instance )
+  #
+  #   @param port_instance [Persistence::Port::Bucket,nil] Persistence::Port::Bucket instance to use.
+  #
+  def persistence_bucket=( persistence_bucket_class_or_name )
+    
+    if persistence_bucket_class_or_name.nil?
+      
+      super( nil )
+      
+    elsif persistence_bucket_class_or_name.is_a?( ::Persistence::Port::Bucket )
+    
+      super( persistence_bucket_class_or_name )
+    
+    elsif persistence_bucket_class_or_name.respond_to?( :instance_persistence_bucket )
+
+      # if arg responds to :instance_persistence_bucket we use arg's bucket
+      super( persistence_bucket_class_or_name.instance_persistence_bucket )
+
+    elsif ! ( persistence_bucket_class_or_name.is_a?( String )  or 
+              persistence_bucket_class_or_name.is_a?( Symbol ) )   and 
+          persistence_bucket_class_or_name.respond_to?( :persistence_bucket )
+      
+      # if arg responds to :persistence_bucket we use arg's bucket
+      super( persistence_bucket_class_or_name.persistence_bucket )
+    
+    else
+      
+      # otherwise we use arg as a symbol
+      # this means classnames are ok (which are default)
+      self.persistence_bucket = persistence_port.persistence_bucket( persistence_bucket_class_or_name.to_sym )
+    
+    end
+    
+    return self
+    
+  end
+
+  ########################
+  #  persistence_bucket  #
+  ########################
+  
+  ###
+  # Get persistence bucket that will be used with this object. Will use name of class if bucket
+  #   does not already exist.
+  #
+  # @return [Persistence::Port,nil] Persistence port instance.
+  #
+  def persistence_bucket
+
+    # if specified at instance level, use specified value
+    # otherwise, use value stored in class
+    return super || self.class.instance_persistence_bucket
+
+  end
+
+  ####################
+  #  persistence_id  #
+  ####################
+  
+  ###
+  # Get persistence ID, used to identify unique objects.
+  #
+  attr_instance_setting :persistence_id
+
+  ##############
+  #  persist!  #
+  ##############
+  
+  ###
+  # Store object to persistence port. Will cause all non-atomic properties to be updated if object has already
+  #   been persisted.
+  #
+  # @overload persist!
+  #
+  # @overload persist!( index_name, key )
+  # 
+  #   @param index_name [Symbol,String] Name of index for explicit key-based indexing.
+  #   @param key [Object] Key for explicit indexing.
+  #
+  # @overload persist!( index_name_key_hash )
+  #
+  #   @param index_name_key_hash [Hash{Symbol,String=>Object}] Name of index for explicit key-based indexing,
+  #     pointing to index value.
+  #
+  # @overload persist!( index_instance, key )
+  #
+  #   @param index_instance [Symbol,String] Name of index for explicit key-based indexing.
+  #   @param key [Object] Key for explicit indexing.
+  #
+  # @overload persist!( index_instance_key_hash )
+  #
+  #   @param index_instance_key_hash [Hash{Persistence::Object::Index=>Object}] Name of index  
+  #     for explicit key-based indexing, pointing to index value.
+  #
+  # @return self
+  #
+  def persist!( *args )
+    
+    index_instance, key, no_key = parse_args_for_index_value_no_value( args, false )
+
+    # call super to ensure object is persisted
+    unless persistence_port
+      raise ::Persistence::Exception::NoPortEnabled, 'No persistence port currently enabled.'
+    end
+
+    self.persistence_id = persistence_bucket.put_object!( self )
+
+    if index_instance
+
+      # if we have an index make sure that we have a key
+      if no_key
+        raise ::Persistence::Exception::KeyValueRequired,
+              'Key required when specifying index for :persist!'
+      end
+
+      # and make sure we have an index that permits arbitrary keys
+      unless explicit_indexes[ index_instance.name ] == index_instance
+        raise ::Persistence::Exception::ExplicitIndexRequired,
+              'Index ' + index_instance.name.to_s + ' was not declared as an explicit index '
+              'and thus does not permit arbitrary keys.'
+      end
+
+      index_instance.index_object( self, key )
+      
+    end
+    
+    unless block_indexes.empty?
+      block_indexes.each do |this_index_name, this_block_index|
+        this_block_index.index_object( self )
+      end
+    end
+    
+    return self
+    
+  end
+  
+  ################
+  #  persisted?  #
+  ################
+
+  ###
+  # Query whether object is persisted in port.
+  #
+  # @return [true,false] Whether object is persisted.
+  #
+  def persisted?
+    
+    bucket_name = persistence_port.get_bucket_name_for_object_id( persistence_id )
+    
+    return bucket_name ? true : false
+
+  end
+  
+  ############
+  #  cease!  #
+  ############
+
+  ###
+  # Remove object properties stored for object from persistence bucket and indexes.
+  #
+  def cease!
+
+    indexes.each do |this_index_name, this_index|
+      this_index.delete_keys_for_object_id!( persistence_id )
+    end
+
+    persistence_hash_from_port = persistence_bucket.delete_object!( persistence_id )
+    
+    self.persistence_id = nil
+    
+    return persistence_hash_from_port
+
+  end
+    
+  ######################
+  #  explicit_indexes  #
+  ######################
+  
+  ###
+  #
+  # @method explicit_indexes
+  #
+  # Hash holding explicit indexes: index_name => index.
+  #
+  # @return [CompositingHash{Symbol,String=>Persistence::Object::Index::ExplicitIndex}]
+  #
+  attr_hash :explicit_indexes, ::Persistence::Object::IndexHash
+  
+  ###################
+  #  block_indexes  #
+  ###################
+  
+  ###
+  #
+  # @method block_indexes
+  #
+  # Hash holding block indexes: index_name => index.
+  #
+  # @return [CompositingHash{Symbol,String=>Persistence::Object::Index::BlockIndex}]
+  #
+  attr_hash :block_indexes, ::Persistence::Object::IndexHash
+  
+  #############
+  #  indexes  #
+  #############
+
+  ###
+  #
+  # @method indexes
+  #
+  # Hash holding indexes: index_name => index.
+  #
+  # @return [CompositingHash{Symbol,String=>Persistence::Object::Index}]
+  #
+  attr_hash :indexes do
+    
+    #======================#
+    #  child_pre_set_hook  #
+    #======================#
+    
+    def child_pre_set_hook( index_name, index_instance )
+      
+      child_instance = nil
+      
+      case index_instance
+        when ::Persistence::Object::Index::ExplicitIndex
+          child_instance = configuration_instance.explicit_indexes[ index_name ]
+        when ::Persistence::Object::Index::BlockIndex
+          child_instance = configuration_instance.block_indexes[ index_name ]                  
+        when ::Persistence::Object::Complex::Index::AttributeIndex
+          child_instance = configuration_instance.attribute_indexes[ index_name ]
+      end
+
+      return child_instance
+      
+    end
+    
+  end
+  
+end