persistence-adapter-flat_file 0.0.1

data/CHANGELOG.rdoc

@@ -0,0 +1,4 @@
+
+## 6/26/2012 ##
+
+Initial release.

data/README.md

@@ -0,0 +1,65 @@
+# Flat File Persistence Adapter #
+
+http://rubygems.org/gems/persistence-adapter-flat_file
+
+# Summary #
+
+Adapter to use flat files as storage port for <a href="https://rubygems.org/gems/persistence">Persistence</a> (<a href="https://github.com/RidiculousPower/persistence">on GitHub</a>).
+
+# Description #
+
+Implements necessary methods to run Persistence on top of the file system without a database.
+
+# Install #
+
+* sudo gem install persistence-adapter-flat_file
+
+# Usage #
+
+The FlatFile adapter is an abstract implementation. Using it requires specifying serialization methods. This permits the creation of concrete adapter implementations that are highly configurable.
+
+At this point, two versions exist:
+
+* FlatFile::Marshal
+* FlatFile::YAML
+
+To use Marshal:
+
+```ruby
+flat_file_adapter = ::Persistence::Adapter::FlatFile::Marshal.new
+
+Persistence.enable_port( :flat_file_marshal_port, flat_file_adapter )
+```
+
+To use YAML:
+
+```ruby
+flat_file_adapter = ::Persistence::Adapter::FlatFile::YAML.new
+
+Persistence.enable_port( :flat_file_yaml_port, flat_file_adapter )
+```
+
+# License #
+
+  (The MIT License)
+
+  Copyright (c) 2012, Asher, Ridiculous Power
+
+  Permission is hereby granted, free of charge, to any person obtaining
+  a copy of this software and associated documentation files (the
+  'Software'), to deal in the Software without restriction, including
+  without limitation the rights to use, copy, modify, merge, publish,
+  distribute, sublicense, and/or sell copies of the Software, and to
+  permit persons to whom the Software is furnished to do so, subject to
+  the following conditions:
+
+  The above copyright notice and this permission notice shall be
+  included in all copies or substantial portions of the Software.
+
+  THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
+  EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+  MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+  IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+  CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+  TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+  SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/lib/persistence/adapter/flat_file.rb

@@ -0,0 +1,17 @@
+
+require 'base64'
+
+#require 'persistence'
+require_relative '../../../../persistence/lib/persistence.rb'
+
+# namespaces that have to be declared ahead of time for proper load order
+require_relative './namespaces'
+
+# source file requires
+require_relative './requires.rb'
+
+class ::Persistence::Adapter::FlatFile
+
+  include ::Persistence::Adapter::FlatFile::AdapterInterface
+  
+end

data/lib/persistence/adapter/flat_file/adapter_interface.rb

@@ -0,0 +1,246 @@
+
+module ::Persistence::Adapter::FlatFile::AdapterInterface
+
+  include ::Persistence::Adapter::Abstract::EnableDisable
+  include ::Persistence::Adapter::Abstract::PrimaryKey::IDPropertyString
+
+  include ::Persistence::Adapter::FlatFile::PathHelpers
+  include ::Persistence::Adapter::FlatFile::Serialization
+
+  Delimiter = '.'
+
+  attr_accessor :parent_bucket
+  
+  ################
+  #  initialize  #
+  ################
+
+  def initialize( home_directory )
+    
+    super( home_directory )
+
+    @buckets = { }
+
+    # make sure we have a sequence
+    unless File.exists?( file__global_id_sequence )
+      create_or_update_value_serialize_and_write( file__global_id_sequence, -1 )
+    end
+    
+  end
+  
+  ###################
+  #  adapter_class  #
+  ###################
+  
+  def adapter_class
+    
+    return self.class
+    
+  end
+
+  ########################
+  #  persistence_bucket  #
+  ########################
+
+  def persistence_bucket( bucket_name )
+    
+    bucket_instance = nil
+
+    unless bucket_instance = @buckets[ bucket_name ]
+      bucket_instance = ::Persistence::Adapter::FlatFile::Bucket.new( self, bucket_name )
+      @buckets[ bucket_name ] = bucket_instance
+    end
+
+    return bucket_instance
+
+  end
+
+  ###################################
+  #  get_bucket_name_for_object_id  #
+  ###################################
+
+  def get_bucket_name_for_object_id( global_id )
+    
+    file__bucket = file__bucket_name_for_id( global_id )
+    
+    return open_read_unserialize_and_close( file__bucket )
+
+  end
+
+  #############################
+  #  get_class_for_object_id  #
+  #############################
+
+  def get_class_for_object_id( global_id )
+    
+    file__class = file__class_for_id( global_id )
+    
+    return open_read_unserialize_and_close( file__class )
+
+  end
+
+  #################################
+  #  delete_bucket_for_object_id  #
+  #################################
+
+  def delete_bucket_for_object_id( global_id )
+
+    file__bucket = file__bucket_name_for_id( global_id )
+    
+    File.delete( file__bucket )
+    
+  end
+
+  ################################
+  #  delete_class_for_object_id  #
+  ################################
+
+  def delete_class_for_object_id( global_id )
+
+    file__class = file__class_for_id( global_id )
+
+    File.delete( file__class )
+  
+  end
+
+  ##########################################
+  #  ensure_object_has_globally_unique_id  #
+  ##########################################
+  
+  def ensure_object_has_globally_unique_id( object )
+
+    unless global_id = object.persistence_id
+              
+      # iterate the sequence by 1 and use the ID
+      object.persistence_id = global_id = iterate_id_sequence
+      
+      # store bucket name for ID
+      store_bucket_name_for_id( object.persistence_bucket.name, global_id )
+
+      # store class for ID
+      store_class_for_id( object.class, global_id )
+
+    end    
+
+    return global_id
+
+  end
+
+  ##################################################################################################
+      private ######################################################################################
+  ##################################################################################################
+
+  #########################
+  #  iterate_id_sequence  #
+  #########################
+  
+  def iterate_id_sequence
+    
+    new_object_id = nil
+
+    open_read_unserialize_perform_action_serialize_write_and_close( file__global_id_sequence ) do |last_persistence_id|
+      
+      # iterate for persistence ID - "last_persistence_id" is the last ID used
+      last_persistence_id = last_persistence_id + 1
+      
+      # assign to object
+      new_object_id = last_persistence_id
+      
+    end
+    
+    return new_object_id
+    
+  end
+
+  ##############################
+  #  store_bucket_name_for_id  #
+  ##############################
+  
+  def store_bucket_name_for_id( bucket_name, global_id )
+
+    file__bucket_name = file__bucket_name_for_id( global_id )
+    
+    create_or_update_value_serialize_and_write( file__bucket_name, bucket_name )
+        
+  end
+  
+  ########################
+  #  store_class_for_id  #
+  ########################
+  
+  def store_class_for_id( klass, global_id )
+
+    file__class = file__class_for_id( global_id )
+    
+    serialize_as_class = self.class::StringifyClassnames ? klass.to_s : klass
+
+    create_or_update_value_serialize_and_write( file__class, serialize_as_class )
+    
+  end
+
+  ###################################
+  #  directory__bucket_name_for_id  #
+  ###################################
+  
+  def directory__bucket_name_for_id
+
+    directory__bucket_name_for_id = File.join( home_directory, 'bucket_name_for_id' )
+                                               
+    ensure_directory_path_exists( directory__bucket_name_for_id )
+
+    return directory__bucket_name_for_id
+
+  end
+
+  #############################
+  #  directory__class_for_id  #
+  #############################
+  
+  def directory__class_for_id
+
+    directory__class_for_id = File.join( home_directory, 'class_for_id' )
+                                         
+    ensure_directory_path_exists( directory__class_for_id )
+
+    return directory__class_for_id
+
+  end
+
+  ##############################
+  #  file__global_id_sequence  #
+  ##############################
+  
+  # Global ID Sequence:      <home_directory>/global_id_sequence.ruby_serialize.txt
+  def file__global_id_sequence  
+
+    return File.join( home_directory,
+                      'global_id_sequence' + self.class::SerializationExtension )
+
+  end
+
+  ##############################
+  #  file__bucket_name_for_id  #
+  ##############################
+  
+  # Bucket/key/class:       <home_directory>/bucket_class/id.ruby_serialize.txt
+  def file__bucket_name_for_id( global_id )
+
+    return File.join( directory__bucket_name_for_id,
+                      global_id.to_s + self.class::SerializationExtension )
+
+  end
+
+  ########################
+  #  file__class_for_id  #
+  ########################
+  
+  # Bucket/key/class:       <home_directory>/bucket_class/id.ruby_serialize.txt
+  def file__class_for_id( global_id )
+
+    return File.join( directory__class_for_id,
+                      global_id.to_s + self.class::SerializationExtension )
+
+  end
+
+end
+

data/lib/persistence/adapter/flat_file/bucket.rb

@@ -0,0 +1,6 @@
+
+class ::Persistence::Adapter::FlatFile::Bucket
+  
+  include ::Persistence::Adapter::FlatFile::Bucket::BucketInterface
+  
+end

data/lib/persistence/adapter/flat_file/bucket/bucket_interface.rb

@@ -0,0 +1,374 @@
+
+module ::Persistence::Adapter::FlatFile::Bucket::BucketInterface
+
+  include ::Persistence::Adapter::Abstract::PrimaryKey::Simple
+  
+  include ::Persistence::Adapter::FlatFile::PathHelpers
+  include ::Persistence::Adapter::FlatFile::Serialization
+
+  attr_accessor :name, :parent_adapter
+
+  ################
+  #  initialize  #
+  ################
+
+  def initialize( parent_adapter, bucket_name )
+    
+    @parent_adapter = parent_adapter
+    @name = bucket_name
+
+    # storage for index objects
+    @indexes = { }
+    
+  end
+
+  ###################
+  #  adapter_class  #
+  ###################
+  
+  def adapter_class
+    
+    return @parent_adapter.class
+    
+  end
+
+  ############
+  #  cursor  #
+  ############
+
+  def cursor
+    
+    return ::Persistence::Adapter::FlatFile::Cursor.new( self, nil )
+
+  end
+
+  ###########
+  #  count  #
+  ###########
+  
+  def count
+    
+    glob_list = Dir.glob( File.join( directory__ids_in_bucket, '*' ) )
+    
+    return glob_list.count
+    
+  end
+
+  #################
+  #  put_object!  #
+  #################
+
+  # must be recoverable by information in the object
+  # we currently use class and persistence key
+  def put_object!( object )
+    
+    @parent_adapter.ensure_object_has_globally_unique_id( object )
+    
+    # write ID to bucket's contents
+    file__ids_in_bucket = file__ids_in_bucket( object.persistence_id )
+    create_or_update_value_serialize_and_write( file__ids_in_bucket, object.persistence_id )
+    
+    object_persistence_hash = object.persistence_hash_to_port
+
+    # iterate flat properties:
+    # * remove delete cascades for this attribute
+    object_persistence_hash.each do |this_attribute, this_attribute_value|
+
+      file__attribute = file__attributes( object.persistence_id, this_attribute )
+
+      create_or_update_value_serialize_and_write( file__attribute, this_attribute_value )
+
+    end
+
+    return object.persistence_id
+
+  end
+
+  ################
+  #  get_object  #
+  ################
+
+  def get_object( global_id )
+
+    persistence_hash_from_port = { }
+
+    # iterate directory of flat objects and unload into hash
+    ::Dir[ ::File.join( directory__attributes( global_id ), '*' ) ].each do |this_file|
+
+      # unserialize contents of file at path for flat attribute value
+      this_attribute = attribute_name_from_file_path( this_file )
+      this_attribute = this_attribute.to_sym if this_attribute
+      this_value = open_read_unserialize_and_close( this_file )
+
+      persistence_hash_from_port[ this_attribute ] = this_value
+
+    end
+    
+    return persistence_hash_from_port.empty? ? nil : persistence_hash_from_port
+
+  end
+  
+  ####################
+  #  delete_object!  #
+  ####################
+
+  def delete_object!( global_id )
+
+    # delete flat properties
+    ::Dir[ ::File.join( directory__attributes( global_id ), '*' ) ].each do |this_file|
+
+      ::File.delete( this_file )
+
+    end
+
+    file__ids_in_bucket = file__ids_in_bucket( global_id )
+    ::File.delete( file__ids_in_bucket )
+
+    @parent_adapter.delete_bucket_for_object_id( global_id )      
+    @parent_adapter.delete_class_for_object_id( global_id )      
+
+    return self
+
+  end
+
+  ####################
+  #  put_attribute!  #
+  ####################
+
+  def put_attribute!( global_id, attribute_name, value )
+    
+    file__attribute = file__attributes( global_id, attribute_name )
+    
+    create_or_update_value_serialize_and_write( file__attribute, value )      
+    
+    return self
+
+  end
+
+  ###################
+  #  get_attribute  #
+  ###################
+
+  def get_attribute( global_id, attribute_name )
+    
+    file__attribute = file__attributes( global_id, attribute_name )
+    
+    return open_read_unserialize_and_close( file__attribute )
+
+  end
+
+  #######################
+  #  delete_attribute!  #
+  #######################
+
+  def delete_attribute!( global_id, attribute_name )
+
+    file__attribute = file__attributes( global_id, attribute_name )
+
+    # delete this attribute
+    ::File.delete( file__attribute )
+
+  end
+
+  ##################
+  #  create_index  #
+  ##################
+  
+  def create_index( index_name, permits_duplicates )
+    
+    unless ( permits_duplicates_value = permits_duplicates?( index_name ) ).nil?
+      
+      if ! permits_duplicates_value != ! permits_duplicates
+        raise 'Index on :' + index_name.to_s + ' already exists and ' + 
+              ( permits_duplicates ? 'does not permit' : 'permits' ) + ' duplicates, which conflicts.'
+      end
+
+    else
+
+      file__permits_duplicates = file__index_permits_duplicates( index_name )
+
+      create_or_update_value_serialize_and_write( file__permits_duplicates, 
+                                                  permits_duplicates )
+
+    end
+
+    # create/instantiate the index
+    index_instance = ::Persistence::Adapter::FlatFile::Bucket::Index.new( index_name,
+                                                                                    self,
+                                                                                    permits_duplicates )
+
+    # store index instance
+    @indexes[ index_name ] = index_instance
+
+    return index_instance
+
+  end
+
+  ###########
+  #  index  #
+  ###########
+  
+  def index( index_name )
+
+    return @indexes[ index_name ]
+
+  end
+
+  ################
+  #  has_index?  #
+  ################
+
+  def has_index?( index_name )
+    
+    return @indexes.has_key?( index_name )
+
+  end
+
+  #########################
+  #  permits_duplicates?  #
+  #########################
+
+  def permits_duplicates?( index_name )
+    
+    file__permits_duplicates = file__index_permits_duplicates( index_name )
+    
+    return open_read_unserialize_and_close( file__permits_duplicates )
+
+  end
+
+  ##################
+  #  delete_index  #
+  ##################
+  
+  def delete_index( index_name )
+
+    index_instance = @indexes.delete( index_name )
+    
+    index_instance.delete
+    
+    # delete permits_duplicates
+    File.delete( file__index_permits_duplicates( index_name ) )
+
+    return self
+
+  end
+
+  ##################################################################################################
+      private ######################################################################################
+  ##################################################################################################
+
+  #######################
+  #  directory__object  #
+  #######################
+
+  def directory__object( global_id )
+
+    directory__object = File.join( @parent_adapter.home_directory,
+                                   'objects',
+                                   @name.to_s,
+                                   global_id.to_s )
+                                   
+    ensure_directory_path_exists( directory__object )
+
+    return directory__object
+
+  end
+
+  ###########################
+  #  directory__attributes  #
+  ###########################
+  
+  # Flat Property Directory:         <home_directory>/objects/bucket/id/flat_properties
+  def directory__attributes( global_id )
+
+    directory__attributes = File.join( directory__object( global_id ),
+                                       'attributes' )
+
+    ensure_directory_path_exists( directory__attributes )
+
+    return directory__attributes
+
+  end
+
+  #########################################
+  #  directory__index_permits_duplicates  #
+  #########################################
+  
+  def directory__index_permits_duplicates
+
+    directory__index_permits_duplicates = File.join( @parent_adapter.home_directory, 'indexes' )
+
+    ensure_directory_path_exists( directory__index_permits_duplicates )
+
+    return directory__index_permits_duplicates
+
+  end
+  
+  ##############################
+  #  directory__ids_in_bucket  #
+  ##############################
+  
+  # Global IDs:              <home_directory>/global_ids/bucket/
+  def directory__ids_in_bucket
+    
+    directory__ids_in_bucket = File.join( @parent_adapter.home_directory,
+                                          'global_ids',
+                                          @name.to_s )
+    
+    ensure_directory_path_exists( directory__ids_in_bucket )
+    
+    return directory__ids_in_bucket
+
+  end
+  
+  #########################
+  #  file__ids_in_bucket  #
+  #########################
+  
+  def file__ids_in_bucket( global_id )
+    
+    return File.join( directory__ids_in_bucket, 
+                      global_id.to_s + @parent_adapter.class::SerializationExtension )
+    
+  end
+  
+  ######################
+  #  file__attributes  #
+  ######################
+  
+  # Flat Attributes:         <home_directory>/objects/bucket/id/flat_properties/attribute.ruby_serialize.txt
+  def file__attributes( global_id, attribute_name )
+
+    return File.join( directory__attributes( global_id ),
+                      attribute_name.to_s + @parent_adapter.class::SerializationExtension )
+
+  end
+
+  ####################################
+  #  file__index_permits_duplicates  #
+  ####################################
+  
+  # Global ID:               <home_directory>/indexes/bucket_name__index_name__permits_duplicates.ruby_serialize.txt
+  def file__index_permits_duplicates( index_name )
+
+    key = key.to_s if key.is_a?( Class )
+
+    return File.join( directory__index_permits_duplicates,
+                      @name.to_s + '__' + index_name.to_s + '__permits_duplicates' + @parent_adapter.class::SerializationExtension )
+
+  end
+
+  ###################################
+  #  attribute_name_from_file_path  #
+  ###################################
+
+  def attribute_name_from_file_path( file_path )
+
+    # get basename instead of path
+    file_basename = File.basename( file_path )
+
+    return file_basename.slice( 0, file_basename.length - @parent_adapter.class::SerializationExtension.length )
+
+  end
+
+end