persistence 0.0.1.alpha → 0.0.1

data/lib/persistence/port/controller.rb

@@ -0,0 +1,263 @@
+
+###
+# Controller methods for Persistence singleton.
+#
+module ::Persistence::Port::Controller
+
+  ###################
+  #  self.extended  #
+  ###################
+
+  ###
+  # Initializes singleton when extended.
+  #
+  def self.extended( instance )
+    
+    instance.module_eval do
+      @ports = { }
+      @pending_buckets = { }
+    end
+    
+  end
+  
+  ###########
+  #  ports  #
+  ###########
+
+  ###
+  # Tracks persistence ports.
+  #
+  # @return [Hash{Symbol,String=>Persistence::Port}] Hash of ports.
+  def ports
+    
+    return @ports
+
+  end
+
+  #####################
+  #  pending_buckets  #
+  #####################
+  
+  ###
+  # @private
+  #
+  # Tracks pending persistence buckets created before a port is enabled.
+  #
+  # @return [Hash{Symbol,String=>Persistence::Port::Bucket}]
+  #
+  def pending_buckets
+
+    return @pending_buckets
+
+  end
+  
+  #################
+  #  enable_port  #
+  #################
+
+  ###
+  # Enable a port. If no port is already enabled, port will be set as current port.
+  #
+  # @param port_name Name of port to create or enable.
+  #
+  # @param adapter_instance Adapter instance to use to create port. If not provided attempt will be made to
+  #   enable existing port by name.
+  #
+  # @return [Persistence::Port] Port instance.
+  #
+  def enable_port( port_name, adapter_instance = nil )
+
+    port_instance = nil
+
+    if adapter_instance
+
+      port_instance = ::Persistence::Port.new( port_name, adapter_instance )
+      
+      prior_port_by_name = @ports[ port_name.to_sym ]
+      
+      @ports[ port_name.to_sym ] = port_instance
+
+      port_instance.enable
+      
+      if prior_port_by_name
+        buckets_around_from_prior_port = prior_port_by_name.buckets
+        buckets_around_from_prior_port.each do |this_bucket_name, this_bucket|
+          port_instance.initialize_persistence_bucket_from_instance( this_bucket )
+        end
+      end
+      
+    else
+
+      unless port_instance = port( port_name )
+        raise 'Port must first be enabled with adapter instance before it can be re-enabled by name.'
+      end
+
+      port_instance.enable
+
+    end
+
+    unless current_port
+      set_current_port( port_instance )
+    end
+    
+    create_pending_buckets( port_instance )
+
+    return port_instance
+
+  end
+
+  ##################
+  #  disable_port  #
+  ##################
+
+  ###
+  # Disable port.
+  #
+  # @param port_name Port name to disable.
+  #
+  # @return self
+  #
+  def disable_port( port_name )
+    
+    if port_instance = port( port_name )
+    
+      if current_port == port_instance
+        set_current_port( nil )
+      end
+    
+      port_instance.disable
+
+    end
+    
+    return self
+
+  end
+
+  ##################
+  #  current_port  #
+  ##################
+  
+  ###
+  # Get current port
+  # 
+  # @return [Persistence::Port,nil] Current port.
+  #
+  def current_port
+    return @current_port
+  end
+
+  ######################
+  #  set_current_port  #
+  ######################
+  
+  ###
+  # Set current port
+  #
+  # @param persistence_port_or_name Port instance or name to set current port to.
+  #
+  # @return self
+  #
+  def set_current_port( persistence_port_or_name )
+    @current_port = port_for_name_or_port( persistence_port_or_name )
+    return self
+  end
+
+  ##########
+  #  port  #
+  ##########
+  
+  ###
+  # Get port for name.
+  #
+  # @param port_name Port name.
+  #
+  # @return [Persistence::Port] Port instance.
+  #
+  def port( port_name )
+    return @ports[ port_name.to_sym ]
+  end
+
+  ###########################
+  #  port_for_name_or_port  #
+  ###########################
+  
+  ###
+  # Get port for name.
+  #
+  # @param persistence_port_or_name Port name or instance.
+  # @param ensure_exists Whether exception should be thrown is port does not exist.
+  #
+  # @return [Persistence::Port] Port instance.
+  #
+  def port_for_name_or_port( persistence_port_or_name, ensure_exists = false )
+    
+    port_instance = nil
+    
+    case persistence_port_or_name
+      when ::Symbol, ::String
+        port_instance = port( persistence_port_or_name )
+      else
+        port_instance = persistence_port_or_name
+    end
+    
+    unless port_instance
+      if ensure_exists
+        raise ::ArgumentError, 'No port found by name ' << persistence_port_or_name.to_s
+      end
+    end
+    
+    return port_instance
+    
+  end
+
+  ############################
+  #  create_pending_buckets  #
+  ############################
+
+  ###
+  # @private
+  #
+  # Creates pending buckets when port is enabled.
+  # 
+  # @param port Port to create pending buckets with.
+  #
+  # @return self
+  #
+  def create_pending_buckets( port )
+    
+    @pending_buckets.delete_if do |this_class, this_bucket|
+      this_bucket.initialize_for_port( port )
+      true
+    end
+
+    return self
+    
+  end
+
+  ####################
+  #  pending_bucket  #
+  ####################
+  
+  ###
+  # @private
+  #
+  # Create pending bucket to be enabled with port is enabled.
+  #
+  # @param klass Class bucket is being created for.
+  # @param bucket_name Name to use for bucket.
+  #
+  # @return [Persistence::Port::Bucket]
+  #
+  def pending_bucket( klass, bucket_name )
+
+    bucket_instance = nil
+
+    unless bucket_instance = @pending_buckets[ klass ] and bucket_instance.name == bucket_name
+      @pending_buckets[ klass ] = bucket_instance = ::Persistence::Port::Bucket.new( nil, bucket_name )
+    end
+    
+    return bucket_instance
+    
+  end
+
+end

data/lib/persistence/port/port_interface.rb

@@ -0,0 +1,417 @@
+
+###
+# Interface for Port implementation. Provided separately for easy overriding.
+#
+module ::Persistence::Port::PortInterface
+
+  include ::Persistence::Object::Flat::File::FilePersistence
+
+  ################
+  #  initialize  #
+  ################
+
+  ###
+  #
+  # @param port_name Name to use to identify port instance.
+  #
+  # @param adapter_instance Adapter instance for which port instance will be operative.
+  #
+  def initialize( port_name, adapter_instance )
+
+    super() if defined?( super )
+    
+    @buckets = { }
+    
+    @instances = ::UniqueArray.new
+    
+    @name    = port_name
+    @adapter = adapter_instance
+    
+    @enabled = false
+    
+  end
+  
+  #############
+  #  adapter  #
+  #############
+  
+  ###
+  # Retrieve parallel adapter instance.
+  #
+  # @return [Object] Adapter instance.
+  #
+  def adapter
+    
+    unless @adapter
+      raise 'Persistence port must be enabled first.'
+    end
+    
+    return @adapter
+    
+  end
+
+  ##########
+  #  name  #
+  ##########
+
+  ###
+  # @!attribute [reader] Name of bucket
+  #
+  # @return [Symbol,String] Name.
+  #
+  attr_reader :name
+
+  ############
+  #  enable  #
+  ############
+  
+  ###
+  # Enable port.
+  #
+  # @return self
+  #
+  def enable
+    @enabled = true
+    @adapter.enable
+    @buckets.each do |this_bucket_name, this_bucket|
+      this_bucket.initialize_for_port( self )
+    end
+    return self
+  end
+
+  #############
+  #  disable  #
+  #############
+
+  ###
+  # Disable port.
+  #
+  # @return self
+  #
+  def disable
+
+    @enabled = false
+
+    @instances.delete_if do |this_instance|
+      this_instance.instance_persistence_port = nil
+      true
+    end
+
+    @buckets.each do |this_bucket_name, this_bucket|
+      this_bucket.disable
+    end
+
+    @adapter.disable
+
+    return self
+
+  end
+
+  ##############
+  #  enabled?  #
+  ##############
+
+  ###
+  # Query whether port is enabled.
+  #
+  # @return [true,false] Whether port is enabled.
+  #
+  def enabled?
+    return @enabled
+  end
+
+  ###############
+  #  disabled?  #
+  ###############
+
+  ###
+  # Query whether port is disabled.
+  #
+  # @return [true,false] Whether port is disabled.
+  #
+  def disabled?
+
+    return ! @enabled
+  end
+  
+  #############
+  #  buckets  #
+  #############
+
+  ###
+  # @!attribute [reader] Hash of buckets.
+  #
+  # @return [Hash{Symbol,String=>Persistence::Port::Bucket] Bucket Hash.
+  #
+  attr_reader :buckets
+  
+  #######################
+  #  register_instance  #
+  #######################
+  
+  ###
+  # @private
+  #
+  # Register an instance as using this port. This is used to disable references to port when port is disabled.
+  #
+  def register_instance( instance )
+    
+    @instances.push( instance )
+    
+    return self
+    
+  end
+
+  #################################################
+  #  initialize_persistence_bucket_from_instance  #
+  #################################################
+
+  ###
+  # @private
+  #
+  # Use a bucket instance that has already been created with this port.
+  #
+  def initialize_persistence_bucket_from_instance( bucket_instance )
+
+    @buckets[ bucket_instance.name.to_sym ] = bucket_instance
+
+    bucket_instance.initialize_for_port( self )
+    
+    return bucket_instance
+    
+  end
+  
+  ########################
+  #  persistence_bucket  #
+  ########################
+  
+  ###
+  # Get persistence bucket configured for this port.
+  #
+  # @param bucket_name Name of bucket.
+  #
+  # @return [Persistence::Port::Bucket] Bucket instance.
+  #
+  def persistence_bucket( bucket_name )
+    
+    bucket_instance = nil
+
+    bucket_name = bucket_name.to_sym
+
+    unless bucket_instance = @buckets[ bucket_name ]
+      @buckets[ bucket_name ] = bucket_instance = ::Persistence::Port::Bucket.new( self, bucket_name )
+    end      
+    
+    return bucket_instance
+    
+  end
+
+  ###################################
+  #  get_bucket_name_for_object_id  #
+  ###################################
+  
+  ###
+  # @private
+  #
+  # Use Object persistence ID to retrieve the name of the bucket in which object is currently being stored.
+  #
+  # @param global_id Object persistence ID that owns indexed entries.
+  #
+  # @return [String] Name of bucket.
+  #
+  def get_bucket_name_for_object_id( global_id )
+    
+    return adapter.get_bucket_name_for_object_id( global_id )
+
+  end
+
+  #############################
+  #  get_class_for_object_id  #
+  #############################
+  
+  ###
+  # @private
+  #
+  # Use Object persistence ID to retrieve the class of the object.
+  #
+  # @param global_id Object persistence ID that owns indexed entries.
+  #
+  # @return [String] Name of bucket.
+  #
+  def get_class_for_object_id( global_id )
+
+    return adapter.get_class_for_object_id( global_id )
+
+  end
+
+  #################
+  #  put_object!  #
+  #################
+
+  ###
+  # @private
+  #
+  # Persist object in persistence port. Object configuration will be used to determine where and how.
+  #
+  # @return [Object] Object persistence ID
+  #
+  def put_object!( object )    
+
+    return object.persistence_bucket.put_object!( object )
+
+  end
+
+  ####################
+  #  delete_object!  #
+  ####################
+
+  ###
+  # @private
+  #
+  # Delete object in persistence port.
+  #
+  # @param global_id Object persistence ID.
+  #
+  # @return [String] Name of bucket.
+  #
+  def delete_object!( global_id )
+  
+    persistence_hash_from_port = nil
+    
+    bucket = get_bucket_name_for_object_id( global_id )
+    
+    if bucket
+      persistence_hash_from_port = persistence_bucket( bucket ).delete_object!( global_id )
+    end
+    
+    return persistence_hash_from_port
+    
+  end
+  
+  ################
+  #  get_object  #
+  ################
+
+  ###
+  # @private
+  #
+  # Get object from persistence port.
+  #
+  # @param global_id Object persistence ID.
+  #
+  # @return [Object] Persisted object instance.
+  #
+  def get_object( global_id )
+        
+    object = nil
+        
+    bucket = get_bucket_name_for_object_id( global_id )
+    
+    if bucket
+      object = persistence_bucket( bucket ).get_object( global_id )
+    end
+
+    return object
+    
+  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
+    
+    bucket = get_bucket_name_for_object_id( global_id )
+
+    if bucket
+      flat_object = persistence_bucket( bucket ).get_flat_object( global_id )
+    end
+    
+    return flat_object
+    
+  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 = ::Persistence.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 = ::Persistence.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 = ::Persistence.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 = ::Persistence.persists_file_paths_as_strings?
+    end
+    
+    return persists_file_paths_as_strings
+    
+  end
+
+end