perobs 1.1.0 → 2.0.0

data/lib/perobs/Object.rb

@@ -76,7 +76,9 @@ module PEROBS
 
     attr_reader :attributes
 
-    # Create a new PEROBS::Object object.
+    # New PEROBS objects must always be created by calling # Store.new().
+    # PEROBS users should never call this method or equivalents of derived
+    # methods directly.
     def initialize(store)
       super
     end
@@ -89,7 +91,7 @@ module PEROBS
     # @param val [Any] Value to be set
     # @return [true|false] True if the value was initialized, otherwise false.
     def init_attr(attr, val)
-      if self.class.attributes.include?(attr)
+      if _all_attributes.include?(attr)
         _set(attr, val)
         return true
       end
@@ -102,9 +104,9 @@ module PEROBS
     # @return [Array of Fixnum or Bignum] IDs of referenced objects
     def _referenced_object_ids
       ids = []
-      self.class.attributes.each do |attr|
+      _all_attributes.each do |attr|
         value = instance_variable_get(('@' + attr.to_s).to_sym)
-        ids << value.id if value && value.is_a?(POReference)
+        ids << value.id if value && value.respond_to?(:is_poxreference?)
       end
       ids
     end
@@ -113,10 +115,10 @@ module PEROBS
     # delete all referenced to the given object ID.
     # @param id [Fixnum/Bignum] targeted object ID
     def _delete_reference_to_id(id)
-      self.class.attributes.each do |attr|
+      _all_attributes.each do |attr|
         ivar = ('@' + attr.to_s).to_sym
         value = instance_variable_get(ivar)
-        if value && value.is_a?(POReference) && value.id == id
+        if value && value.respond_to?(:is_poxreference?) && value.id == id
           instance_variable_set(ivar, nil)
         end
       end
@@ -129,6 +131,7 @@ module PEROBS
     def _deserialize(data)
       # Initialize all attributes with the provided values.
       data.each do |attr_name, value|
+        value = POXReference.new(@store, value.id) if value.is_a?(POReference)
         instance_variable_set(('@' + attr_name).to_sym, value)
       end
     end
@@ -137,7 +140,7 @@ module PEROBS
     # @return [String]
     def inspect
       "{\n" +
-      self.class.attributes.map do |attr|
+      _all_attributes.map do |attr|
         ivar = ('@' + attr.to_s).to_sym
         "  #{attr.inspect}=>#{instance_variable_get(ivar).inspect}"
       end.join(",\n") +
@@ -150,23 +153,25 @@ module PEROBS
     # class.
     def _serialize
       attributes = {}
-      self.class.attributes.each do |attr|
+      _all_attributes.each do |attr|
         ivar = ('@' + attr.to_s).to_sym
-        if (value = instance_variable_get(ivar)).is_a?(ObjectBase)
-          raise ArgumentError, "The instance variable #{ivar} contains a " +
-                               "reference to a PEROBS::ObjectBase object! " +
-                               "This is not allowed. You must use the " +
-                               "accessor method to assign a reference to " +
-                               "another PEROBS object."
-        end
-        attributes[attr.to_s] = value
+        value = instance_variable_get(ivar)
+        #if (value = instance_variable_get(ivar)).is_a?(ObjectBase)
+        #  raise ArgumentError, "The instance variable #{ivar} contains a " +
+        #                       "reference to a PEROBS::ObjectBase object! " +
+        #                       "This is not allowed. You must use the " +
+        #                       "accessor method to assign a reference to " +
+        #                       "another PEROBS object."
+        #end
+        attributes[attr.to_s] = value.respond_to?(:is_poxreference?) ?
+          POReference.new(value.id) : value
       end
       attributes
     end
 
     def _set(attr, val)
       ivar = ('@' + attr.to_s).to_sym
-      if val.is_a?(ObjectBase)
+      if !val.respond_to?(:is_poxreference?) && val.is_a?(ObjectBase)
         # References to other PEROBS::Objects must be handled somewhat
         # special.
         if @store != val.store
@@ -175,7 +180,7 @@ module PEROBS
         # To release the object from the Ruby object list later, we store the
         # PEROBS::Store ID of the referenced object instead of the actual
         # reference.
-        instance_variable_set(ivar, POReference.new(val._id))
+        instance_variable_set(ivar, POXReference.new(@store, val._id))
       else
         instance_variable_set(ivar, val)
       end
@@ -187,13 +192,24 @@ module PEROBS
 
     def _get(attr)
       value = instance_variable_get(('@' + attr.to_s).to_sym)
-      if value.is_a?(POReference)
+      if value.respond_to?(:is_poxreference?)
         @store.object_by_id(value.id)
       else
         value
       end
     end
 
+    def _all_attributes
+      # PEROBS objects that don't have persistent attributes declared don't
+      # really make sense.
+      unless self.class.attributes
+        raise StandardError
+          "No persistent attributes have been declared for " +
+          "class #{self.class}. Use 'po_attr' to declare them."
+      end
+      self.class.attributes
+    end
+
   end
 
 end

data/lib/perobs/ObjectBase.rb

@@ -32,26 +32,88 @@ module PEROBS
   # This class is used to replace a direct reference to another Ruby object by
   # the Store ID. This makes object disposable by the Ruby garbage collector
   # since it's no longer referenced once it has been evicted from the
-  # PEROBS::Store cache.
-  class POReference < Struct.new(:id)
+  # PEROBS::Store cache. The POXReference objects function as a transparent
+  # proxy for the objects they are referencing.
+  class POXReference  < BasicObject
+
+    attr_reader :store, :id
+
+    def initialize(store, id)
+      super()
+      @store = store
+      @id = id
+    end
+
+    # Proxy all calls to unknown methods to the referenced object.
+    def method_missing(method_sym, *args, &block)
+      unless (obj = _referenced_object)
+        raise ::RuntimeError, "Internal consistency error. No object with " +
+          "ID #{@id} found in the store"
+      end
+      if obj.respond_to?(:is_poxreference?)
+        raise ::RuntimeError,
+          "POXReference that references a POXReference found"
+      end
+      obj.send(method_sym, *args, &block)
+    end
+
+    # Proxy all calls to unknown methods to the referenced object. Calling
+    # respond_to?(:is_poxreference?) is the only reliable way to find out if
+    # the object is a POXReference or not as pretty much every method call is
+    # proxied to the referenced object.
+    def respond_to?(method_sym, include_private = false)
+      (method_sym == :is_poxreference?) ||
+        _referenced_object.respond_to?(method_sym, include_private)
+    end
+
+    # Just for completeness. We don't want to be caught lying.
+    def is_poxreference?
+      true
+    end
+
+    # @return [ObjectBase] Return the referenced object. This method should
+    # not be used outside of the PEROBS library. Leaked references can cause
+    # data corruption.
+    def _referenced_object
+      @store.object_by_id(@id)
+    end
+
+    # BasicObject provides a ==() method that prevents method_missing from
+    # being called. So we have to pass the call manually to the referenced
+    # object.
+    # @param obj object to compare this object with.
+    def ==(obj)
+      _referenced_object == obj
+    end
 
-    # Textual dump for debugging purposes
-    # @return [String]
-    def inspect
-      "@#{id}"
+    # Shortcut to access the _id() method of the referenced object.
+    def _id
+      @id
     end
 
   end
 
+  # This class is used to serialize the POXReference objects. It only holds
+  # the ID of the referenced Object.
+  class POReference < Struct.new(:id)
+  end
+
   # Base class for all persistent objects. It provides the functionality
   # common to all classes of persistent objects.
   class ObjectBase
 
     attr_reader :_id, :store
 
-    # Create a new PEROBS::ObjectBase object.
+    # New PEROBS objects must always be created by calling # Store.new().
+    # PEROBS users should never call this method or equivalents of derived
+    # methods directly.
     def initialize(store)
       @store = store
+      unless @store.object_creation_in_progress
+        raise ::RuntimeError,
+          "All PEROBS objects must exclusively be created by calling " +
+          "Store.new(). Never call the object constructor directly."
+      end
       @_id = @store.db.new_id
       @_stash_map = nil
 
@@ -59,8 +121,18 @@ module PEROBS
       @store.cache.cache_write(self)
     end
 
+    public
+
+    # This method can be overloaded by derived classes to do some massaging on
+    # the data after it has been restored from the database. This could either
+    # be some sanity check or code to migrate the object from one version to
+    # another.
+    def post_restore
+    end
+
     # Two objects are considered equal if their object IDs are the same.
     def ==(obj)
+      return false unless obj.is_a?(ObjectBase)
       obj && @_id == obj._id
     end
 
@@ -85,11 +157,12 @@ module PEROBS
 
       klass = store.class_map.id_to_class(db_obj['class_id'])
       # Call the constructor of the specified class.
-      obj = Object.const_get(klass).new(store)
+      obj = store.construct_po(Object.const_get(klass))
       # The object gets created with a new ID by default. We need to restore
       # the old one.
       obj._change_id(id)
       obj._deserialize(db_obj['data'])
+      obj.post_restore
 
       obj
     end
@@ -140,29 +213,10 @@ module PEROBS
     def _change_id(id)
       # Unregister the object with the old ID from the write cache to prevent
       # cache corruption. The objects are index by ID in the cache.
-      store.cache.unwrite(self)
+      @store.cache.unwrite(self)
       @_id = id
     end
 
-    private
-
-    def _dereferenced(v)
-      v.is_a?(POReference) ? @store.object_by_id(v.id) : v
-    end
-
-    def _referenced(obj)
-      if obj.is_a?(ObjectBase)
-        # The obj is a reference to another persistent object. Store the ID
-        # of that object in a POReference object.
-        if @store != obj.store
-          raise ArgumentError, 'The referenced object is not part of this store'
-        end
-        POReference.new(obj._id)
-      else
-        obj
-      end
-    end
-
   end
 
 end

data/lib/perobs/Store.rb

@@ -25,6 +25,8 @@
 # OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
 # WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 
+require 'set'
+
 require 'perobs/Cache'
 require 'perobs/ClassMap'
 require 'perobs/BTreeDB'
@@ -38,18 +40,55 @@ module PEROBS
   # PEROBS::Store is a persistent storage system for Ruby objects. Regular
   # Ruby objects are transparently stored in a back-end storage and retrieved
   # when needed. It features a garbage collector that removes all objects that
-  # are no longer in use.  A build-in cache keeps access latencies to recently
+  # are no longer in use. A build-in cache keeps access latencies to recently
   # used objects low and lazily flushes modified objects into the persistend
-  # back-end. Currently only filesystems are supported but it can easily be
-  # extended to any key/value database.
+  # back-end. The default back-end is a filesystem based database.
+  # Alternatively, an Amazon DynamoDB can be used as well. Adding support for
+  # other key/value stores is fairly trivial to do. See PEROBS::DynamoDB for
+  # an example
+  #
+  # Persistent objects must be defined by deriving your class from
+  # PEROBS::Object, PERBOS::Array or PEROBS::Hash. Only instance variables
+  # that are declared via po_attr will be persistent. It is recommended that
+  # references to other objects are all going to persistent objects again. TO
+  # create a new persistent object you must call Store.new(). Don't use the
+  # constructors of persistent classes directly. Store.new() will return a
+  # proxy or delegator object that can be used like the actual object. By
+  # using delegators we can disconnect the actual object from the delegator
+  # handle.
+  #
+  # require 'perobs'
+  #
+  # class Person < PEROBS::Object
+  #
+  #   po_attr :name, :mother, :father, :kids
+  #
+  #   def initialize(store, name)
+  #     super
+  #     attr_init(:name, name)
+  #     attr_init(:kids, @store.new(PEROBS::Array))
+  #   end
+  #
+  #   def to_s
+  #     "#{@name} is the child of #{self.mother ? self.mother.name : 'unknown'} " +
+  #     "and #{self.father ? self.father.name : 'unknown'}.
+  #   end
+  #
+  # end
+  #
+  # store = PEROBS::Store.new('family')
+  # store['grandpa'] = joe = store.new(Person, 'Joe')
+  # store['grandma'] = jane = store.new(Person, 'Jane')
+  # jim = store.new(Person, 'Jim')
+  # jim.father = joe
+  # joe.kids << jim
+  # jim.mother = jane
+  # jane.kids << jim
+  # store.sync
   #
-  # Persistent objects must be created by deriving your class from
-  # PEROBS::Object. Only instance variables that are declared via
-  # po_attr will be persistent. It is recommended that references to other
-  # objects are all going to persistent objects again.
   class Store
 
-    attr_reader :db, :cache, :class_map
+    attr_reader :db, :cache, :class_map, :object_creation_in_progress
 
     # Create a new Store.
     # @param data_base [String] the name of the database
@@ -85,6 +124,9 @@ module PEROBS
       # Create a map that can translate classes to numerical IDs and vice
       # versa.
       @class_map = ClassMap.new(@db)
+      # This flag is used to check that PEROBS objects are only created via
+      # the Store.new() call by PEROBS users.
+      @object_creation_in_progress = false
 
       # The Cache reduces read and write latencies by keeping a subset of the
       # objects in memory.
@@ -92,7 +134,8 @@ module PEROBS
 
       # The named (global) objects IDs hashed by their name
       unless (@root_objects = object_by_id(0))
-        @root_objects = Hash.new(self)
+        @root_objects = construct_po(Hash)
+
         # The root object hash always has the object ID 0.
         @root_objects._change_id(0)
         # The ID change removes it from the write cache. We need to add it
@@ -101,6 +144,26 @@ module PEROBS
       end
     end
 
+    # You need to call this method to create new PEROBS objects that belong to
+    # this Store.
+    # @param klass [Class] The class of the object you want to create. This
+    #        must be a derivative of ObjectBase.
+    # @param *args Optional list of other arguments that are passed to the
+    #        constructor of the specified class.
+    # @return [POXReference] A reference to the newly created object.
+    def new(klass, *args)
+      POXReference.new(self, construct_po(klass, *args)._id)
+    end
+
+    # For library internal use only!
+    def construct_po(klass, *args)
+      @object_creation_in_progress = true
+      obj = klass.new(self, *args)
+      @object_creation_in_progress = false
+      obj
+    end
+
+
     # Delete the entire store. The store is no longer usable after this
     # method was called.
     def delete_store
@@ -124,6 +187,9 @@ module PEROBS
         return nil
       end
 
+      if obj.respond_to?(:is_poxreference?)
+        obj = obj._referenced_object
+      end
       # We only allow derivatives of PEROBS::Object to be stored in the
       # store.
       unless obj.is_a?(ObjectBase)

data/lib/perobs/version.rb

@@ -1,4 +1,4 @@
 module PEROBS
   # The version number
-  VERSION = "1.1.0"
+  VERSION = "2.0.0"
 end

data/tasks/test.rake

@@ -3,5 +3,6 @@ require 'rspec/core/rake_task'
 
 desc 'Run all RSpec tests in the spec directory'
 RSpec::Core::RakeTask.new(:test) do |t|
-  t.pattern = 'test/*_spec.rb'
+  t.pattern = Dir.glob('test/*_spec.rb')
+  t.rspec_opts = "-I #{File.join(File.dirname(__FILE__), '..', 'test')}"
 end

data/test/Array_spec.rb

@@ -0,0 +1,208 @@
+# encoding: UTF-8
+#
+# Copyright (c) 2015 by Chris Schlaeger <chris@taskjuggler.org>
+#
+# This file contains tests for Array that are similar to the tests for the
+# Array implementation in MRI. The ideas of these tests were replicated in
+# this code.
+#
+# MIT License
+#
+# 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.
+
+require 'spec_helper'
+
+require 'perobs'
+
+class PO < PEROBS::Object
+
+  po_attr :name
+
+  def initialize(store, name = nil)
+    super(store)
+    _set(:name, name)
+  end
+
+end
+
+describe PEROBS::Array do
+
+  before(:all) do
+    @db_name = generate_db_name(__FILE__)
+  end
+
+  before(:each) do
+    @store = PEROBS::Store.new(@db_name)
+  end
+
+  after(:each) do
+    @store.delete_store
+  end
+
+  it 'should store simple objects persistently' do
+    @store['a'] = a = @store.new(PEROBS::Array)
+    a[0] = 'A'
+    a[1] = 'B'
+    a[2] = po = @store.new(PO)
+    po.name = 'foobar'
+
+    expect(a[0]).to eq('A')
+    expect(a[1]).to eq('B')
+    expect(a[2].name).to eq('foobar')
+    @store.sync
+
+    @store = PEROBS::Store.new(@db_name)
+    a = @store['a']
+    expect(a[0]).to eq('A')
+    expect(a[1]).to eq('B')
+    expect(a[2].name).to eq('foobar')
+  end
+
+  it 'should have an each method to iterate' do
+    @store['a'] = a = @store.new(PEROBS::Array)
+    a[0] = 'A'
+    a[1] = 'B'
+    a[2] = 'C'
+    vs = ''
+    a.each { |v| vs << v }
+    expect(vs).to eq('ABC')
+    @store.sync
+
+    @store = PEROBS::Store.new(@db_name)
+    a = @store['a']
+    vs = ''
+    a[3] = @store.new(PO, 'D')
+    a.each { |v| vs << (v.is_a?(String) ? v : v.name) }
+    expect(vs).to eq('ABCD')
+  end
+
+  # Utility method to create a PEROBS::Array from a normal Array.
+  def cpa(ary = nil)
+    a = @store.new(PEROBS::Array)
+    a.replace(ary) unless ary.nil?
+    @store['a'] = a
+  end
+
+  def pcheck
+    yield
+    @store.sync
+    @store = PEROBS::Store.new(@db_name)
+    yield
+  end
+
+  it 'should support reading methods' do
+    expect(cpa([ 1, 1, 3, 5 ]) & cpa([ 1, 2, 3 ])).to eq([ 1, 3 ])
+    expect(cpa & cpa([ 1, 2, 3 ])).to eq([])
+
+    expect(cpa.empty?).to be true
+    expect(cpa([ 0 ]).empty?).to be false
+
+    x = cpa([ 'it', 'came', 'to', 'pass', 'that', '...'])
+    x = x.sort.join(' ')
+    expect(x).to eq('... came it pass that to')
+  end
+
+  it 'should support Enumberable methods' do
+    x = cpa([ 2, 5, 3, 1, 7 ])
+    expect(x.find { |e| e == 4 }).to be_nil
+    expect(x.find { |e| e == 3 }).to eq(3)
+  end
+
+  it 'should support re-writing methods' do
+    x = cpa([2, 5, 3, 1, 7])
+    x.sort!{ |a, b| a <=> b }
+    pcheck { expect(x).to eq([ 1, 2, 3, 5, 7 ]) }
+    x.sort!{ |a, b| b - a }
+    pcheck { expect(x).to eq([ 7, 5, 3, 2, 1 ]) }
+
+    x.clear
+    pcheck { expect(x).to eq([]) }
+  end
+
+  it 'should support <<()' do
+    a = cpa([ 0, 1, 2 ])
+    a << 4
+    pcheck { expect(a).to eq([ 0, 1, 2, 4 ]) }
+  end
+
+  it 'should support []=' do
+    a = cpa([ 0, nil, 2 ])
+    a[1] = 1
+    pcheck { expect(a).to eq([ 0, 1, 2 ]) }
+  end
+
+  it 'should support collect!()' do
+    a = cpa([ 1, 'cat', 1..1 ])
+    expect(a.collect! { |e| e.class }).to eq([ Fixnum, String, Range ])
+    pcheck { expect(a).to eq([ Fixnum, String, Range ]) }
+
+    a = cpa([ 1, 'cat', 1..1 ])
+    expect(a.collect! { 99 }).to eq([ 99, 99, 99])
+    pcheck { expect(a).to eq([ 99, 99, 99]) }
+  end
+
+  it 'should support map!()' do
+    a = cpa([ 1, 'cat', 1..1 ])
+    expect(a.map! { |e| e.class }).to eq([ Fixnum, String, Range ])
+    pcheck { expect(a).to eq([ Fixnum, String, Range ]) }
+
+    a = cpa([ 1, 'cat', 1..1 ])
+    expect(a.map! { 99 }).to eq([ 99, 99, 99])
+    pcheck { expect(a).to eq ([ 99, 99, 99]) }
+  end
+
+  it 'should support fill()' do
+    pcheck { expect(cpa([]).fill(99)).to eq([]) }
+    pcheck { expect(cpa([]).fill(99, 0)).to eq([]) }
+    pcheck { expect(cpa([]).fill(99, 0, 1)).to eq([ 99 ]) }
+  end
+
+  it 'should support flatten!()' do
+    a1 = cpa([ 1, 2, 3])
+    a2 = cpa([ 5, 6 ])
+    a3 = cpa([ 4, a2 ])
+    a4 = cpa([ a1, a3 ])
+    pcheck { expect(a4.flatten).to eq([ 1, 2, 3, 4, 5, 6 ]) }
+  end
+
+  it 'should support replace()' do
+    a = cpa([ 1, 2, 3])
+    a_id = a.__id__
+    expect(a.replace(cpa([4, 5, 6]))).to eq([ 4, 5, 6 ])
+    pcheck { expect(a).to eq ([ 4, 5, 6 ]) }
+  end
+
+  it 'should support insert()' do
+    a = cpa([ 0 ])
+    a.insert(1)
+    pcheck { expect(a).to eq([ 0 ]) }
+    a.insert(1, 1)
+    pcheck { expect(a).to eq([ 0, 1]) }
+  end
+
+  it 'should support push()' do
+    a = cpa([ 1, 2, 3 ])
+    a.push(4, 5)
+    pcheck { expect(a).to eq([ 1, 2, 3, 4, 5 ]) }
+    a.push(nil)
+    pcheck { expect(a).to eq([ 1, 2, 3, 4, 5, nil ]) }
+  end
+
+end