Rubernate 0.1.0

data/README

@@ -0,0 +1,30 @@
+== Rubernate
+
+Rubernate is an object-oriented storage for Ruby objects based on relational database model.
+
+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 
+fixed set of tables.
+
+This approach has following advantages:
+
+* Simplicity - it simplifies greatly persistent classes creation and their modifications, too, because 
+it prevents database structure changes.
+
+* Reusability - as persistence doesn't depend on database structure its possible to reuse objects in different projects.
+
+* Object oriented storage - it is possible to put conditions on objects classes during a search.
+
+Rubernate has following features:
+
+* Classes can have persistent parameters of following types: Integer, String, Date, Time, Reference to Persistent Object, Array of References, Hash of References with key of type Integer or String or Date or Time.
+
+* Built-in query language and support for native queries 
+
+* Support for Oracle and MySQL.
+ 
+* Can be used independently or with other ORM like ActiveRecord
+
+* Extendable architecture - can be easily extended by user functionality.
+

data/db/mysql.sql

@@ -0,0 +1,35 @@
+/**
+ * Creates Rubernate tables for MySQL database.
+ * Copyright (C) 2006 Andrey Ryabov <andrey_ryabov@bk.ru>
+ */
+
+# Creates database named rubernate_db change name and uncomment if necessary
+#   CREATE DATABASE RUBERNATE_DB;
+#   USE RUBERNATE_DB;
+
+
+DROP TABLE IF EXISTS R_PARAMS;
+DROP TABLE IF EXISTS R_OBJECTS;
+
+CREATE TABLE R_OBJECTS (
+    OBJECT_PK       INTEGER(20)     PRIMARY KEY AUTO_INCREMENT,
+    OBJECT_CLASS    VARCHAR(100)    NOT NULL) ENGINE=InnoDB;
+
+CREATE TABLE R_PARAMS (
+    OBJECT_PK       INTEGER(20)     NOT NULL,
+    NAME            VARCHAR(100)    NOT NULL,
+    FLAGS           INTEGER(5)      NOT NULL,
+    INT_VALUE       INTEGER(20),
+    STR_VALUE       VARCHAR(255),
+    DAT_VALUE       DATETIME,
+    REF_VALUE       INTEGER(20),
+  CONSTRAINT R_PARAM_FK FOREIGN KEY (OBJECT_PK) REFERENCES R_OBJECTS(OBJECT_PK) ON DELETE CASCADE,
+  CONSTRAINT R_REF_FK   FOREIGN KEY (REF_VALUE) REFERENCES R_OBJECTS(OBJECT_PK) ON DELETE CASCADE)  ENGINE=InnoDB;
+
+CREATE INDEX R_O_PK_CLASS ON R_OBJECTS (OBJECT_PK   ASC, OBJECT_CLASS);
+CREATE INDEX R_P_PK_NAME ON R_PARAMS (OBJECT_PK   ASC, NAME);
+
+
+/**
+ * End
+ */

data/db/oracle.sql

@@ -0,0 +1,29 @@
+/**
+ * Creates Rubernate tables for Oracle database.
+ * Copyright (C) 2006 Andrey Ryabov <andrey_ryabov@bk.ru>
+ */
+
+CREATE TABLE R_OBJECTS (
+    OBJECT_PK       NUMBER(20)      PRIMARY KEY,
+    OBJECT_CLASS    VARCHAR2(100)   NOT NULL) 
+/
+CREATE TABLE R_PARAMS (
+    OBJECT_PK       NUMBER(20)    NOT NULL,
+    NAME            VARCHAR2(100) NOT NULL,
+    FLAGS           NUMBER(5)     NOT NULL,
+    INT_VALUE       NUMBER(20),
+    STR_VALUE       VARCHAR2(1000),
+    DAT_VALUE       DATE,
+    REF_VALUE       NUMBER(20),
+  CONSTRAINT R_PARAM_FK FOREIGN KEY (OBJECT_PK) REFERENCES R_OBJECTS(OBJECT_PK) ON DELETE CASCADE,
+  CONSTRAINT R_REF_FK   FOREIGN KEY (REF_VALUE) REFERENCES R_OBJECTS(OBJECT_PK) ON DELETE CASCADE)
+/
+CREATE INDEX R_O_PK_CLASS ON R_OBJECTS (OBJECT_PK   ASC, OBJECT_CLASS)
+/
+CREATE INDEX R_P_PK_NAME ON R_PARAMS (OBJECT_PK   ASC, NAME)
+/
+CREATE SEQUENCE R_PK_SEQUENCE START WITH 1001 INCREMENT BY 1
+/
+/**
+ * End
+ */

data/lib/rubernate/callbacks.rb

@@ -0,0 +1,70 @@
+module Rubernate
+
+# This module is holder for other callback modules.
+# 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 module Rubernate::Entity
+  module Entity
+    # Invoked if object has just been created in database.
+    def on_create
+    end
+
+    # Invoked when object is about to be removed from database.
+    def on_remove
+    end
+
+    # Invoked when object is about to be stored in database.
+    def on_save
+    end
+
+    # Invoked if object has just been loaded from database.
+    def on_load
+    end
+
+    # Invoked if property of object has just been reassigned by +=+ operator.
+    def on_change prop_name, old_value, new_value
+    end
+
+    # 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
+    # TODO: implement invokations
+    def on_lose_ref refered_by
+    end
+  end
+ 
+  # This module contains callback method and 
+  # included in class Rubernate::Runtime. 
+  module Runtime
+    # Invoked on session creation.
+    def on_begin
+    end
+
+    # Invoked if session is about to be rolled back.
+    def on_rollback
+    end
+
+    # Invoked if session is about to be commited.
+    def before_commit
+    end
+
+    # Invoked if session 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
+    def before_flush modified
+    end
+
+    # Invoked if after flushing modified objects
+    # This method is invoked only if any objects has been actually flushed
+    def after_flush 
+    end
+  end
+end
+end

data/lib/rubernate/entity.rb

@@ -0,0 +1,85 @@
+module Rubernate
+
+# This module contains methods that will be included into persistent objects
+module Entity
+  include Rubernate
+  include Callbacks::Entity
+
+  # This property holds objects primary key.
+  # The primary key is not +nil+ for objects attached to session.
+  attr :primary_key, true
+  
+  # Attaches object to session returns self
+  def attach
+    Rubernate.runtime.attach self
+    self
+  end
+
+  # Deletes object.
+  def remove!
+    Rubernate.runtime.remove self
+    @removed = true
+  end
+  
+  # Checks if object has been removed in current session
+  def removed?
+    @removed
+  end
+  
+  # Retruns objects +peer+ if ther is one or +nil+ in other case 
+  def peer
+    @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
+    else
+      def self.ensure_loaded
+        Rubernate.runtime.find_by_pk @primary_key, true
+      end
+    end
+    @peer = value
+  end
+
+  def dirty?
+    peer.dirty? &on_modify_callback
+  end
+  
+  # Defines metod == in for rubernated classes
+  def self.included klass
+    klass.module_eval %{
+      def == other
+        return self.primary_key == other.primary_key if other.is_a? Entity
+        super
+      end
+    }
+  end
+
+  private
+    def ensure_loaded
+      self.peer = Peer.new
+    end  
+
+    def disable_ensure
+      def self.ensure_loaded
+      end
+    end
+    
+    def on_modify_callback
+      @__on_modify_callback ||= proc {|p_name, old_value, new_value|
+        on_modify p_name, old_value, new_value # callback
+      }
+    end
+    
+    def on_change_callback
+      @__on_change_callback ||= proc {|p_name, old_value, new_value|
+        on_change p_name, old_value, new_value # callback
+      }      
+    end
+end
+end

data/lib/rubernate/impl/dbigeneric.rb

@@ -0,0 +1,286 @@
+require 'dbi'
+require 'time'
+
+module Rubernate
+module DBI
+  # Param flags constants
+  PARAM_FLAG_INT      =    (1 << 0).to_i
+  PARAM_FLAG_STRING   =    (1 << 1).to_i
+  PARAM_FLAG_TIME     =    (1 << 2).to_i
+  PARAM_FLAG_DATE     =    (1 << 3).to_i
+  PARAM_FLAG_REF      =    (1 << 4).to_i
+  PARAM_FLAG_ARRAY    =    (1 << 5).to_i
+  PARAM_FLAG_HASH     =    (1 << 6).to_i
+
+  # Array and Hashs combinations
+  ARRAY_INT_REF       = (PARAM_FLAG_ARRAY | PARAM_FLAG_INT).to_i
+  HASH_INT_REF        = (PARAM_FLAG_HASH  | PARAM_FLAG_INT).to_i
+  HASH_STRING_REF     = (PARAM_FLAG_HASH  | PARAM_FLAG_STRING).to_i
+  HASH_TIME_REF       = (PARAM_FLAG_HASH  | PARAM_FLAG_TIME).to_i
+  HASH_DATE_REF       = (PARAM_FLAG_HASH  | PARAM_FLAG_DATE).to_i
+  
+  # Represents factory for +Runtime+ implementors.
+  class RuntimeFactory
+    # Accepts +Runtime+ impl. class, database url, user name, and user password
+    def initialize klass, db_url, db_user, db_password
+      @klass, @db_url, @db_user, @db_password = klass, db_url, db_user, db_password
+      # @params = {'AutoCommit' => false} #TODO: refine  
+    end
+        
+    # Creates initialized PeerHost
+    def create
+      @klass.new connect     
+    end
+    
+    # Creates connection and pass it in block if present 
+    # else return it if there is no block given.
+    def connect
+      return ::DBI.connect(@db_url, @db_user, @db_password, @params) unless block_given?
+      ::DBI.connect(@db_url, @db_user, @db_password, @params) { |dbh| yield dbh }
+    end
+    
+    def to_s
+      "runtime impl: #{@klass}, db_url: #{@db_url}, db_user: #{@db_user}, db_password: #{@db_password}"
+    end    
+  end    
+
+  # Represent base class for all Runtime implementation.
+  # Contains generic sql implementations of all required methods except +create+.
+  # The +create+ method should be implemented in subclasses.
+  class Runtime < Rubernate::Runtime
+    include DBI
+
+    # Parameters are deleted automatically with corresponding r_object records    
+    #DELETE_PARAMS = <<-SQL    
+    #    DELETE FROM R_PARAMS WHERE OBJECT_PK = ? 
+    #    SQL
+    DELETE_PARAMS_FOR = <<-SQL    
+        DELETE FROM R_PARAMS WHERE OBJECT_PK IN 
+        SQL
+    DELETE_OBJECT = <<-SQL
+        DELETE FROM R_OBJECTS WHERE OBJECT_PK = ?
+        SQL
+    SAVE_PARAMS = <<-SQL
+        INSERT INTO R_PARAMS VALUES (?, ?, ?, ?, ?, ?, ?)
+        SQL
+    SELECT_PARAMS = <<-SQL
+        SELECT P.*, O.OBJECT_CLASS, R.OBJECT_CLASS
+            FROM R_PARAMS P JOIN R_OBJECTS O ON (O.OBJECT_PK = P.OBJECT_PK)
+            LEFT OUTER JOIN R_OBJECTS R ON (P.REF_VALUE = R.OBJECT_PK)
+                WHERE O.OBJECT_PK IN 
+        SQL
+    SELECT_ONE_OBJECT = <<-SQL
+        SELECT  O.OBJECT_PK, P.NAME, P.FLAGS, P.INT_VALUE, P.STR_VALUE, 
+                P.DAT_VALUE, P.REF_VALUE,  O.OBJECT_CLASS, R.OBJECT_CLASS
+            FROM R_OBJECTS O
+                LEFT OUTER JOIN R_PARAMS  P ON (O.OBJECT_PK = P.OBJECT_PK)
+                LEFT OUTER JOIN R_OBJECTS R ON (P.REF_VALUE = R.OBJECT_PK)
+                WHERE O.OBJECT_PK = ?
+        SQL
+        
+    # R_OBJECTS table's column's indexes
+    CI_O_PK     =   0
+    CI_O_CLASS  =   1
+
+    # R_PARAMS table's column's indexes
+    CI_P_PK     =   0
+    CI_P_NAME   =   1
+    CI_P_FLAGS  =   2    
+    CI_P_INT    =   3
+    CI_P_STR    =   4
+    CI_P_TIME   =   5
+    CI_P_REF    =   6
+    
+    attr :dbh, false
+    
+    def initialize dbh
+      super()
+      @dbh = dbh
+    end
+        
+    # Updates object state in database
+    def save objects
+      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) 
+      # store r_params for objects
+      @dbh.prepare SAVE_PARAMS do |sth|
+        for object in objects
+          object.peer.each {|name, param|
+            save_param sth, object.primary_key, name.to_s, param
+          }
+        end
+      end
+      # clear dirty flag
+      for object in objects
+        object.peer.dirty = false
+      end        
+    end
+        
+    # Loads object by primary_key
+    def load_by_pk pk
+      klass, peer = nil
+      dbh.execute(SELECT_ONE_OBJECT, pk) { |sth|
+        sth.fetch { |row|        
+          klass, peer = row[7], Rubernate::Peer.new unless klass
+          fetch_param peer, row
+        }
+      }
+      return nil unless klass      
+      obj = instantiate pk, class_by_name(klass), peer
+      post_load obj
+      obj
+    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, class_by_name(row[1])
+          buffer[obj.primary_key], obj.peer = obj, Rubernate::Peer.new unless obj.peer
+          result << obj
+        }        
+      }
+      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[0].to_i].peer, row
+        }
+      }
+      # clears dirty flags
+      buffer.values.each {|object| post_load object}
+      result
+    end
+        
+    # Deletes object from database
+    def delete object
+      # Rows from r_params should be deleted automaticaly 
+      #   by foregin key contraint
+      #dbh.do DELETE_PARAMS, object.primary_key
+      dbh.do DELETE_OBJECT, object.primary_key
+      object.primary_key = nil
+    end
+    
+    def close
+      @dbh.commit
+      @dbh.disconnect
+    end        
+    
+    def failed
+      @dbh.rollback rescue Log.error 'Error during rollback in session failed state'
+      @dbh.disconnect rescue Log.error 'Error during disconnect in session failed state'
+    end
+    private
+      def save_param sth, pk, name, param
+        case param
+          when Entity:    save_ref   sth, pk, name, param
+          when Hash:      save_hash  sth, pk, name, param
+          when Array:     save_array sth, pk, name, param
+          when Integer:   save_int   sth, pk, name, param
+          when Time:      save_time  sth, pk, name, param
+          when Date:      save_date  sth, pk, name, param
+          else            save_str   sth, pk, name, param
+        end
+      end
+      
+      def save_ref sth, pk, name, ref
+        sth.execute pk, name, PARAM_FLAG_REF, nil, nil, nil, ref.primary_key unless ref.removed?
+      end
+      
+      def save_time sth, pk, name, time
+        sth.execute pk, name, PARAM_FLAG_TIME, nil, nil, ::DBI::Timestamp.new(time), nil
+      end
+      
+      def save_date sth, pk, name, date
+        sth.execute pk, name, PARAM_FLAG_DATE, nil, nil, ::DBI::Timestamp.new(date), nil
+      end      
+      
+      def save_hash sth, pk, name, hash
+        hash.delete_if {|key, ref| ref.removed?}
+        if hash.empty?
+          sth.execute pk, name, PARAM_FLAG_HASH, 0, nil, nil, nil          
+        else
+          hash.each {|key, ref| save_key_value sth, pk, name, key, ref.primary_key}
+        end
+      end  
+      
+      def save_key_value sth, pk, name, key, ref
+        if key.is_a? String
+          sth.execute pk, name, HASH_STRING_REF, nil, key, nil, ref
+        elsif key.is_a? Integer
+          sth.execute pk, name, HASH_INT_REF, key, nil, nil, ref
+        elsif key.is_a? ::Time # TODO:  chek time and date scopes?
+          sth.execute pk, name, HASH_TIME_REF, nil, nil, ::DBI::Timestamp.new(key), ref 
+        elsif key.is_a? ::Date
+          sth.execute pk, name, HASH_DATE_REF, nil, nil, ::DBI::Timestamp.new(key), ref 
+        elsif key.nil? 
+          sth.execute pk, name, PARAM_FLAG_HASH, nil, nil, nil, ref
+        else
+          raise "invalid hash key value #{key}"
+        end
+      end
+      
+      def save_array sth, pk, name, array
+        array.delete_if {|ref| !ref or ref.removed?} # Reject removed and nil items
+        if array.empty? # Empty arrays should also be stored
+          sth.execute pk, name, ARRAY_INT_REF, 0, nil, nil, nil
+        else
+          array.each_index { |idx|  sth.execute pk, name, 
+            ARRAY_INT_REF, idx, nil, nil, array[idx].primary_key}
+        end
+      end
+      
+      def save_int sth, pk, name, param
+        sth.execute pk, name, PARAM_FLAG_INT, param, nil, nil, nil
+      end
+      
+      def save_str sth, pk, name, param
+        sth.execute pk, name, PARAM_FLAG_STRING, nil, param.to_s, nil, nil
+      end   
+
+      def fetch_param peer, row
+        return unless row[1] # there are no params for this object
+        name, flags, ref = row[1].to_sym, row[2].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)
+        else
+          peer[name] = fetch_value row, flags
+        end
+      end 
+      
+      def fetch_value row, flags
+        return row[CI_P_INT].to_i if flags & PARAM_FLAG_INT != 0
+        return row[CI_P_STR].to_s if flags & PARAM_FLAG_STRING != 0
+        return instantiate(row[CI_P_REF].to_i, class_by_name(row[CI_P_REF + 2])) if flags & PARAM_FLAG_REF != 0
+        return row[CI_P_TIME].to_time if flags & PARAM_FLAG_TIME != 0
+        return row[CI_P_TIME].to_date if flags & PARAM_FLAG_DATE != 0
+        return nil
+      end
+      
+      def fetch_ref_value row
+        ref_pk = nil
+        instantiate ref_pk, class_by_name(row[8]) if ref_pk = row[6]
+      end      
+            
+      def object_ids objects
+        ids = objects.collect {|o| o.primary_key}
+        ids.uniq!
+        ids.map! {|id| id.to_s}
+        ids.join ', '
+      end
+
+      def object_ids_p objects
+        '(' + object_ids(objects) + ')'
+      end
+  end
+end
+end

data/lib/rubernate/impl/dbimysql.rb

@@ -0,0 +1,28 @@
+require 'dbi'
+
+module Rubernate
+module DBI
+  class MySqlRuntime < Runtime 
+    SELECT_NEXT_PK = <<-SQL
+        SELECT LAST_INSERT_ID()
+        SQL
+    CREATE_PEER = <<-SQL
+        INSERT INTO R_OBJECTS (OBJECT_CLASS) values (?)
+        SQL
+       
+    def initialize dbh
+      super
+      dbh.do 'SET AUTOCOMMIT=0'
+    end
+    
+    # Creates record in r_objects for specified object
+    def create object
+      object.peer = Rubernate::Peer.new
+      @dbh.do CREATE_PEER, object.class.name
+      object.primary_key = @dbh.select_one(SELECT_NEXT_PK)[0].to_i
+      object.peer.dirty = true
+      object.primary_key
+    end            
+  end  
+end
+end

data/lib/rubernate/impl/dbioracle.rb

@@ -0,0 +1,29 @@
+require 'dbi'
+
+module Rubernate
+module DBI
+  class OracleRuntime < Runtime
+    SELECT_NEXT_PK = <<-SQL
+        SELECT R_PK_SEQUENCE.NEXTVAL FROM DUAL
+        SQL
+    CREATE_PEER = <<-SQL
+        INSERT INTO R_OBJECTS (OBJECT_PK, OBJECT_CLASS) values (?, ?)
+        SQL
+  
+    # TODO: make it work
+    def initialize dbh
+      super
+      dbh.do "ALTER session SET nls_date_format = 'YYYY/MM/DD HH24:MI:SS'"
+    end
+        
+    # Creates record in r_objects for specified object
+    def create object
+      object.peer = Rubernate::Peer.new
+      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.primary_key
+    end            
+  end  
+end
+end