Rubernate 0.1.5 → 0.1.6

data/README

@@ -4,7 +4,7 @@ Rubernate is an object-oriented storage for Ruby objects based on relational dat
 
 Rubernate provides an ability to create persistent object hierarchies with minimal restrictions 
 on their structure. The main difference of Rubernate from traditional ORM is that it uses common 
-database tables to store all classes of persistent objects. All object's-related data are stored in 
+database tables to store all classes of persistent objects. All object-related data are stored in 
 fixed set of tables.
 
 This approach has following advantages:

data/lib/rubernate/callbacks.rb

@@ -4,64 +4,61 @@ module Rubernate
 # Methods in these modules are intended to be overridden by user 
 # in other to extend basic functionality.
 module Callbacks
-  # This module contains callback methods and 
-  # included in all persisten classes.
+  # This module contains callback methods and included in all persisten classes.
   module Persistent
-    # Invoked if object has just been created in database.
+    # It's invoked if object has just been created in database.
     def on_create
     end
 
-    # Invoked when object is about to be removed from database.
+    # It's invoked when object is about to be removed from database.
     def on_remove
     end
 
-    # Invoked when object is about to be stored in database.
+    # It's invoked when object is about to be stored in database.
     def on_save
     end
 
-    # Invoked if object has just been loaded from database.
+    # It's invoked if object has just been loaded from database.
     def on_load
     end
 
-    # Invoked if property of object has just been changed via = or [] = operator.
+    # It's invoked if property of object has just been changed via = or [] = operator.
     def on_change prop_name, old_value, new_value
     end
 
-    # Invoked if Hash or Array property  has been modified.
+    # It's invoked if Hash or Array property  has been modified.
     def on_modify prop_name, old_value, new_value
     end
     
-    # Invoked if object referred by this one has been deleted
+    # It's invoked if object referred by this one has been deleted
     def on_lose_ref ref_prop, ref_obj
     end
   end
  
-  # This module contains callback method and 
-  # included in class Rubernate::Runtime. 
+  # This module contains callback method and  included in class Rubernate::Runtime. 
   module Runtime
-    # Invoked on session creation.
+    # It's invoked on session creation.
     def on_begin
     end
 
-    # Invoked if session is about to be rolled back.
+    # It's invoked if session/transaction is about to be rolled back.
     def on_rollback
     end
 
-    # Invoked if session is about to be commited.
+    # It's invoked if session/transaction is about to be commited.
     def before_commit
     end
 
-    # Invoked if session has just been commited
+    # It's invoked if transaction has just been commited.
     def after_commit
     end
         
-    # Invoked when Rubernate needs to flush modified objects
-    # It can happens when find_by_query is called or if session is going to be commited
+    # It's invoked when Rubernate needs to flush modified objects.
+    # It happens when find_by_query is called or if session is going to be commited.
     def before_flush modified
     end
-
-    # Invoked if after flushing modified objects
-    # This method is invoked only if any objects has been actually flushed
+  
+    # It's invoked  if after flushing modified objects.
     def after_flush 
     end
   end

data/lib/rubernate/impl/dbi_generic.rb

@@ -59,7 +59,6 @@ module DBI
       "Impl: #{@klass}, db_url: #{@db_url}, db_user: #{@db_user}, db_password: #{@db_password}"
     end    
   end    
-
   
   TimeType = ::DBI::Timestamp  
 
@@ -116,56 +115,42 @@ module DBI
       objects = [objects] unless objects.kind_of? Array
       return if objects.empty?
       # clear r_params for objects
-      @dbh.do DELETE_PARAMS_FOR + object_ids_p(objects) 
+      clear_params objects
       # store r_params for objects
       @dbh.prepare SAVE_PARAMS do |sth|
         for object in objects
-          object.peer.each {|name, param|
+          object.__peer.each {|name, param|
             save_param sth, object, name.to_s, param
           }
         end
       end
       # clear dirty flag
       for object in objects
-        object.peer.dirty = false
+        object.__peer.dirty = false
       end        
     end
         
     # Loads object by primary_key
     def load_by_pk pk
-      klass, peer = nil
+      obj = nil
       dbh.execute SELECT_ONE_OBJECT, pk do |sth|
-        sth.fetch do |row|        
-          klass, peer = row[P_CLASS], Rubernate::Peer.new unless klass
-          fetch_param peer, row
+        lazily = lazy_factory
+        sth.fetch do |row|
+          obj = instantiate pk, row[P_CLASS], Rubernate::Peer.new unless obj
+          fetch_param obj, row, lazily
         end
       end
-      return nil unless klass      
-      obj = instantiate pk, klass, peer
-      post_load obj
+      return nil unless obj
+      post_load  obj if obj
       obj
-    end        
+    end
     
     # Loads objects by query with specified params. 
     def load_by_query query, params=[]
-      result = []
       buffer = {} # buffer for not loaded objects (whose peer is nil)
-      # selects objects and stores not loaded to buffer
-      dbh.execute(query, *params) { |sth| 
-        sth.fetch { |row|
-          obj = instantiate row[0].to_i, row[1]
-          buffer[obj.primary_key], obj.peer = obj, Rubernate::Peer.new unless obj.peer
-          result << obj
-        }        
-      }
+      result = find_buffer query, params, buffer
       return result if buffer.empty?
-      # load peers for objects in buffer.
-      dbh.execute(SELECT_PARAMS + object_ids_p(buffer.values)) {|sth|
-        sth.fetch {|row| 
-          fetch_param buffer[row[P_PK].to_i].peer, row
-        }
-      }
-      # clears dirty flags
+      load_buffer buffer
       buffer.values.each {|object| post_load object}
       result
     end
@@ -189,6 +174,35 @@ module DBI
       @dbh.disconnect rescue Log.error 'Error during disconnect in session failed state'
     end
     private
+      # Select objects from database by query and determines objects
+      # that should be loaded and put them to buffer.
+      def find_buffer query, params, buffer
+        result = []
+        dbh.execute(query, *params) do|sth| 
+          sth.fetch do |row|
+            obj = instantiate row[0].to_i, row[1]
+            buffer[obj.primary_key], obj.__peer = obj, Peer.new unless obj.__peer.is_a? Peer
+            result << obj
+          end
+        end
+        result
+      end
+      
+      # Loads objects in buffer.
+      def load_buffer buffer
+        lazily = lazy_factory
+        dbh.execute(SELECT_PARAMS + object_ids_p(buffer.values)) {|sth|
+          sth.fetch {|row|
+            fetch_param buffer[row[P_PK].to_i], row, lazily
+          }
+        }
+      end
+
+      # Delete entries corresponding to objects from r_params 
+      def clear_params objects
+        @dbh.do DELETE_PARAMS_FOR + object_ids_p(objects)
+      end
+      
       def save_param sth, obj, name, param
         case param
           when Persistent: save_ref   sth, obj, name, param
@@ -259,35 +273,48 @@ module DBI
         end
       end
       
-      def fetch_param peer, row
+      # Fetch param from db row
+      # * peer - is peer of object that is being loaded
+      # * row - database row
+      # * lazily - LazyLoader factory.
+      def fetch_param obj, row, lazily
         return unless row[P_NAME] # there are no params for this object
-        name, flags, ref = row[P_NAME].to_sym, row[P_FLAGS].to_i
-        if flags & PARAM_FLAG_ARRAY != 0
-          peer[name] = [] unless peer[name] 
-          peer[name][fetch_value(row, flags)] = ref if ref = fetch_ref_value(row)
-        elsif flags & PARAM_FLAG_HASH != 0
-          peer[name] = {} unless peer[name] 
-          peer[name][fetch_value(row, flags)] = ref if ref = fetch_ref_value(row)
+        name, flags, peer, ref = row[P_NAME].to_sym, row[P_FLAGS].to_i, obj.__peer
+        if    flags & PARAM_FLAG_ARRAY != 0   # fetch array row        
+          peer[name] = [] unless peer[name]         
+          ref = fetch_ref_value row, obj, name, lazily
+          peer[name][fetch_value(row, flags)] = ref if ref
+        elsif flags & PARAM_FLAG_HASH  != 0   # fetch hash row
+          peer[name] = {} unless peer[name]
+          ref = fetch_ref_value row, obj, name, lazily
+          peer[name][fetch_value(row, flags)] = ref if ref
+        elsif flags & PARAM_FLAG_REF   != 0   # reference row
+          ref = fetch_ref_value row, obj, name, lazily
+          peer[name] = ref if ref
         else
-          peer[name] = fetch_value row, flags
+          peer[name] = fetch_value row, flags # simple attr row
         end
-      end 
-      
+      end
+
       def fetch_value row, flags
-        return row[P_INT].to_i if flags & PARAM_FLAG_INT    != 0
-        return row[P_FLT].to_f if flags & PARAM_FLAG_FLOAT  != 0
-        return row[P_STR].to_s if flags & PARAM_FLAG_STRING != 0
-        return instantiate(row[P_REF].to_i, row[P_REF_CLASS]) if flags & PARAM_FLAG_REF != 0
-        return row[P_TIME].to_time if flags & PARAM_FLAG_TIME != 0
-        return row[P_TIME].to_date if flags & PARAM_FLAG_DATE != 0
+        return row[P_INT].to_i      if flags & PARAM_FLAG_INT    != 0
+        return row[P_FLT].to_f      if flags & PARAM_FLAG_FLOAT  != 0
+        return row[P_STR].to_s      if flags & PARAM_FLAG_STRING != 0
+        return row[P_TIME].to_time  if flags & PARAM_FLAG_TIME   != 0
+        return row[P_TIME].to_date  if flags & PARAM_FLAG_DATE   != 0
         return nil
       end
+
+      def fetch_ref_value row, obj, name, lazily
+        ref = row[P_REF]
+        return nil unless ref
+        ref_obj = instantiate ref, row[P_REF_CLASS]
+        unless ref_obj.__peer.is_a? Rubernate::Peer
+          ref_obj.__peer = lazily.create obj.primary_key, name 
+        end
+        ref_obj
+      end
       
-      def fetch_ref_value row
-        ref_pk = nil
-        instantiate ref_pk, row[P_REF_CLASS] if ref_pk = row[P_REF]
-      end      
-            
       def object_ids objects
         ids = objects.collect {|o| o.primary_key}
         ids.uniq!

data/lib/rubernate/impl/dbi_mysql.rb

@@ -18,10 +18,10 @@ module DBI
     
     # Creates record in r_objects for specified object
     def create object
-      object.peer = Rubernate::Peer.new
+      object.__peer = Rubernate::Peer.new unless object.__peer 
       @dbh.do CREATE_PEER, object.class.name
       object.primary_key = @dbh.select_one(SELECT_NEXT_PK)[0].to_i
-      object.peer.dirty = true
+      object.__peer.dirty = true
       object.primary_key
     end            
   end

data/lib/rubernate/impl/dbi_oracle.rb

@@ -10,12 +10,38 @@ module DBI
           
     # Creates record in r_objects for specified object
     def create object
-      object.peer = Rubernate::Peer.new
+      object.__peer = Rubernate::Peer.new unless object.__peer 
       object.primary_key = @dbh.select_one(SELECT_NEXT_PK)[0].to_i
       @dbh.do CREATE_PEER, object.primary_key, object.class.name
-      object.peer.dirty = true
+      object.__peer.dirty = true
       object.primary_key
     end            
-  end  
+    
+    private
+      # Oracle requires that IN list must be less or equal to 1000 items
+      def clear_params objects
+        return super if objects.size <= 1000
+        idx = 0
+        while chunck = objects.slice(idx, 1000)
+          break if chunck.empty?
+          super chunck
+          idx+= chunck.size
+        end
+      end
+
+      # Oracle requires that IN list must be less or equal to 1000 items
+      def load_buffer buffer
+        return super if buffer.size <= 1000
+        until buffer.empty?
+          chunck = {}
+          for i in 1..1000
+            break if buffer.empty?
+            pk, obj = buffer.shift
+            chunck[pk] = obj
+          end
+          super chunck
+        end
+      end 
+  end
 end
 end

data/lib/rubernate/impl/dbi_pg.rb

@@ -16,10 +16,10 @@ module DBI
      
     # Creates record in r_objects for specified object
     def create object
-      object.peer = Rubernate::Peer.new
+      object.__peer = Rubernate::Peer.new unless object.__peer 
       object.primary_key = @dbh.select_one(SELECT_NEXT_PK)[0].to_i
       @dbh.do CREATE_PEER, object.primary_key, object.class.name
-      object.peer.dirty = true
+      object.__peer.dirty = true
       object.primary_key
     end
 

data/lib/rubernate/impl/memory.rb

@@ -2,10 +2,10 @@ require 'rubernate/queries'
 
 module Rubernate
 # This module contains implementation of Runtime that operates with memory instead database.
-# It is intended only of testing.
-module Memory
-  module Queries
-    class Query < Rubernate::Queries::Expr 
+# It is intended only for testing.
+module Memory # :nodoc:
+  module Queries #:nodoc:
+    class Query < Rubernate::Queries::Expr #:nodoc:
       def params v
         case v
           when Array: v
@@ -15,7 +15,7 @@ module Memory
       end
     end
     
-    class Factory < Rubernate::Queries::Factory
+    class Factory < Rubernate::Queries::Factory # :nodoc:
       def initialize
         super
         @query = Query        
@@ -23,7 +23,7 @@ module Memory
     end
   end
   
-  class Reference
+  class Reference #:nodoc:
     attr_reader  :primary_key, :object_class
     def initialize pk, klass
       @primary_key, @object_class = pk, klass
@@ -35,7 +35,7 @@ module Memory
     end
   end
   
-  class Configuration
+  class Configuration # :nodoc:
     attr_accessor :database
     def initialize
       @pk, @database = 1001, {}
@@ -48,9 +48,11 @@ module Memory
     end
   end
   
-  class Runtime < Rubernate::Runtime
+  class Runtime < Rubernate::Runtime # :nodoc:
     attr_accessor :pk, :database
     
+    @@lazy_loader = LazyLoader.new
+    
     # Database is maps {pk => [class, {attr => value}]}
     def initialize database, pk_seq
       super()
@@ -86,13 +88,13 @@ module Memory
     def load_param p_data
       case p_data
         when Reference: 
-          instantiate p_data.primary_key, p_data.object_class
+          instantiate p_data.primary_key, p_data.object_class, @@lazy_loader
         when Array: 
           p_data.collect{|ref| instantiate(ref.primary_key, ref.object_class)}
         when Hash:
           result = {}
           p_data.each_pair {|key, ref| 
-            result[key] = instantiate(ref.primary_key, ref.object_class)
+            result[key] = instantiate ref.primary_key, ref.object_class, LazyLoader.new
           }
           result
         when Fixnum 
@@ -106,13 +108,13 @@ module Memory
       objects = [objects] unless objects.kind_of? Array
       for object in objects
         @database[object.primary_key] = [object.class, save_peer(object)]
-        object.peer.dirty = false
+        object.__peer.dirty = false
       end
     end
     
     def save_peer obj
       result = {}
-      obj.peer.each {|key, value| result[key] = save_param obj, key, value}
+      obj.__peer.each {|key, value| result[key] = save_param obj, key, value}
       result
     end
     

data/lib/rubernate/init/init_mysql.rb

@@ -24,10 +24,10 @@ module DBI
           CONSTRAINT R_REF_FK   FOREIGN KEY (REF_VALUE) REFERENCES R_OBJECTS(OBJECT_PK) ON DELETE CASCADE)  ENGINE=InnoDB;
         }.gsub(INDENT, '')
     CREATE_INDEX_O_PK_CLASS = %q{
-        CREATE INDEX R_O_PK_CLASS ON R_OBJECTS (OBJECT_PK   ASC, OBJECT_CLASS);
+        CREATE INDEX R_O_PK_CLASS ON R_OBJECTS (OBJECT_PK, OBJECT_CLASS);
         }.gsub(INDENT, '')
     CREATE_INDEX_P_PK_NAME  = %q{
-        CREATE INDEX R_P_PK_NAME ON R_PARAMS (OBJECT_PK   ASC, NAME);
+        CREATE INDEX R_P_PK_NAME ON R_PARAMS (OBJECT_PK, NAME);
         }.gsub(INDENT, '')
         
     TEMPLATE = %q{

data/lib/rubernate/init/init_oracle.rb

@@ -24,10 +24,10 @@ module DBI
           CONSTRAINT R_REF_FK   FOREIGN KEY (REF_VALUE) REFERENCES R_OBJECTS(OBJECT_PK) ON DELETE CASCADE)    
         }.gsub(INDENT, '')
     CREATE_INDEX_O_PK_CLASS = %q{
-        CREATE INDEX R_O_PK_CLASS ON R_OBJECTS (OBJECT_PK   ASC, OBJECT_CLASS)
+        CREATE INDEX R_O_PK_CLASS ON R_OBJECTS (OBJECT_PK, OBJECT_CLASS)
         }.gsub(INDENT, '')
     CREATE_INDEX_P_PK_NAME  = %q{
-        CREATE INDEX R_P_PK_NAME ON R_PARAMS (OBJECT_PK   ASC, NAME)
+        CREATE INDEX R_P_PK_NAME ON R_PARAMS (OBJECT_PK, NAME)
         }.gsub(INDENT, '')
     CREATE_R_PK_SEQUENCE = %q{
         CREATE SEQUENCE R_PK_SEQUENCE START WITH 1001 INCREMENT BY 1

data/lib/rubernate/lazyload.rb

@@ -0,0 +1,63 @@
+module Rubernate
+  # Base class and default implementation for lazy loaders.
+  # Loads each objects separately.
+  class LazyLoader
+    def load_lazy obj
+      Rubernate::Log.debug {"load-lazy, pk: #{obj.primary_key}"}
+      Rubernate.runtime.find_by_pk obj.primary_key, true
+    end    
+    # Creates LazyLoader
+    # * obj_pk  - object that holds reference to object that is supposed to be load lazily.
+    # * p_name - name of reference(or collection) parameter that referes to object that is to be loaded lazily.
+    def create obj_pk, p_name
+      @@single_lazy_loader
+    end    
+  end
+  
+  # Factory for LazyLoader default implementation
+  class LazyLoaderFactory
+    # All instances of LazyLoader are similzr so only one instance is used
+    def create obj_pk, p_name
+      @@single_lazy_loader  
+    end
+    @@single_lazy_loader = LazyLoader.new
+  end
+  
+  # Loads all objects that are holded by the same collection as the object that is  loaded
+  class ParamLazyLoader < LazyLoader
+    PRE_LOAD = 'select distinct ref_value from r_params where object_pk = ? and name = ?'
+    def initialize referer_pk, ref_param
+      @referer_pk, @ref_param = referer_pk, ref_param
+    end
+    def load_lazy obj
+      Rubernate::Log.debug {"load-lazy, referer: #{@referer_pk}, reference: #{@ref_param}"}
+      Rubernate.find_by_query PRE_LOAD, [@referer_pk, @ref_param.to_s]
+    end
+  end
+  
+  class ParamLazyLoaderFactory
+    def create obj_pk, p_name
+      @cache = {} unless @cache
+      @cache[[obj_pk, p_name]] ||= ParamLazyLoader.new obj_pk, p_name
+    end
+  end
+  
+  # Loads all objects that are refered by the same object as the object that is  loaded
+  class HolderLazyLoader < LazyLoader
+    PRE_LOAD = 'select distinct ref_value from r_params where object_pk = ?'
+    def initialize referer_pk
+      @referer_pk = referer_pk
+    end
+    def load_lazy obj
+      Rubernate::Log.debug {"load-lazy, referer: #{@referer_pk}"}
+      Rubernate.find_by_query PRE_LOAD, [@referer_pk]
+    end
+  end  
+  
+  class HolderLazyLoaderFactory
+    def create obj_pk, p_name
+      @cache = {} unless @cache
+      @cache[obj_pk] ||= HolderLazyLoader.new obj_pk
+    end
+  end
+end

data/lib/rubernate/mixins.rb

@@ -2,10 +2,12 @@ require 'set'
 
 class Module
   # Finds class defined in current module.
-  # :call-seq:
+  #
+  # :call-seq: find_class(name, scaned = Set.new)
+  #
   #   Module.find_class 'ClassName' # finds class 'ClassName' in global space
   #   SomeModule.find_class 'ClassName' # finds class 'ClassName' in module SomeModule
-  #   
+  #
   def find_class name, scaned = Set.new
     scaned << self
     for unit in module_units - scaned
@@ -64,12 +66,12 @@ class Class
     module_eval %{
       def #{name}                
         ensure_loaded
-        peer[:#{name}]
+        @__peer[:#{name}]
       end
 
       def #{name}= value
         ensure_loaded
-        peer.set :#{name}, value, &on_change_callback
+        @__peer.set :#{name}, value, &on_change_callback
       end
     }
   end

data/lib/rubernate/persistent.rb

@@ -25,29 +25,28 @@ module Persistent
   def removed?
     @removed
   end
+
+  # Checks if object has been modified.
+  def dirty?
+    return false unless @__peer.is_a? Peer
+    @__peer.dirty? &on_modify_callback
+  end
   
   # Retruns objects peer if ther is one or nil in other case 
-  def peer
-    @peer
+  # This method is implementation detail. Users are not supposed to use it.
+  def __peer # :nodoc:
+    @__peer
   end
   
   # Sets peer if there is no one and invokes on_load callback else skip.
   # If value is nil peer will be lazy initialized in ensure_loaded.
-  # This method should be invoked only once with not nil value.
-  def peer= value
-    return if @peer
-    if value
-      disable_ensure
+  # This method should be invoked only once with not nil value.            # TODO: rdoc on lazy loaders
+  def __peer= value # :nodoc:
+    if @__peer
+      @__peer = value unless value.is_a? LazyLoader
     else
-      def self.ensure_loaded
-        Rubernate.runtime.find_by_pk @primary_key, true
-      end
+      @__peer = value
     end
-    @peer = value
-  end
-
-  def dirty?
-    peer.dirty? &on_modify_callback
   end
   
   # Defines metod == in for rubernated classes
@@ -61,13 +60,14 @@ module Persistent
   end
 
   private
-    def ensure_loaded
-      self.peer = Peer.new
-    end  
-
-    def disable_ensure
-      def self.ensure_loaded
+    def ensure_loaded      
+      return if @__peer.is_a? Peer # Object has already been initialized              
+      if @__peer.is_a? LazyLoader 
+        @__peer.load_lazy self # LazyLoader
+      else
+        @__peer = Peer.new # Default peer.
       end
+      raise "lazy loading fails, peer is #{@__peer}" unless @__peer.is_a? Peer
     end
     
     def on_modify_callback