jsl-hashback 0.0.1.2 → 0.0.2.3

data/LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2007 Justin S. Leitgeb
+Copyright (c) 2009 Justin S. Leitgeb
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/README.rdoc

@@ -1,7 +1,89 @@
 = HashBack
 
-Provides a general interface over Moneta which allows namespacing of key values and the requirement of correct
-Moneta backend class.
+HashBack is a simple Object-hash mapping (OHM) system for Ruby.  It allows for serializable classes to be saved, 
+retrieved and deleted from any key-value store supported by {Moneta}[http://github.com/wycats/moneta/tree/master] 
+(a unified interface to key-value systems).
+
+== Quick Start
+
+HashBack is easy to use, so we can jump right in to code using the system.
+
+First, install the gem:
+
+  sudo gem install jsl-hashback
+  
+Then, in your code you'll want to require 'hashback'.  For this example, the object ids that we use will be 
+UUIDs created by the assaf-uuid gem, so we'll include that as well.
+
+  require 'hashback'
+  require 'uuid'
+
+Below we create a simple class that is serializable to HashBack.
+
+  class Elephant
+    HashBack::Resource.setup(self, :uuid, 'Moneta::Memory')
+
+    attr_accessor :uuid, :name
+
+    def initialize(name)
+      @name = name
+      @uuid = UUID.new.generate
+    end
+  end
+
+You can now start using this class to save, fetch and retrieve elephants as follows:
+
+  dumbo = Elephant.new('Dumbo')
+  dumbo.save
+
+To bring Dumbo back as a new elephant:
+
+  new_dumbo = Elephant.fetch(dumbo.uuid)
+
+When you're sick of Dumbo and want to get rid of him:
+
+  new_dumbo.destroy
+
+Note that at this point the data is still available in the instance variables for Dumbo, but the persisted form of him is gone.
+
+== Detailed usage
+
+Generally, HashBack should work with any class that can be serialized.  You can decide which key-value storage system
+to use by passing an appropriate class name to HashBack::Resource.setup.  See the Moneta documentation for available backends.
+
+You can also pass options to HashBack::Resource which are given directly to the moneta backend during initialization as 
+follows:
+
+  require 'hashback'
+  
+  class Foo
+    HashBack::Resource.setup(self, :id, 'Moneta::Memcache', :server => 'localhost:1978')
+  end
+  
+This initializes a class with a backend storage in a Tokyo Tyrant server.  The serialized forms of objects that are 
+stored will be saved with keys like Foo-object_id.  You probably want to use a different id method to customize the id
+that will be used to store these objects.
+
+== Discussion
+
+Key-value databases are rapidly becoming more popular, and they clearly have several use cases that aren't well 
+addressed by existing RDBM systems.  While adoptation of these key-value storage systems has been rapid, there don't 
+seem to be any systems that help to implement common patterns for accessing objects saved in these stores.  Before 
+writing this program, I couldn't find any precedent for a concept of a OHM (Object Hash Mapping) system, so I put 
+together a lightweight implementation with methods for saving and accessing similar to popular ORM systems in Ruby.
+
+== TODO
+
+The following features are not present in the current library, but may be useful:
+
+* A system of callbacks
+* A system for associating objects, perhaps constrained to objects that have a 1 - 1 mapping (since it's not entirely 
+  intuitive what the structures or algorithms would be for mainting integrity with higher levels of mapping between
+  objects). 
+
+== Feedback
+
+Please write the author if you have any questions or feedbacks about this library.
 
 == Author
 

data/hashback.gemspec

@@ -1,6 +1,6 @@
 Gem::Specification.new do |s|
   s.name     = "hashback"
-  s.version  = "0.0.1.2"
+  s.version  = "0.0.2.3"
   s.date     = "2009-05-13"
   s.summary  = "Generic tool for writing namespaced key-value data to a variety of hash-type systems"
   s.email    = "justin@phq.org"
@@ -16,13 +16,25 @@ Gem::Specification.new do |s|
     "README.rdoc",
     "Rakefile",
     "lib/hashback.rb",
-    "lib/hashback/backend.rb"
+    "lib/hashback/backend.rb",
+    "lib/hashback/resource.rb"
   ]
   s.test_files = [
     "spec/hashback/backend_spec.rb",
     "spec/hashback_spec.rb",
     "spec/spec_helper.rb"
   ]
-  s.add_dependency("wycats-moneta", ["> 0.0.0"])
-  s.add_dependency("activesupport", ["> 0.0.0"])
+  
+  s.extra_rdoc_files = [ "README.rdoc" ]
+  
+  s.rdoc_options += [
+    '--title', 'HashBack',
+    '--main', 'README.rdoc',
+    '--line-numbers',
+    '--inline-source'
+   ]
+   
+  s.add_dependency("wycats-moneta")
+  s.add_dependency("activesupport")
+  s.add_dependency("assaf-uuid")
 end

data/lib/hashback.rb

@@ -1,4 +1,6 @@
 require 'moneta'
 require 'activesupport'
 
-require File.expand_path(File.join(File.dirname(__FILE__), %w[hashback backend] ))
+Dir[File.join(File.dirname(__FILE__), 'hashback', '*.rb')].each do |f|
+  require File.expand_path(f)
+end

data/lib/hashback/backend.rb

@@ -8,7 +8,7 @@ module HashBack
     def initialize(namespace, moneta_klass, options = { })
       @namespace = namespace
       @options   = options
-      @moneta     = initialize_moneta_klass(moneta_klass)
+      @moneta    = initialize_moneta_klass(moneta_klass)
     end
     
     def [](key)
@@ -36,7 +36,13 @@ module HashBack
 
     def load_moneta_klass(klass)
       klass_const = klass.respond_to?(:constantize) ? klass.constantize : klass      
-      klass_const.new(@options)
+      moneta = klass_const.new(@options)
+      
+      # The options hash would have messed up default Hash initialization to return an empty hash
+      # when the key was not found.  Revert this case by setting the default to nil if the object 
+      # responds to this method.
+      moneta.default = nil if moneta.respond_to?(:default)
+      moneta
     end
     
     def require_klass(klass)

data/lib/hashback/resource.rb

@@ -0,0 +1,56 @@
+module HashBack
+  
+  # HashBack::Resource is an Object-Hash Mapping (OHM) tool for Ruby.  It is able to map Ruby objects
+  # to any of the backends supported by Moneta, a unified interface to key-value storage systems.
+  class Resource
+    
+    # Configures the persistent backend for this object.  Configuration options:
+    #
+    # * +source+ - the class to be persisted
+    # * +key_method+ - a symbol representing the method that will return a unique identifier 
+    #   for this object when called on the instance
+    # * +moneta_klass+ - a String representation or class constant of the Moneta class used to store this object
+    # * +moneta_options+ - an (optional) hash which is passed directly to the moneta backend for configuration
+    def self.setup(source, key_method_sym, moneta_klass, moneta_options = {})
+      source.__send__(:class_variable_set, :@@_backend, HashBack::Backend.new(source.to_s, moneta_klass, moneta_options))
+      source.__send__(:class_variable_set, :@@_key_method_sym, key_method_sym)
+
+      source.__send__(:include, InstanceMethods)
+      source.extend(ClassMethods)
+    end
+    
+    module InstanceMethods
+      
+      # Saves the serialized form of this object to the configured backend store.
+      def save
+        _hashback_backend[_hashback_id_key] = self
+      end
+      
+      # Destroy the persisted copy of this object.
+      def destroy
+        _hashback_backend.delete(_hashback_id_key)
+      end
+
+      ## Methods we try to hide, because we're just sneaky like that.
+      
+      def _hashback_backend
+        self.class.__send__(:class_variable_get, :@@_backend)        
+      end
+      
+      def _hashback_id_key
+        self.__send__(self.class.__send__(:class_variable_get, :@@_key_method_sym))
+      end
+      
+      private :_hashback_backend, :_hashback_id_key
+    end
+    
+    module ClassMethods
+      
+      # Fetches the object identified by +key+ from the storage backend.
+      def fetch(key)
+        backend = self.__send__(:class_variable_get, :@@_backend)
+        backend[key]
+      end
+    end
+  end
+end

data/spec/hashback/backend_spec.rb

@@ -3,6 +3,7 @@ require File.join(File.dirname(__FILE__), %w[ .. spec_helper ])
 describe HashBack::Backend do
   before do
     @mock_moneta = mock('moneta')
+    @mock_moneta.stubs(:keys).returns(['keyname'])
     @moneta_klass = "Moneta::Memory"
     @b = HashBack::Backend.new('foo', @moneta_klass, { })
     @b.instance_variable_set(:@moneta, @mock_moneta)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: jsl-hashback
 version: !ruby/object:Gem::Version 
-  version: 0.0.1.2
+  version: 0.0.2.3
 platform: ruby
 authors: 
 - Justin Leitgeb
@@ -18,9 +18,9 @@ dependencies:
   version_requirement: 
   version_requirements: !ruby/object:Gem::Requirement 
     requirements: 
-    - - ">"
+    - - ">="
       - !ruby/object:Gem::Version 
-        version: 0.0.0
+        version: "0"
     version: 
 - !ruby/object:Gem::Dependency 
   name: activesupport
@@ -28,9 +28,19 @@ dependencies:
   version_requirement: 
   version_requirements: !ruby/object:Gem::Requirement 
     requirements: 
-    - - ">"
+    - - ">="
       - !ruby/object:Gem::Version 
-        version: 0.0.0
+        version: "0"
+    version: 
+- !ruby/object:Gem::Dependency 
+  name: assaf-uuid
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
     version: 
 description: Wrapper around Moneta that facilitates using the key-value store as a backend for applications requiring namespacing
 email: justin@phq.org
@@ -38,8 +48,8 @@ executables: []
 
 extensions: []
 
-extra_rdoc_files: []
-
+extra_rdoc_files: 
+- README.rdoc
 files: 
 - Rakefile
 - hashback.gemspec
@@ -48,11 +58,17 @@ files:
 - README.rdoc
 - lib/hashback.rb
 - lib/hashback/backend.rb
+- lib/hashback/resource.rb
 has_rdoc: true
 homepage: http://github.com/jsl/hashback
 post_install_message: 
-rdoc_options: []
-
+rdoc_options: 
+- --title
+- HashBack
+- --main
+- README.rdoc
+- --line-numbers
+- --inline-source
 require_paths: 
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement