persistence-adapter-kyotocabinet 0.0.1

data/CHANGELOG.rdoc

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

data/README.md

@@ -0,0 +1,65 @@
+# KyotoCabinet Persistence Adapter #
+
+http://rubygems.org/gems/persistence-adapter-kyotocabinet
+
+# Summary #
+
+Adapter to use <a href="http://fallabs.com/kyotocabinet/">KyotoCabinet</a> 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 Kyoto Cabinet.
+
+# Install #
+
+* sudo gem install persistence-adapter-kyotocabinet
+
+# Usage #
+
+The KyotoCabinet 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:
+
+* KyotoCabinet::Marshal
+* KyotoCabinet::YAML
+
+To use Marshal:
+
+```ruby
+kyotocabinet_marshal_adapter = ::Persistence::Adapter::KyotoCabinet::Marshal.new
+
+Persistence.enable_port( :kyotocabinet_marshal_port, kyotocabinet_marshal_adapter )
+```
+
+To use YAML:
+
+```ruby
+kyotocabinet_yaml_adapter = ::Persistence::Adapter::KyotoCabinet::YAML.new
+
+Persistence.enable_port( :kyotocabinet_yaml_port, kyotocabinet_yaml_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/kyotocabinet.rb

@@ -0,0 +1,18 @@
+
+require 'persistence'
+
+require 'kyotocabinet'
+
+require 'yaml'
+
+# 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::KyotoCabinet
+  
+  include ::Persistence::Adapter::KyotoCabinet::AdapterInterface
+
+end

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

@@ -0,0 +1,196 @@
+
+module ::Persistence::Adapter::KyotoCabinet::AdapterInterface
+
+  include ::Persistence::Adapter::Abstract::EnableDisable
+
+  include ::Persistence::Adapter::KyotoCabinet::DatabaseSupport
+
+  DatabaseFlags = ::KyotoCabinet::DB::OWRITER | ::KyotoCabinet::DB::OCREATE
+
+  Delimiter = '.'  
+
+  ################
+  #  initialize  #
+  ################
+
+  def initialize( home_directory )
+  
+    super( home_directory )
+
+    @buckets = { }
+
+  end
+
+  ############
+  #  enable  #
+  ############
+
+  def enable
+
+    super
+
+    # holds global ID sequence
+    @database__id_sequence = ::KyotoCabinet::DB.new
+    @database__id_sequence.open( file__id_sequence_database, DatabaseFlags )
+
+    # holds global ID => primary bucket
+    @database__primary_bucket_for_id = ::KyotoCabinet::DB.new
+    @database__primary_bucket_for_id.open( file__primary_bucket_for_id_database, DatabaseFlags )
+
+    return self
+
+  end
+
+  #############
+  #  disable  #
+  #############
+
+  def disable
+
+    super
+
+    @database__id_sequence.close
+    @database__primary_bucket_for_id.close
+    
+    return self
+
+  end
+
+  ########################
+  #  persistence_bucket  #
+  ########################
+
+  def persistence_bucket( bucket_name )
+    
+    bucket_instance = nil
+
+    unless bucket_instance = @buckets[ bucket_name ]
+      bucket_instance = ::Persistence::Adapter::KyotoCabinet::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 )
+
+    bucket_name = @database__primary_bucket_for_id.get( global_id )
+    
+    bucket_name = bucket_name.to_sym if bucket_name
+      
+    return bucket_name
+  
+  end
+
+  #############################
+  #  get_class_for_object_id  #
+  #############################
+
+  def get_class_for_object_id( global_id )
+
+    bucket_name = get_bucket_name_for_object_id( global_id )
+
+    bucket_instance = persistence_bucket( bucket_name )
+
+    return bucket_instance.get_class( global_id )
+  
+  end
+
+  #################################
+  #  delete_bucket_for_object_id  #
+  #################################
+
+  def delete_bucket_for_object_id( global_id )
+
+    return @database__primary_bucket_for_id.remove( global_id )
+  
+  end
+
+  ################################
+  #  delete_class_for_object_id  #
+  ################################
+
+  def delete_class_for_object_id( global_id )
+
+    bucket_name = get_bucket_name_for_object_id( global_id )
+
+    bucket_instance = persistence_bucket( bucket_name )
+
+    return bucket_instance.delete_class( global_id )
+  
+  end
+
+  ##########################################
+  #  ensure_object_has_globally_unique_id  #
+  ##########################################
+
+  def ensure_object_has_globally_unique_id( object )
+  
+    unless object.persistence_id
+
+      # we only store one sequence so we don't need a key; increment it by 1
+      global_id = @database__id_sequence.increment( :sequence, 1, -1 )
+
+      # and write it to our global object database with a bucket/key struct as data
+      @database__primary_bucket_for_id.set( global_id, object.persistence_bucket.name )
+
+      object.persistence_id = global_id
+      
+    end
+  
+    return self
+  
+  end
+
+  ##################################################################################################
+      private ######################################################################################
+  ##################################################################################################
+
+  ################################
+  #  file__id_sequence_database  #
+  ################################
+
+  def file__id_sequence_database
+
+    return File.join( home_directory,
+                      'IDSequence' + extension__id_sequence_database )
+
+  end
+
+  ##########################################
+  #  file__primary_bucket_for_id_database  #
+  ##########################################
+
+  def file__primary_bucket_for_id_database
+
+    return File.join( home_directory,
+                      'PrimaryBucketForID' + extension__primary_bucket_for_id_database )
+                      
+  end
+
+  #####################################
+  #  extension__id_sequence_database  #
+  #####################################
+
+  def extension__id_sequence_database
+    
+    return extension__database( :tree )
+
+  end
+
+  ###############################################
+  #  extension__primary_bucket_for_id_database  #
+  ###############################################
+  
+  def extension__primary_bucket_for_id_database
+    
+    return extension__database( :hash )
+
+  end
+
+end

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

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

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

@@ -0,0 +1,435 @@
+
+module ::Persistence::Adapter::KyotoCabinet::Bucket::BucketInterface
+
+  include ::Persistence::Adapter::Abstract::PrimaryKey::IDPropertyString
+
+  include ::Persistence::Adapter::KyotoCabinet::DatabaseSupport
+
+  attr_accessor :parent_adapter, :name
+
+  # we're always opening as writers and creating the files if they don't exist
+
+  ################
+  #  initialize  #
+  ################
+  
+  def initialize( parent_adapter, bucket_name )
+    
+    @parent_adapter = parent_adapter
+    @name = bucket_name
+
+    # storage for index objects
+    @indexes = { }
+
+    database_flags = @parent_adapter.class::DatabaseFlags
+
+    # bucket database corresponding to self - holds properties
+    # 
+    # objectID             => klass
+    # objectID.property_A  => property_value_A
+    # objectID.property_B  => property_value_B
+    # 
+    @database__bucket = ::KyotoCabinet::DB.new
+    @database__bucket.open( file__bucket_database( bucket_name ), database_flags )
+
+    # holds IDs that are presently in this bucket so we can iterate objects normally
+    # 
+    # objectID => objectID
+    #
+    @database__ids_in_bucket = ::KyotoCabinet::DB.new
+    @database__ids_in_bucket.open( file__ids_in_bucket_database( bucket_name ), database_flags )
+    
+    # holds whether each index permits duplicates
+    @database__index_permits_duplicates = ::KyotoCabinet::DB.new
+    @database__index_permits_duplicates.open( file__index_permits_duplicates_database( bucket_name ), database_flags )
+
+  end
+
+  ###########
+  #  count  #
+  ###########
+  
+  def count
+    
+    return @database__ids_in_bucket.count
+    
+  end
+  
+  ###########
+  #  close  #
+  ###########
+  
+  def close
+
+    close_indexes
+
+    @database__index_permits_duplicates.close
+
+    super
+
+  end
+
+  ###################
+  #  close_indexes  #
+  ###################
+  
+  def close_indexes
+
+    @indexes.each do |this_index_name, this_index_instance|
+      this_index_instance.close
+    end
+
+  end
+
+  ############
+  #  cursor  #
+  ############
+
+  def cursor
+    return ::Persistence::Adapter::KyotoCabinet::Cursor.new( self, nil, @database__ids_in_bucket.cursor )
+  end
+
+  #########################
+  #  permits_duplicates?  #
+  #########################
+  
+  def permits_duplicates?( index )
+
+    permits_duplicates = @database__index_permits_duplicates.get( index )
+    permits_duplicates = ( permits_duplicates == 1 ? true : false ) unless permits_duplicates.nil?
+
+    return permits_duplicates
+
+  end
+
+  #################
+  #  put_object!  #
+  #################
+  
+  def put_object!( object )
+    
+    @parent_adapter.ensure_object_has_globally_unique_id( object )
+    
+    # insert object class definition: ID => klass
+    # class definition is used as header/placeholder for object properties
+    @database__bucket.set( object.persistence_id, object.class.to_s )
+
+    # insert ID to cursor index
+    @database__ids_in_bucket.set( object.persistence_id, object.persistence_id )
+
+    # insert properties
+    object.persistence_hash_to_port.each do |primary_key, attribute_value|
+      put_attribute!( object.persistence_id, primary_key, attribute_value )
+    end
+    
+    return object.persistence_id
+    
+  end
+  
+  ################
+  #  get_object  #
+  ################
+  
+  def get_object( global_id )
+
+    object_persistence_hash = { }
+
+    # create cursor and set to position of ID
+    @database__bucket.cursor_process do |object_cursor|
+
+      if object_cursor.jump( global_id )
+
+        # Iterate until the key no longer begins with ID
+        # First record (ID only, no attribute) points to klass, so we have to move forward to start.
+        while this_attribute = next_attribute_of_this_object( object_cursor, global_id )
+
+          serialized_value = object_cursor.get_value
+
+          value = @parent_adapter.class::SerializationClass.__send__(  @parent_adapter.class::UnserializationMethod, serialized_value )
+                    
+          object_persistence_hash[ this_attribute ] = value
+
+        end
+      
+      end
+
+    end
+
+    return object_persistence_hash.empty? ? nil : object_persistence_hash
+    
+  end
+  
+  ####################
+  #  delete_object!  #
+  ####################
+  
+  def delete_object!( global_id )
+
+    # delete from IDs in bucket database
+    @database__ids_in_bucket.remove( global_id )
+
+    # create cursor and set to position of ID
+    @database__bucket.cursor_process do |object_cursor|
+
+      if object_cursor.jump( global_id )
+        
+        object_cursor.remove
+        
+        # Iterate until the key no longer begins with ID
+        # First record (ID only, no attribute) points to klass, so we have to move forward to start.
+        while this_attribute = next_attribute_of_this_object( object_cursor, global_id )
+
+          this_attribute_value = object_cursor.get_value
+
+          object_cursor.remove
+        
+        end
+      
+      end
+
+    end
+  
+  end
+  
+  ####################
+  #  put_attribute!  #
+  ####################
+  
+  def put_attribute!( global_id, attribute_name, value )
+    
+    serialization_class = @parent_adapter.class::SerializationClass
+    
+    serialized_value  = serialization_class.__send__( @parent_adapter.class::SerializationMethod, value )
+
+    @database__bucket.set( attribute_name, serialized_value )
+
+  end
+
+  ###################
+  #  get_attribute  #
+  ###################
+  
+  def get_attribute( global_id, attribute_name )
+
+    value = nil
+
+    if serialized_value = @database__bucket.get( attribute_name )
+
+      serialization_class = @parent_adapter.class::SerializationClass
+
+      value = serialization_class.__send__( @parent_adapter.class::UnserializationMethod, serialized_value )
+
+    end
+
+    return value
+
+  end
+  
+  #######################
+  #  delete_attribute!  #
+  #######################
+  
+  def delete_attribute!( global_id, attribute_name )
+
+    # delete primary info on attribute
+    @database__bucket.remove( attribute_name )
+
+  end
+
+  ##################
+  #  create_index  #
+  ##################
+  
+  def create_index( index_name, permits_duplicates )
+
+    # make sure index doesn't already exist with conflict duplicate permission
+    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
+
+      @database__index_permits_duplicates.set( index_name, permits_duplicates )
+
+    end
+
+    # create/instantiate the index
+    index_instance = self.class::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
+
+  ##################
+  #  delete_index  #
+  ##################
+  
+  def delete_index( index_name )
+
+    # remove permits_duplicates configuration
+    @database__index_permits_duplicates.remove( index_name )
+
+    index_instance = @indexes.delete( index_name )
+    
+    index_instance.delete
+    
+  end
+  
+  ################
+  #  has_index?  #
+  ################
+  
+  def has_index?( index_name )
+    
+    return @indexes.has_key?( index_name )
+
+  end
+
+  ###############
+  #  get_class  #
+  ###############
+
+  def get_class( global_id )
+    
+    klass = nil
+    
+    if klass_path_string = @database__bucket.get( global_id )
+    
+      klass_path_parts = klass_path_string.split( '::' )
+
+      klass = klass_path_parts.inject( Object ) do |object_container_namespace, next_path_part|
+        object_container_namespace.const_get( next_path_part )
+      end
+    
+    end
+    
+    return klass
+    
+  end
+
+  ###############
+  #  get_class  #
+  ###############
+
+  def delete_class( global_id )
+    
+    @database__bucket.remove( global_id )
+
+  end
+  
+  ##################################################################################################
+      private ######################################################################################
+  ##################################################################################################
+
+  ###################################
+  #  next_attribute_of_this_object  #
+  ###################################
+
+  def next_attribute_of_this_object( object_cursor, global_id )
+    
+    attribute_name = nil
+
+    if object_cursor.step and primary_key = object_cursor.get_key
+
+      this_global_id, this_attribute = primary_key.split( @parent_adapter.class::Delimiter )
+    
+      if this_global_id.to_i == global_id
+        attribute_name = this_attribute.to_sym
+      end
+    
+    end
+    
+    return attribute_name
+
+  end
+
+  ###########################
+  #  file__bucket_database  #
+  ###########################
+
+  def file__bucket_database( bucket_name )
+    
+    return File.join( @parent_adapter.home_directory,
+                      bucket_name.to_s + extension__bucket_database )
+
+  end
+
+  ##################################
+  #  file__ids_in_bucket_database  #
+  ##################################
+
+  def file__ids_in_bucket_database( bucket_name )
+
+    return File.join( @parent_adapter.home_directory,
+                      bucket_name.to_s + '__ids_in_bucket__' + extension__ids_in_bucket_database )
+
+  end  
+
+  #############################################
+  #  file__index_permits_duplicates_database  #
+  #############################################
+
+  def file__index_permits_duplicates_database( bucket_name )
+    
+    index_file_name = bucket_name.to_s + '__index_permits_duplicates__' + extension__index_permits_duplicates_database
+    
+    return File.join( @parent_adapter.home_directory, index_file_name )
+
+  end
+
+  ################################
+  #  extension__bucket_database  #
+  ################################
+
+  def extension__bucket_database
+    
+    return extension__database( :tree )
+
+  end
+
+  ###################################################
+  #  extension__indexes_permit_duplicates_database  #
+  ###################################################
+
+  def extension__indexes_permit_duplicates_database
+    
+    return extension__database( :hash )
+
+  end
+
+  #######################################
+  #  extension__ids_in_bucket_database  #
+  #######################################
+
+  def extension__ids_in_bucket_database
+    
+    return extension__database( :hash )
+
+  end
+
+  ##################################################
+  #  extension__index_permits_duplicates_database  #
+  ##################################################
+  
+  def extension__index_permits_duplicates_database
+
+    return extension__database( :hash )
+
+  end
+    
+end