poro_repository 0.0.1

data/.gitignore

@@ -0,0 +1,2 @@
+Gemfile.lock
+

data/Gemfile

@@ -0,0 +1,3 @@
+source 'https://rubygems.org'
+
+gem 'rspec'

data/README.md

@@ -0,0 +1,73 @@
+poro_repository
+================
+
+Store plain old ruby objects to the file system. You can store any object that
+can be marshalled. The objects to be stored need not inherit from any library
+base class, nor include any library module.
+
+Usage Examples
+--------------
+
+A simple example
+
+```ruby
+class Contact
+  attr_accessor :id, :name
+end
+
+contact = Contact.new
+contact.id = 1
+contact.name = "John Smith"
+
+repo = PoroRepository.new("/repository/path")
+repo.save_record contact
+
+# ...
+
+repo.load_record('Contact', 1).name #=> "John Smith"
+```
+
+Storing different entities separately
+
+```ruby
+class Contact
+  attr_accessor :id, :name
+end
+
+class Company
+  attr_accessor :id, :name
+end
+
+xyz_company = Company.new
+xyz_company.id = 1
+xyz_company.name = "XYZ Company"
+
+contact = Contact.new
+contact.id = 1
+contact.name = "John Smith"
+contact.company = xyz_company
+
+repo = PoroRepository.new("/repository/path")
+repo.boundary :Contact, :@company # causes company record to save separately
+
+repo.save_record contact
+
+# ...
+
+# company record stored separately, and can be loaded independently
+loaded_company = repo.load_record 'Company', 1
+
+loaded_contact = repo.load_record 'Contact', 1
+loaded_contact.company == loaded_company #=> true
+loaded_contact.company.equal?(loaded_company) #=> true ; same object
+```
+
+Caveats
+-------
+
+* No consideration has been given to concurrency. If you need concurrency, you
+  should probably use something else.
+* At least at this stage, it is only really suitable for storing hundreds of
+  objects, not thousands or millions.
+* It's still very incomplete and is missing most features required for it to
+  be generally useful.

data/lib/poro_repository/boundary_token.rb

@@ -0,0 +1,10 @@
+class PoroRepository::BoundaryToken
+
+  attr_reader :original_type, :original_id
+
+  def initialize original_type, original_id
+    @original_type = original_type
+    @original_id = original_id
+  end
+
+end

data/lib/poro_repository/record_meta_data.rb

@@ -0,0 +1,13 @@
+class PoroRepository::RecordMetaData
+
+  def id
+    @id ||= random_id
+  end
+
+  private
+
+  def random_id
+    Digest::SHA1.hexdigest("#{rand}#{rand}#{rand}#{Time.now.to_i}")
+  end
+
+end

data/lib/poro_repository/weak_hash.rb

@@ -0,0 +1,24 @@
+require 'weakref'
+
+# http://endofline.wordpress.com/2011/01/09/getting-to-know-the-ruby-standard-library-weakref/
+class PoroRepository::WeakHash < Hash
+
+  class AmbivalentRef < WeakRef
+    def __getobj__
+      super rescue nil
+    end
+
+    alias actual __getobj__
+  end
+
+  def []= key, object
+    super(key, AmbivalentRef.new(object))
+  end
+
+  def [] key
+    ref = super(key)
+    self.delete(key) if !ref.weakref_alive?
+    ref
+  end
+
+end

data/lib/poro_repository.rb

@@ -0,0 +1,165 @@
+require 'digest/sha1'
+require 'fileutils'
+
+class PoroRepository
+
+  autoload :WeakHash, "poro_repository/weak_hash"
+  autoload :RecordMetaData, "poro_repository/record_meta_data"
+  autoload :BoundaryToken, "poro_repository/boundary_token"
+
+  attr_accessor :remember
+
+  def initialize root
+    @root = root
+    @instantiated_records = {}
+    @boundaries = {}
+    @remember = true
+  end
+
+  # When serialising, attributes identified as "boundaries" are not serialised with the
+  # larger object, but are instead serialised separately. A placeholder is used in the
+  # original object, with an ID for the extracted object.
+  # @param type [Symbol]
+  # @param instance_var [Symbol]
+  def boundary type, instance_var
+    @boundaries[type] ||= []
+    @boundaries[type] << instance_var
+  end
+
+  def nuke! really
+    if really == 'yes, really'
+      FileUtils.rm_rf @root
+    else
+      raise "wont do it!"
+    end
+  end
+
+  def load_record type, id
+    record = previous_instantiated type, id
+    return record unless record.nil?
+    data = read_if_exists(record_path(type, id))
+    data && deserialise(data).tap do |record|
+      record.instance_variables.each do |inst_var|
+        if (token = record.instance_variable_get(inst_var)).is_a? BoundaryToken
+          object = load_record token.original_type, token.original_id
+          record.instance_variable_set inst_var, object
+        end
+      end
+      remember_record record if @remember
+    end
+  end
+
+  # @return [String] record id
+  def save_record record, remember=true
+    id = id_from_record(record)
+    path = record_path(type_from_record(record), id)
+    open_for_write path do |file|
+      with_boundary_objects_extracted record do |extracted|
+        file.write serialise record
+        extracted.each do |extracted_record|
+          save_record extracted_record
+        end
+      end
+    end
+    remember_record record if @remember
+    id
+  end
+
+  private
+
+  def open_for_write path, &block
+    FileUtils.mkdir_p File.dirname(path)
+    File.open path, 'w', &block
+  end
+
+  # @return [String, nil]
+  def read_if_exists path
+    if File.exist? path
+      File.read path
+    else
+      nil
+    end
+  end
+
+  def record_metadata record
+    record.instance_eval do
+      @_repository_data ||= RecordMetaData.new
+    end
+  end
+
+  def serialise record
+    Marshal.dump(record)
+  end
+
+  def deserialise data
+    Marshal.load(data)
+  end
+
+  # @return [String]
+  def type_from_record record
+    if record.respond_to? :type
+      record.type
+    else
+      record.class.name.split('::').last
+    end
+  end
+
+  def id_from_record record
+    if record.respond_to?(:id) && record.id
+      record.id
+    else
+      record_metadata(record).id
+    end
+  end
+
+  def record_path type, id
+    raise if id.nil?
+    "#{@root}/#{type}/records/#{id}"
+  end
+
+  def index_path type, field
+    "#{@root}/#{type}/index/#{field}"
+  end
+
+  def with_boundary_objects_extracted record, &block
+    originals = {}
+    boundaries(record).each do |inst_var|
+      value = record.instance_variable_get(inst_var)
+      originals[inst_var] = value
+      record.instance_variable_set(inst_var, boundary_token(value))
+    end
+    block.call originals.values
+  ensure
+    originals.each do |inst_var, original_value|
+      record.instance_variable_set(inst_var, original_value)
+    end
+  end
+
+  def boundaries record
+    @boundaries[type_from_record(record).to_sym] || []
+  end
+
+  def boundary_token record
+    BoundaryToken.new type_from_record(record), id_from_record(record)
+  end
+
+  def remember_record record
+    type = type_from_record(record)
+    @instantiated_records[type] ||= WeakHash.new
+    @instantiated_records[type][id_from_record(record)] = record
+  end
+
+  def previous_instantiated type, id
+    records = @instantiated_records[type] || {}
+    ref = records[id]
+    ref && ref.actual
+  end
+
+  # this method is only used in test
+  def remembered_records
+    @instantiated_records.values.collect do |h|
+      h.values.compact.collect(&:actual)
+    end.flatten.compact
+  end
+
+end

data/poro_repository.gemspec

@@ -0,0 +1,18 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+
+Gem::Specification.new do |s|
+  s.name        = "poro_repository"
+  s.version     = "0.0.1"
+  s.authors     = ["Joel Plane"]
+  s.email       = ["joel.plane@gmail.com"]
+  s.homepage    = "https://github.com/joelplane/poro_repository"
+  s.summary     = %q{PORO Repository}
+  s.description = %q{Library for storing plain old ruby objects to the file system}
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- spec/*`.split("\n")
+  s.require_paths = ["lib"]
+
+  s.add_development_dependency "rspec"
+end

data/spec/poro_repository_spec.rb

@@ -0,0 +1,167 @@
+require 'spec_helper'
+require 'ostruct'
+
+describe PoroRepository do
+
+  subject do
+    PoroRepository.new("/tmp/test-avial-invoicing-repository").tap do |repo|
+      # disable storing of records in memory, so we know we're not cheating
+      repo.remember = false
+    end
+  end
+
+  let(:record) do
+    OpenStruct.new.tap do |o|
+      o.type = 'Invoice'
+      o.blah = 'blah'
+    end
+  end
+
+  let(:record_with_id) do
+    OpenStruct.new.tap do |o|
+      o.id = "123"
+      o.type = 'Invoice'
+      o.blah = 'blah'
+    end
+  end
+
+  after(:each) do
+    subject.nuke! 'yes, really'
+  end
+
+  context "when the record does not have an id attribute" do
+    it "automatically assigns a random id" do
+      record_id = subject.save_record record
+      record_id.should match /^[a-f0-9]{40}$/
+    end
+  end
+
+  context "when the record has an id attribute" do
+    it "uses the record's id, not a random one" do
+      record_id = subject.save_record record_with_id
+      record_id.should == '123'
+    end
+  end
+
+  it "saves and retrieves a record" do
+    record_id = subject.save_record record
+    loaded_record = subject.load_record('Invoice', record_id)
+    loaded_record.should == record        # record should be the same value
+    loaded_record.should_not equal record # but not the same object
+                                          # NOTE - it would be the same object, but we did repo.remember = false
+  end
+
+  it "does not save more than one copy of a record" do
+    record_id1 = subject.save_record record
+    record_id2 = subject.save_record record
+    record_id1.should == record_id2
+  end
+
+  # An Invoice has a Contact. We define the relationship as a boundary.
+  # This means the Invoice and the Contact are stored separately. To
+  # confirm this, we store the Invoice, and then try to load up just
+  # the Contact.
+  describe "boundaries" do
+
+    subject do
+      PoroRepository.new("/tmp/test-avial-invoicing-repository").tap do |repo|
+        repo.boundary :Invoice, :@contact
+        repo.remember = false
+      end
+    end
+
+    # Some arbitrary object that an invoice might have.
+    # Here to test that it gets stored with the invoice and not
+    # independently, since don't define a boundary for it.
+    let(:terms) do
+      TestObject.new.tap do |o|
+        o.id = '123'
+        o.type = 'Terms'
+        o.due_days = 7
+      end
+    end
+
+    let(:contact) do
+      TestObject.new.tap do |o|
+        o.id = '234'
+        o.type = 'Contact'
+        o.name = 'John Smith'
+      end
+    end
+
+    let(:invoice) do
+      TestObject.new.tap do |o|
+        o.id = '345'
+        o.type = 'Invoice'
+        o.contact = contact
+        o.terms = terms
+      end
+    end
+
+    it "should not store non-boundary objects separately" do
+      subject.save_record invoice
+      loaded_terms = subject.load_record('Terms', terms.id)
+      loaded_terms.should be_nil
+    end
+
+    it "should store boundary objects separately" do
+      subject.save_record invoice
+      loaded_contact = subject.load_record('Contact', contact.id)
+      loaded_contact.should be_a contact.class
+      loaded_contact.name.should == 'John Smith'
+    end
+
+    it "should load boundary objects" do
+      subject.save_record invoice
+      loaded_invoice = subject.load_record('Invoice', invoice.id)
+      loaded_invoice.contact.should be_a contact.class
+      loaded_invoice.contact.name.should == 'John Smith'
+    end
+
+  end
+
+  describe "object lifecycle" do
+
+    subject do
+      PoroRepository.new("/tmp/test-avial-invoicing-repository")
+    end
+
+    let(:invoice) do
+      TestObject.new.tap do |o|
+        o.id = '345'
+        o.type = 'Invoice'
+      end
+    end
+
+    context do
+      before do
+        subject.save_record invoice
+      end
+
+      it "should return the same object on sucessive calls to load_record" do
+        record1 = subject.load_record 'Invoice', '345'
+        record2 = subject.load_record 'Invoice', '345'
+        record1.should equal record2
+      end
+
+      it "should return the original object if still in memory" do
+        loaded_record = subject.load_record 'Invoice', '345'
+        loaded_record.should equal invoice
+      end
+    end
+
+    it "should not prevent records from being garbage collected" do
+      GC.disable
+      records = [TestObject.new.tap { |o| o.id = '345'; o.type = 'Invoice' }]
+      subject.save_record records.first
+      subject.send(:remembered_records).length.should == 1
+      records.clear
+      subject.send(:remembered_records).length.should == 1
+      GC.enable
+      GC.start
+      subject.send(:remembered_records).length.should == 0
+    end
+
+  end
+
+end

data/spec/spec_helper.rb

@@ -0,0 +1,9 @@
+require 'poro_repository'
+require_relative 'test_object'
+
+RSpec.configure do |config|
+  config.treat_symbols_as_metadata_keys_with_true_values = true
+  config.run_all_when_everything_filtered = true
+  config.filter_run :focus
+  config.order = 'random'
+end

data/spec/test_object.rb

@@ -0,0 +1,3 @@
+class TestObject
+  attr_accessor :id, :type, :name, :terms, :contact, :due_days
+end

metadata

@@ -0,0 +1,75 @@
+--- !ruby/object:Gem::Specification
+name: poro_repository
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+  prerelease: 
+platform: ruby
+authors:
+- Joel Plane
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-10-06 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Library for storing plain old ruby objects to the file system
+email:
+- joel.plane@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- Gemfile
+- README.md
+- lib/poro_repository.rb
+- lib/poro_repository/boundary_token.rb
+- lib/poro_repository/record_meta_data.rb
+- lib/poro_repository/weak_hash.rb
+- poro_repository.gemspec
+- spec/poro_repository_spec.rb
+- spec/spec_helper.rb
+- spec/test_object.rb
+homepage: https://github.com/joelplane/poro_repository
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.24
+signing_key: 
+specification_version: 3
+summary: PORO Repository
+test_files:
+- spec/poro_repository_spec.rb
+- spec/spec_helper.rb
+- spec/test_object.rb