persistence 0.0.1.alpha → 0.0.1

data/lib/persistence/object/parse_persistence_args.rb

@@ -0,0 +1,145 @@
+
+###
+# @private
+#
+# Internal helper for parsing args of the format: method, method( global_id ), method( index_name, value ),
+#   method( index_instance, value ), method( index_name => value ), method( index_instance => value ).
+module ::Persistence::Object::ParsePersistenceArgs
+
+  #########################################
+  #  parse_args_for_index_value_no_value  #
+  #########################################
+  
+  ###
+  # Parse *args for index, key_value, no_value.
+  #
+  # @param args [Array] An array of args of the format: method, method( global_id ), method( index_name, value ),
+  #   method( index_instance, value ), method( index_name => value ), method( index_instance => value ).
+  #
+  # @param require_value [true,false] Whether key value must be provided; will throw exception if true and
+  #   key value is not provided.
+  #
+  # @return [Array] Array containing index instance, key value, whether key value was provided.
+  #
+  def parse_args_for_index_value_no_value( args, require_value = false )
+    
+    # * nil
+    #   - Cursor to primary bucket
+    # * :index
+    #   - Cursor to index
+    # * :index => persistence_key
+    #   - Object(s) for indexed key value
+    
+    index = nil
+    key_value = nil
+    no_value = nil
+    case args.count
+
+      when 0
+
+        no_value = true
+        if require_value
+          raise ::Persistence::Exception::KeyValueRequired, 
+                'Key value required.'
+        end
+
+      when 1
+
+        index_or_id = args[ 0 ]
+        if index_or_id.is_a?( Symbol ) or
+           index_or_id.is_a?( String )
+
+           index = indexes[ index_or_id ]
+           unless index
+             raise ::Persistence::Exception::ExplicitIndexRequired,
+                   'Explicit index ' + index_or_id.to_s + ' did not exist.'
+           end
+           no_value = true
+        
+        elsif index_or_id.respond_to?( :index_object )
+          
+          index = index_or_id
+          no_value = true
+          
+        elsif index_or_id.is_a?( Hash )
+        
+          key_value = index_or_id.values[ 0 ]
+          index_name = index_or_id.keys[ 0 ]
+          if index_name.is_a?( Symbol ) or
+             index_name.is_a?( String )
+             
+            index = indexes[ index_name ]
+            unless index
+              raise ::Persistence::Exception::ExplicitIndexRequired,
+                    'Explicit index :' + index_name.to_s + ' did not exist.'
+            end
+
+          end
+          no_value = false
+
+        else
+
+          # persistence_id - anything other than Symbol, String, Hash
+          key_value = args[ 0 ]
+          no_value = false
+          
+        end
+        
+      when 2
+
+        index_or_name = args[ 0 ]
+
+        index = index_or_name.respond_to?( :index_object ) ? index_or_name : indexes[ index_or_name ]
+        key_value = args[ 1 ]
+
+        if ! index and ! key_value
+          raise ::Persistence::Exception::ExplicitIndexRequired,
+                'Index ' + index_or_name.to_s + ' did not exist.'
+        end
+        no_value = false
+
+      else
+
+        raise 'Unexpected arguments ' + args.inspect + '.'
+
+    end
+    
+    # if we have a file we need to persist it like we would a sub-object
+    if key_value.is_a?( File )
+      key_value = process_file_key( key_value )
+    end
+    
+    return index, key_value, no_value
+    
+  end
+
+  ######################
+  #  process_file_key  #
+  ######################
+  
+  ###
+  # Internal helper method to handle instances of File as key.
+  #
+  # @param file_key [File] File instance to process as key.
+  #
+  # @return [Persistence::Object::Flat::File::Path,Persistence::Object::Flat::File::Contents] Processed key.
+  #
+  def process_file_key( file_key )
+
+    # do we have a file key? if so we need to replace it with File::Path or File::Contents
+
+    processed_key = nil
+    
+    if persists_files_by_path?
+      processed_key = ::Persistence::Object::Flat::File::Path.new( file_key.path )
+    else
+      starting_pos  = file_key.pos
+      processed_key = ::Persistence::Object::Flat::File::Contents.new( file_key.readlines.join )
+      file_key.pos  = starting_pos
+    end
+    
+    return processed_key
+    
+  end
+    
+end

data/lib/persistence/port.rb

@@ -0,0 +1,9 @@
+
+###
+# Public interface to storage port. Provides consist interface to adapter implementation.
+#
+class ::Persistence::Port
+  
+  include ::Persistence::Port::PortInterface
+  
+end

data/lib/persistence/port/bucket.rb

@@ -0,0 +1,9 @@
+
+###
+# Public interface to bucket in storage port. Provides consistent interface to adapter implementation.
+#
+class ::Persistence::Port::Bucket
+
+  include ::Persistence::Port::Bucket::BucketInterface
+  
+end

data/lib/persistence/port/bucket/bucket_index.rb

@@ -0,0 +1,9 @@
+
+###
+# Bucket indexes run on each object inserted into bucket.
+#
+class ::Persistence::Port::Bucket::BucketIndex
+  
+  include ::Persistence::Object::Index::BlockIndex::BlockIndexInterface
+  
+end

data/lib/persistence/port/bucket/bucket_interface.rb

@@ -0,0 +1,685 @@
+
+###
+# Interface for Bucket implementation. Provided separately for easy overriding.
+#
+module ::Persistence::Port::Bucket::BucketInterface
+
+  include ::Persistence::Object::Flat::File::FilePersistence
+
+  include ::Enumerable
+
+  ################
+  #  initialize  #
+  ################
+
+  ###
+  #
+  # @param parent_port Port where this bucket is active. Can be nil if no port is yet enabled.
+  #
+  # @param bucket_name Name of the bucket to open in port.
+  #
+  def initialize( parent_port, bucket_name )
+
+    @name = bucket_name
+
+    @indexes = { }
+    @pending_indexes = [ ]
+
+    if parent_port
+      initialize_for_port( parent_port )
+    end
+    
+  end
+
+  #########################
+  #  initialize_for_port  #
+  #########################
+  
+  ###
+  # Initialize bucket for a port that has been enabled.
+  #
+  # @param port Parent port in which to initialize bucket.
+  #
+  def initialize_for_port( port )
+
+    if port = ::Persistence.port_for_name_or_port( port ) and port.enabled?
+    
+      @parent_port = ::Persistence.port_for_name_or_port( port )
+    
+      if @parent_port.enabled?
+        @adapter_bucket = @parent_port.adapter.persistence_bucket( @name )
+      end
+
+      @indexes.each do |this_index_name, this_index_instance|
+        this_index_instance.initialize_for_bucket( self )
+      end
+    
+      @pending_indexes.delete_if do |this_pending_index|
+        this_pending_index.initialize_for_bucket( self )
+        true
+      end
+    
+    else
+      
+      disable
+      
+    end
+    
+  end
+
+  ####################
+  #  adapter_bucket  #
+  ####################
+  
+  ###
+  # Retrieve parallel adapter bucket instance.
+  #
+  # @return [Object] Adapter bucket instance.
+  #
+  def adapter_bucket
+    
+    unless @adapter_bucket
+      raise 'Persistence port must be enabled first.'
+    end
+    
+    return @adapter_bucket
+    
+  end
+
+  ##########
+  #  name  #
+  ##########
+  
+  ###
+  # @!attribute [accessor] Name of bucket
+  #
+  # @return [Symbol,String] Name.
+  #
+  attr_accessor :name
+  
+  #################
+  #  parent_port  #
+  #################
+  
+  attr_accessor :parent_port
+  
+  #############
+  #  disable  #
+  #############
+
+  ###
+  # @private
+  #
+  # Disable bucket when port disables. Internal helper method necessary to ensure 
+  # that old references don't stick around.
+  #
+  def disable
+
+    @adapter_bucket = nil
+    @parent_port = nil
+    
+    @indexes.each do |this_index_name, this_index|
+      this_index.disable
+    end
+    
+  end
+
+  ##################
+  #  create_index  #
+  ##################
+  
+  ###
+  # Create a bucket index, which is a block index that runs on each inserted object, regardless of type.
+  #
+  def create_index( index_name, sort_by_proc = nil, & indexing_block )
+    
+    return create_bucket_index( index_name, false, sort_by_proc, & indexing_block )
+    
+  end
+
+  ##################################
+  #  create_index_with_duplicates  #
+  ##################################
+  
+  ###
+  # Create a bucket index that permits duplicates.
+  #
+  def create_index_with_duplicates( index_name, sort_by_proc = nil, sort_duplicates_by_proc = nil, & indexing_block )
+
+    return create_bucket_index( index_name, true, sort_by_proc, sort_duplicates_by_proc, & indexing_block )
+    
+  end
+
+  ################
+  #  pend_index  #
+  ################
+  
+  ###
+  # @private
+  #
+  # Pend index instance for port to be enabled.
+  #
+  # @param index_instance Instance of index that is waiting for port to be enabled.
+  #
+  def pend_index( index_instance )
+    
+    @pending_indexes.push( index_instance )
+    
+  end
+  
+  ###########
+  #  index  #
+  ###########
+  
+  ###
+  # Retrieve index.
+  #
+  # @param index_name [Symbol,String] Name of index
+  # 
+  # @param ensure_exists [true,false] Whether exception should be thrown if index does not exist.
+  #
+  # @return [Persistence::Object::Index] Index instance
+  #
+  def index( index_name, ensure_exists = false )
+    
+    index_instance = nil
+    
+    unless index_instance = @indexes[ index_name ]
+      if ensure_exists
+        raise ::ArgumentError, 'No index found by name ' << index_name.to_s + '.'
+      end
+    end
+    
+    return index_instance
+    
+  end
+
+  ################
+  #  has_index?  #
+  ################
+  
+  ###
+  # Query whether attribute index(es) exist for object.
+  #
+  # @overload has_attribute_index?( index_name, ... )
+  #
+  #   @param index_name Name of requested index.
+  #
+  # @return [true,false] Whether index(es) exist.
+  #
+  def has_index?( *indexes )
+    
+    has_index = false
+    
+    indexes.each do |this_index|
+      break unless has_index = @indexes.has_key?( index_name )
+    end
+    
+    return has_index
+    
+  end
+
+  ###########
+  #  count  #
+  ###########
+
+  ###
+  # Get the number of objects in index. See {::Enumerable}.
+  #
+  # @return [Integer] Number of objects in bucket.
+  #
+  def count( *args, & count_block ) 
+
+    return_value = 0
+    
+    if block_given?
+      return_value = super( & count_block )
+    elsif args.empty?
+      return_value = adapter_bucket.count
+    else
+      return_value = super( *args )
+    end
+
+    return return_value
+
+  end
+
+  #############################
+  #  delete_index_for_object  #
+  #############################
+
+  ###
+  # @private
+  #
+  # Delete indexed entries for object.
+  #
+  # @param object Object that owns indexed entries.
+  #
+  # @param index_name Name of index.
+  #
+  def delete_index_for_object( object, index_name )
+
+    return delete_index_for_object_id( object.persistence_id )
+
+  end
+
+  ################################
+  #  delete_index_for_object_id  #
+  ################################
+  
+  ###
+  # @private
+  #
+  # Delete indexed entries for object.
+  #
+  # @param global_id Object persistence ID that owns indexed entries.
+  #
+  # @param index_name Name of index.
+  #
+  def delete_index_for_object_id( global_id, index_name )
+
+    return adapter_bucket.delete_index_for_object_id( global_id )
+
+  end
+
+  ###################
+  #  get_attribute  #
+  ###################
+  
+  ###
+  # @private
+  #
+  # Get attribute for object from port. 
+  #
+  # @param object Object that owns indexed entries.
+  #
+  # @param attribute_name Name of attribute.
+  #
+  def get_attribute( object, attribute_name )
+    
+    primary_key = primary_key_for_attribute_name( object, attribute_name )
+
+    attribute_value = adapter_bucket.get_attribute( object, primary_key )
+
+    if attribute_value.is_a?( ::Persistence::Object::Complex::ComplexObject )
+      attribute_value.persistence_port = object.persistence_port
+      attribute_value = attribute_value.persist
+    end
+    
+    return attribute_value
+
+  end
+
+  ####################
+  #  put_attribute!  #
+  ####################
+  
+  ###
+  # @private
+  #
+  # Put attribute for object to port. 
+  #
+  # @param object Object that owns indexed entries.
+  #
+  # @param attribute_name Name of attribute.
+  #
+  # @param attribute_value Value to put.
+  #
+  def put_attribute!( object, attribute_name, attribute_value )
+    
+    primary_key = primary_key_for_attribute_name( object, attribute_name )
+    
+    return adapter_bucket.put_attribute!( object, primary_key, attribute_value )
+    
+  end
+
+  #################
+  #  put_object!  #
+  #################
+  
+  ###
+  # @private
+  #
+  # Put object properties to persistence port.
+  #
+  # @param object Object to persist to port.
+  #
+  def put_object!( object )    
+
+    return adapter_bucket.put_object!( object )
+
+  end
+    
+  ################
+  #  get_object  #
+  ################
+
+  ###
+  # @private
+  #
+  # Get object from persistence port.
+  #
+  # @param global_id Object persistence ID to persist from port.
+  #
+  # @return [Object] Persisted object instance.
+  #
+  def get_object( global_id )
+    
+    object = nil
+    
+    # get the class
+    if klass = @parent_port.get_class_for_object_id( global_id )
+
+      object = klass.new
+      
+      object.persistence_id = global_id
+
+      # if we have non-atomic attributes, load them
+      unless klass.non_atomic_attribute_readers.empty?
+
+        if persistence_hash_from_port = get_object_hash( global_id )
+          
+          object.load_persistence_hash( object.persistence_port, persistence_hash_from_port )
+
+        end
+
+      end
+
+    end
+    
+    return object
+
+  end
+  
+  #####################
+  #  get_object_hash  #
+  #####################
+
+  ###
+  # @private
+  #
+  # Get object properties from persistence port.
+  #
+  # @param global_id Object persistence ID to persist from port.
+  #
+  # @return [Hash] Persistence hash from port.
+  #
+  def get_object_hash( global_id )
+
+    return adapter_bucket.get_object( global_id )
+
+  end
+
+  #####################
+  #  get_flat_object  #
+  #####################
+
+  ###
+  # @private
+  #
+  # Get flat object from persistence port.
+  #
+  # @param global_id Object persistence ID to persist from port.
+  #
+  # @return [Object] Persisted object instance.
+  #
+  def get_flat_object( global_id )
+
+    flat_object = nil
+
+    if persistence_value_hash = adapter_bucket.get_object( global_id )
+
+      if persistence_value_key_data = persistence_value_hash.first
+        flat_object = persistence_value_key_data[ 1 ]
+        flat_object.persistence_id = global_id
+      end
+    end
+
+    return flat_object
+    
+  end
+
+  ####################
+  #  delete_object!  #
+  ####################
+
+  ###
+  # @private
+  #
+  # Delete object from persistence port.
+  #
+  # @param global_id Object persistence ID to delete from port.
+  #
+  # @return [Hash] Persistence hash from port.
+  #
+  def delete_object!( global_id )
+    
+    return adapter_bucket.delete_object!( global_id )
+  
+  end
+
+  #######################
+  #  delete_attribute!  #
+  #######################
+
+  ###
+  # @private
+  #
+  # Delete attribute for object from port. 
+  #
+  # @param object Object that owns indexed entries.
+  #
+  # @param attribute_name Name of attribute.
+  #
+  def delete_attribute!( object, attribute_name )
+
+    primary_key = primary_key_for_attribute_name( object, attribute_name )
+
+    return adapter_bucket.delete_attribute!( object, primary_key )
+
+  end
+
+  ####################################
+  #  primary_key_for_attribute_name  #
+  ####################################
+
+  ###
+  # @private
+  #
+  # Generate primary key for storage for attribute name on object.
+  #
+  # @param object Object for which attribute is being stored.
+  #
+  # @param attribute_name Name of attribute.
+  #
+  # @return [String] Primary key.
+  #
+  def primary_key_for_attribute_name( object, attribute_name )
+
+    return adapter_bucket.primary_key_for_attribute_name( object, attribute_name )
+
+  end
+
+  ################################
+  #  persists_files_by_content?  #
+  ################################
+
+  def persists_files_by_content?
+    
+    persists_files_by_content = nil
+    
+    persists_files_by_content = super
+    
+    if persists_files_by_content.nil?
+      persists_files_by_content = parent_port.persists_files_by_content?
+    end
+    
+    return persists_files_by_content
+    
+  end
+
+  #############################
+  #  persists_files_by_path?  #
+  #############################
+
+  def persists_files_by_path?
+    
+    persists_files_by_path = nil
+    
+    persists_files_by_path = super
+    
+    if persists_files_by_path.nil?
+      persists_files_by_path = parent_port.persists_files_by_path?
+    end
+    
+    return persists_files_by_path
+    
+  end
+
+  #####################################
+  #  persists_file_paths_as_objects?  #
+  #####################################
+
+  def persists_file_paths_as_objects?
+    
+    persists_file_paths_as_objects = nil
+    
+    persists_file_paths_as_objects = super
+    
+    if persists_file_paths_as_objects.nil?
+      persists_file_paths_as_objects = parent_port.persists_file_paths_as_objects?
+    end
+    
+    return persists_file_paths_as_objects
+    
+  end
+
+  #####################################
+  #  persists_file_paths_as_strings?  #
+  #####################################
+
+  def persists_file_paths_as_strings?
+    
+    persists_file_paths_as_strings = nil
+    
+    persists_file_paths_as_strings = super
+    
+    if persists_file_paths_as_strings.nil?
+      persists_file_paths_as_strings = parent_port.persists_file_paths_as_strings?
+    end
+    
+    return persists_file_paths_as_strings
+    
+  end
+
+  ############
+  #  cursor  #
+  ############
+
+  ###
+  # Create and return cursor instance for this bucket.
+  #
+  # @return [Persistence::Cursor] New cursor instance.
+  #
+  def cursor( *args, & block )
+    
+    cursor_instance = ::Persistence::Cursor.new( self )
+    
+    if args.count > 0
+      cursor_instance.persisted?( *args )
+    end
+    
+    if block_given?
+      cursor_instance = cursor_instance.instance_eval( & block )
+      cursor_instance.close
+    end
+    
+    return cursor_instance
+  
+  end
+
+  ###################
+  #  atomic_cursor  #
+  ###################
+
+  ###
+  # Create and return cursor instance for this index enabled to load all object properties as atomic.
+  #   See Persistence::Cursor#atomize.
+  #
+  # @return [Persistence::Cursor] New cursor instance.
+  #
+  def atomic_cursor( *args )
+    
+    return cursor( *args ).atomize
+  
+  end
+
+  ##########
+  #  each  #
+  ##########
+
+  ###
+  # Iterate objects in current bucket.
+  #
+  # @yield [object] Current object.
+  #
+  # @yieldparam object Object stored in bucket.
+  #
+  def each( & block )
+    
+    return atomic_cursor.each( & block )
+
+  end
+
+  ##################################################################################################
+      private ######################################################################################
+  ##################################################################################################
+
+  #########################
+  #  create_bucket_index  #
+  #########################
+  
+  ###
+  # Internal helper method for common code to create bucket indexs.
+  #
+  # @param index_name Name of index to create.
+  # 
+  # @param permits_duplicates Whether index should permit duplicates.
+  # 
+  # @param sort_by_proc [Proc] Proc to use for sorting objects.
+  #
+  # @param sort_duplicates_by_proc [Proc] Proc to use for sorting duplicate objects.
+  #
+  # @yield [object] Block to create index keys on object.
+  # @yieldparam object [Object] Object to index.
+  #
+  # @return [Persistence::Port::Bucket::BucketIndex]
+  #
+  def create_bucket_index( index_name, 
+                           permits_duplicates, 
+                           sort_by_proc = nil, 
+                           sort_duplicates_by_proc = nil, 
+                           & indexing_block )
+    
+    if index_instance = @indexes[ index_name ] and 
+       index_instance.permits_duplicates? != permits_duplicates
+      
+      raise 'Index ' << index_name.to_s + ' has already been declared, ' <<
+            'and new duplicates declaration does not match existing declaration.'
+    
+    end
+
+    index_instance = ::Persistence::Port::Bucket::BucketIndex.new( index_name, 
+                                                                          self, 
+                                                                          permits_duplicates,
+                                                                          sort_by_proc, 
+                                                                          sort_duplicates_by_proc,
+                                                                          & indexing_block )
+    
+    @indexes[ index_name ] = index_instance
+    
+    return index_instance
+    
+  end
+
+end