Rubernate 0.1.5 → 0.1.6

data/lib/rubernate/queries.rb

@@ -48,7 +48,13 @@ module Queries
     end
   end
 
-  # Factory method, creates queries based on Generic factory. 
+  # Factory method, creates queries using stardart factory.
+  #
+  # :call-seq:
+  #
+  # q = Rubernate::Queries.query "Select :o; Where o.prop.str == :value"
+  # puts q.to_sql
+  #   
   def self.query q_text=nil, &q_block
     if block_given?
       @@generic_factory.query(&q_block)
@@ -68,7 +74,7 @@ module Queries
   # 
   # New implementations of elements MUST accept factory as it's first parameter.
   class Factory
-    attr_reader :cache # Queries cache. TODO: limit size!
+    attr_reader :cache # Queries cache. TODO: limit cache size!
     # Initalizes default implementations
     def initialize
       @expr     = Expr
@@ -102,7 +108,6 @@ module Queries
       end
   end
 
-  # Contains classes for standart ANSY SQL.
   # Represent abstract expression
   class Expr
     include Operations
@@ -145,7 +150,7 @@ module Queries
       end
   end  
   
-  # Represents constraint for one columns.
+  # Represents constraint for one column.
   class UnOpConstr < Expr
     def initialize factory, expr, op, braces = false
       @factory, @op, @braces = factory, op, braces
@@ -169,7 +174,7 @@ module Queries
     end
   end
   
-  # Represent constraint that applied on two columns.
+  # Represent constraint applied on two columns.
   class BinOpConstr < Expr
     def initialize factory, expr1, expr2, sign, braces = false
       @factory, @sign, @braces = factory, sign, braces
@@ -196,7 +201,8 @@ module Queries
     end
   end  
   
-  # Represent expression with table's field
+  # Represent expression with tabls field such as
+  # <tt>r_params.name</tt> or <tt>r_objects.object_class</tt>
   class FieldExpr < Expr    
     def initialize factory, table, field
       @factory, @table, @field, @markers = factory, table, field, []
@@ -216,7 +222,7 @@ module Queries
     end
   end
   
-  # Represent r_params for hashes and arrays constrained by key
+  # Represents r_params for hashes and arrays constrained by key
   class KeyRefExpr < BinOpConstr
     def initialize factory, r_param, key_field, key_value
       @factory, @r_param, @key_field, @key_value = factory, r_param, key_field, key_value
@@ -227,7 +233,7 @@ module Queries
     end
   end
 
-  # Reresents List of expressions
+  # Reresents collection of expressions
   class ExprsList < Expr
     def initialize factory, list
       @factory, @exprs = factory, list.collect{|expr| Expr === expr ? expr : factory.expr(expr)}
@@ -243,7 +249,7 @@ module Queries
     end
   end
   
-  # Represents r_params table
+  # Represents <tt>r_params</tt> table
   class RParam < Expr
     include Rubernate::DBI
     
@@ -260,15 +266,31 @@ module Queries
       @r_object.to_sql + @p_name
     end
     
-    # Fields accessors.
+    # Creates  accessor to +r_params.primary_key+.
     def pk   () f_expr 'object_pk'; end
+
+    # Creates accessor to +r_params.int_value+.
     def int  () f_expr 'int_value'; end
+
+    # Creates accessor to +r_parms.flt_value+.
     def float() f_expr 'flt_value'; end
+
+    # Creates accessor to +r_parms.str_value+.
     def str  () f_expr 'str_value'; end
+
+    # Creates accessor to +r_parms.dat_value+ with appropriate converison  to time if needed.
     def time () f_expr 'dat_value'; end
+
+    # Creates accessor to +r_parms.dat_value+ with appropriate converison  if needed.
     def date () f_expr 'dat_value'; end
+
+    # Creates accessor to +r_parms.ref_value+.
     def ref  () f_expr 'ref_value'; end
+
+    # Creates accessor to +r_parms.flags+.
     def flags() f_expr 'flags';     end
+
+    # Creates accessor to +r_parms.name+.
     def name () f_expr 'name';      end
     
     # The following methods checks r_param.flags value. (r_param.flags)
@@ -304,7 +326,7 @@ module Queries
       end
   end
   
-  # Represent r_objects table
+  # Represent <tt>r_objects</tt> table
   class RObject < Expr 
     # Init Table accepts query and name of table
     def initialize factory, name

data/lib/rubernate/runtime.rb

@@ -1,4 +1,6 @@
-module Rubernate
+require 'rubernate/lazyload'
+
+module Rubernate    
   # Base class for all Runtime implementations.
   class Runtime
     include Callbacks::Runtime
@@ -6,13 +8,18 @@ module Rubernate
     # Log for Runtime events
     Log = Rubernate::Log
 
+    # Runtime scope settings
+    attr_reader :settings
+
     def initialize
       @pool = {} # Contains objects loaded during the session
-      @factory = Queries::Factory.new
-    end
+      @@factory = Queries::Factory.new unless @@factory
+      @factory  = @@factory                            
+      @settings = Hash.new {|hash, key| hash[key] = Rubernate.settings[key]}
+    end    
+    @@factory = nil
     
-    # Finds object by primary key,
-    #    raises ObjectNotFoundException if object is not found
+    # Finds object by primary key.  Raises ObjectNotFoundException if object is not found
     def find_by_pk pk, load = false
       result = @pool[pk]
       unless result
@@ -28,13 +35,14 @@ module Rubernate
       result
     end
     
-    # Finds objects by query. Returns ordered list of objects.
-    # If +params+ if Array the query will be treated as native sql
-    #   and won't be processed.
+    # Finds objects by query. Returns ordered list of objects or empty one if no objects was found.
+    # The query can be one of two types.
+    # * native sql - in this case +params+ should be of type Array.
+    # * query language - +params+ shoud be of type Hash.
     def find_by_query query, params={} #TODO: improve working with paramters
       flush_modified
       params = case params
-        when Hash: params
+        when Hash : params
         when Array: params
         else [params]
       end
@@ -54,7 +62,7 @@ module Rubernate
     # primary key already loaded in session.
     def attach object
       raise "Can't attach object: #{object.primary_key}" if @pool.has_key? object.primary_key
-      object.peer = Peer.new unless object.peer
+      object.__peer = Peer.new unless object.__peer
       create object
       @pool[object.primary_key] = object
       Log.debug {"Attach #{object.class.name}: #{object.primary_key} to session"}
@@ -75,13 +83,13 @@ module Rubernate
         raise
     end
 
-    # Begins session
+    # Begins session and transaction.
     def begin
       Log.debug {"Begin session #{self}"}
       on_begin      
     end
     
-    # Persist all changes and Commit transction.
+    # Persist all changes and commit transction.
     def commit
       before_commit # callback 
       flush_modified
@@ -93,7 +101,7 @@ module Rubernate
         raise
     end
     
-    # Discard all changes and Rollback transaction.
+    # Discard all changes and rollback transaction.
     def rollback ex='not specified'
       on_rollback # callback
       Log.warn {"Rollback session #{self} due to error: #{ex}"}
@@ -103,7 +111,10 @@ module Rubernate
         raise
     end
 
-    # Flushes modified objects. Invokes on_store callback before storing.
+    # Stores modified objects to database. This method is invoked before 
+    # transaction commit and before each invokation of Runtime.find_by_query. 
+    # You can invoke this method manually if you want to store all changes of your
+    # objects to database immediately.    
     def flush_modified      
       objects = modified
       before_flush modified # callback
@@ -116,8 +127,9 @@ module Rubernate
 
     private     
       # Creates new object instance or returns insance from pool
-      # Parameter klass can be Class or String (class name)
-      def instantiate pk, klass, peer = nil
+      #  * klass - can be Class or String (class name)
+      #  * peer  - can be Peer, LazyLoader or nill
+      def instantiate pk, klass, peer = nil 
         object = @pool[pk]
         unless object
           clazz  = klass.is_a?(Class) ? klass : get_class(klass)
@@ -125,10 +137,10 @@ module Rubernate
           object.primary_key = pk
           @pool[pk] = object
         end
-        object.peer = peer # TODO: TEST!!! and write description
+        object.__peer = peer if peer
         object
-      end
-       
+      end     
+
       #Classes cache.
       @@classes = {}
 
@@ -141,17 +153,27 @@ module Rubernate
         @@classes[name] = klass
       end
       
+      # Returns LazyLoaderFactory instance.
+      def lazy_factory
+        case settings[:lazy_load]
+          when :holder:    HolderLazyLoaderFactory.new
+          when :collection: ParamLazyLoaderFactory.new
+          when :separately, nil: LazyLoaderFactory.new
+          else "wrong value for setting :lazy_load - #{settings[:lazy_load]}"
+        end
+      end
+      
       # Returns modified objects.
       def modified
-        @pool.values.find_all {|object| object.peer and object.dirty?}
+        @pool.values.find_all {|object| object.__peer and object.dirty?}
       end
       
-      # Callback functions invoked when session successfully closed
+      # Callback functions it's invoked when session successfully closed
       # Should be overriden by subclasses to perform implement closing logic
       def close
       end
       
-      # Callback functions invoked when session fails
+      # Callback functions it's invoked when session fails.
       # Should be overriden by subclasses to cleanup resources
       def failed
       end
@@ -203,10 +225,10 @@ module Rubernate
       end
       
       def post_load object
-        for value in object.peer.values
+        for value in object.__peer.values
           value.compact! if value.is_a? Array
         end      
-        object.peer.dirty = false
+        object.__peer.dirty = false
         object.on_load
       end
       
@@ -221,10 +243,10 @@ module Rubernate
           when Class: p.name
           else p
         end
-      end      
+      end
   end
-
-  # Represetns Dummy Persistent. - objects whose class wasn't found during loading.
+  
+  # Represetns object whose class wasn't found during loading.
   class DummyPersistent
     persistent
     def initialize class_name

data/lib/rubernate.rb

@@ -41,8 +41,8 @@ module Rubernate
   # Rubernate core singelton methods.
   class << self
     # Allows you setup Rubernate by yours implementaion of Configuration.
-    # See also method config
-    def configuration= config
+    # See also method config 
+    def configuration= config # :nodoc:
       Log.info "Rubernate configured by #{config}"
       @factory = config
     end
@@ -63,37 +63,14 @@ module Rubernate
       self.configuration = DBI::Configuration.new impl, init, url, user, password
     end
     
-    # Loads MySQL module
-    def require_mysql
-      require 'rubernate/impl/dbi_mysql'
-      require 'rubernate/init/init_mysql'
-      [DBI::MySqlRuntime, DBI::MySqlInit.new]
-    end
-
-    # Loads Oracle module
-    def require_oracle
-      require 'rubernate/impl/dbi_oracle'
-      require 'rubernate/init/init_oracle'    
-      [DBI::OracleRuntime, DBI::OracleInit.new]
-    end
-    
-    # Loads Postgres module
-    def require_pg
-      require 'rubernate/impl/dbi_pg'
-      require 'rubernate/init/init_pg'
-      [DBI::PgRuntime, DBI::PgInit.new]
-    end
-    
-    # Loads Memory module used only for testing
-    def require_memory
-      require 'rubernate/impl/memory'
-      Memory::Runtime
-    end
         
     # Intializes database - creates necessary tables, sequences and indices.
     def init_db
       @factory.init_db
     end
+
+    # Global scope settings
+    attr_reader :settings    
     
     # Returns Runtime object associated with current session 
     # or nil if session does not excists
@@ -108,8 +85,9 @@ module Rubernate
       Thread.current[:Rubernate] != nil
     end
     
-    # Begins new Rubernate session
+    # Begins new  session and transaction in database. Returns Runtime object or supply it to block if one is given.
     def session
+      raise 'No config found. Call Rubernate.config first.' unless @factory
       runtime = @factory.create
       Thread.current[:Rubernate] = runtime
       runtime.begin
@@ -125,19 +103,59 @@ module Rubernate
       end
       result
     end 
-  end
+    private
+      # Loads MySQL module 
+      def require_mysql # :nodoc:  
+        require 'rubernate/impl/dbi_mysql'
+        require 'rubernate/init/init_mysql'
+        [DBI::MySqlRuntime, DBI::MySqlInit.new]
+      end
 
-  # Shortcut method can be used instead of Rubernate.runtime.find_by_pk
+      # Loads Oracle module 
+      def require_oracle # :nodoc:  
+        require 'rubernate/impl/dbi_oracle'
+        require 'rubernate/init/init_oracle'    
+        [DBI::OracleRuntime, DBI::OracleInit.new]
+      end
+      
+      # Loads Postgres module 
+      def require_pg # :nodoc:
+        require 'rubernate/impl/dbi_pg'
+        require 'rubernate/init/init_pg'
+        [DBI::PgRuntime, DBI::PgInit.new]
+      end
+      
+      # Loads Memory module used only for testing :nodoc: 
+      def require_memory #  :nodoc: 
+        require 'rubernate/impl/memory'
+        Memory::Runtime
+      end  
+  end
+  @settings = {} 
+  
+  # Finds object by primary key. This method is actually shortcut to Runtime.find_by_pk
   def find_by_pk pk
     Rubernate.runtime.find_by_pk pk
   end
 
-  # Shortcut method can be used instead of Rubernate.runtime.find_by_query
+  # Finds object by query. This method is actually shortcut to Runtime.find_by_query
+  # Retruns array of objects, accepts native sql or query language expressions.
+  # If query is sql then +params+ should be array as in DBI. Else it should be Hash of <tt>{:maker=>value}</tt>.
+  #
+  #   :call-seq: find_by_query(query, params={})
+  #
+  #      Rubernate.find_by_query 'Select :p; Where p.name.str == :name', :name => 'Andy'
+  #      
+  #      #Or the same using native sql.
+  #      Rubernate.find_by_query  "select p_.* from r_objects p_ left outer join  r_params p_name 
+  #             on (p_.object_pk = p_name.object_pk)
+  #         where p_name.name = 'name' and p_name.str_value = ?", ['Andy'] 
+  #
   def find_by_query query, params={}
     Rubernate.runtime.find_by_query query, params
   end
   
-  # Shortcut method can be used instead of Rubernate.runtime
+  # Returns current runtime object.
   def runtime
     Rubernate.runtime
   end

data/tests/config.rb

@@ -1,15 +1,17 @@
 # Set to true to run tests on Oracle
 $run_oracle_tests   = false
 
-ORA_RUNTIME_CLASS   = Rubernate.require_oracle[0]
-ORA_DB_URL          = 'dbi:OCI8:dbg91'
+module Rubernate
+  
+ORA_RUNTIME_CLASS   = require_oracle[0]
+ORA_DB_URL          = 'dbi:OCI8:nc65db'
 ORA_DB_USER         = 'netcracker65'
 ORA_DB_PWD          = 'netcracker65'
 
 # Set to true to run tests on MySQL
 $run_mysql_tests    = false
 
-MYSQL_RUNTIME_CLASS = Rubernate.require_mysql[0]
+MYSQL_RUNTIME_CLASS = require_mysql[0]
 MYSQL_DB_URL        = 'dbi:Mysql:rubernate_db:localhost'
 MYSQL_DB_USER       = nil
 MYSQL_DB_PWD        = nil
@@ -17,12 +19,13 @@ MYSQL_DB_PWD        = nil
 # Set to true to run tests on PostgreSQL
 $run_pg_tests       = false
 
-PG_RUNTIME_CLASS    = Rubernate.require_pg[0]
+PG_RUNTIME_CLASS    = require_pg[0]
 PG_DB_URL           = 'dbi:Pg:rubernate_db'
 PG_DB_USER          = 'rn_test'
 PG_DB_PWD           = 'rn_password'
 
-Rubernate.require_memory
+require_memory
+end
 
 # Log4r configuration
 Rubernate::Log.level = Log4r::DEBUG