Permalink
Switch branches/tags
Nothing to show
Find file
Fetching contributors…
Cannot retrieve contributors at this time
94 lines (59 sloc) 3.48 KB

HashBack

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. It works particulary well with, but has no dependency on Moneta (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.new)

  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.

HashBack::Backend

A lightweight class called HashBack::Backend is included with the distribution of this gem. This class wraps common Hash-like getter and setter methods with ones that include a namespace. This may be helpful to you if you're persisting many objects to the same backend data store. Please see the documentation for HashBack::Backend for more information.

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, HashBack::Backend.new('Foo', Moneta::Memcache.new(: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

Feedback

Please write the author if you have any questions or feedback regarding this library.

Author

Justin S. Leitgeb, <justin@phq.org>