Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
A ruby Object-Hash Mapper (OHM).
Ruby
branch: master

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.
examples
lib
spec
.gitignore
LICENSE
README.rdoc
Rakefile
hashback.gemspec
init.rb

README.rdoc

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>

Something went wrong with that request. Please try again.