ribs 0.0.1

data/README

@@ -0,0 +1,139 @@
+= Ribs - A Ruby ORM using Hibernate
+
+The current ORM approaches for Ruby include ActiveRecord, DataMapper
+and RBatis. None of these have the versatility and power that
+Hibernate gives to any Java project. Ribs is a new interpretation of
+the idea ActiveHibernate, which was proposed in a blog post
+here[http://olabini.com/blog/2007/04/activehibernate-any-takers/]. The
+original name didn't really suit, though, since it was based on the
+ActiveRecord name, and Ribs will end up being something quite
+different.
+
+So what is Ribs? It's a Ruby framework written for JRuby, that allows
+you to use Hibernate to persist your Ruby objects. There are many
+things planned for Ribs, but currently it only supports quite basic
+operations.
+
+== Definitions
+
+To get started, you first need to define a database connection for
+Ribs to use. In most cases you only have one, but Ribs doesn't
+preclude you defining several and using them in different places. The
+code for doing that looks like this:
+
+  Ribs::DB.define do |db|
+    db.dialect = 'Derby'
+    db.uri = 'jdbc:derby:test_database;create=true'
+    db.driver = 'org.apache.derby.jdbc.EmbeddedDriver'
+  end
+
+You can also provide username, password, and other properties that
+will be passed through to Hibernate. Currently, Derby is the only
+database tested against, but most of the features used are totally
+database independent, and Hibernate shields Ribs from most of the
+rest.
+
+See the define method and the Ribs::DB class for more information on
+what's available.
+
+To actually make a Ruby class a database backed objects, you use the
+method {Kernel#Ribs!}[link:classes/Kernel.html#M000038] In the simple case you don't need to actually
+provide any configuration, but support is available for renaming
+columns, deciding which one is the primary key, and also avoid making
+columns part of the object. The simple case looks like this:
+
+  class Blog
+    Ribs!
+  end
+
+It can also be written as:
+
+  class Blog; end
+
+  Ribs! :on => Blog
+
+There is no need to actually have the Ribs definition inside of the
+model class. You can define that a model should go against a specific
+database definition if you want - by default it will use the default
+database.
+
+In the above example, the table name backing the model will be assumed
+to be "blog". Case is not important here. Ribs tries to find the table
+no matter what.
+
+To redefine which table to use, the names of the columns, and where
+the primary key is, you need to provide a block to the {Ribs!}[link:classes/Kernel.html#M000038] method:
+
+  class Blog
+    Ribs! do |r|
+      r.table :blogs
+
+      r.primary_key :blog_id
+
+      r.col :title, :blog_title
+
+      r.avoid :irrelevant_column
+    end
+  end
+
+This code will back the model against the "blogs" table, have the
+column name blog_id represent the primary key, and map the column
+title to the property blog_title. Note that primary_key[link:classes/Ribs/Rib.html#M000028] can take a
+second parameter that is the property name. Finally, avoid[link:classes/Ribs/Rib.html#M000029] tells Ribs
+to avoid a specific column.
+
+Currently Ribs only supports simple data types. It doesn't include
+associations, and have no support for setting default values, or
+constraints in the definitions. It's not possible to set the types in
+the definitions either.
+
+== Usage
+
+Once you have a defined model, you can work with it in several
+different ways.
+
+If you want to create new instances you can do it much like with
+ActiveRecord:
+
+  blog = Blog.new
+  blog.blog_id = 1
+  blog.blog_title = "Foobar"
+  blog.save
+
+The new method can take the parameters as a hash of symbols too:
+
+  blog = Blog.new(
+    :blog_id => 1,
+    :blog_title => "Foobar")
+  blog.save
+
+And as a short hand a create method is available:
+
+  blog = Blog.create(
+    :blog_id => 1,
+    :blog_title => "Foobar")
+
+To find a specific entry:
+
+  blog = Blog.find(1)
+
+Or to find all entries:
+
+  blogs = Blog.find(:all)
+
+To update an entry:
+  
+  blog.blog_title = "New title"
+  blog.save
+
+To destroy an existing entry:
+
+  blog.destroy!
+
+Or to destroy it based on id:
+ 
+  Blog.destroy(1)
+
+== License
+
+Ribs is released under the MIT license.

data/Rakefile

@@ -0,0 +1,64 @@
+require 'rubygems'
+require 'rake/gempackagetask'
+require 'rake/rdoctask'
+require 'spec/rake/spectask'
+
+task :ant do 
+  ret = system('ant')
+  if !ret
+    raise "Compilation error"
+  end
+end
+
+task :default => [:spec]
+task :test => [:spec]
+
+desc "Flog all Ruby files in lib"
+task :flog do 
+  system("find lib -name '*.rb' | xargs flog")
+end
+
+desc "Run all specs"
+Spec::Rake::SpecTask.new(:spec) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.spec_files = FileList['test/**/*_spec.rb']
+  t.verbose = true
+  t.spec_opts = ["-fs", "--color"]
+end
+
+task :spec => [:ant]
+
+desc 'Generate RDoc'
+Rake::RDocTask.new do |task|
+  task.main = 'README'
+  task.title = 'ribs'
+  task.rdoc_dir = 'doc'
+  task.options << "--line-numbers" << "--inline-source"
+  task.rdoc_files.include('README', 'lib/**/*.rb')
+end
+
+Gem::manage_gems
+
+specification = Gem::Specification.new do |s|
+  s.name   = "ribs"
+  s.summary = "Ribs wraps Hibernate, to provide a good ORM for JRuby"
+  s.version = "0.0.1"
+  s.author = 'Ola Bini'
+  s.description = s.summary
+  s.homepage = 'http://ribs.rubyforge.org'
+  s.rubyforge_project = 'ribs'
+
+  s.has_rdoc = true
+  s.extra_rdoc_files = ['README']
+  s.rdoc_options << '--title' << 'ribs' << '--main' << 'README' << '--line-numbers'
+
+  s.email = 'ola.bini@gmail.com'
+  s.files = FileList['{lib,test}/**/*.{rb,jar}', '[A-Z]*$', 'Rakefile'].to_a
+#  s.add_dependency('mocha', '>= 0.5.5')
+end
+
+Rake::GemPackageTask.new(specification) do |package|
+  package.need_zip = false
+  package.need_tar = false
+end

data/lib/ribs.rb

@@ -0,0 +1,78 @@
+require 'java'
+
+# Force logging to a lower level
+lm = java.util.logging.LogManager.log_manager
+lm.logger_names.each do |ln|
+  lm.get_logger(ln).set_level(java.util.logging.Level::SEVERE)
+end
+
+# Everything needed for Hibernate
+require 'antlr-2.7.6.jar'
+require 'commons-collections-3.1.jar'
+require 'dom4j-1.6.1.jar'
+require 'javassist-3.4.GA.jar'
+require 'jta-1.1.jar'
+require 'slf4j-api-1.5.2.jar'
+require 'slf4j-jdk14-1.5.2.jar'
+require 'hibernate3.jar'
+
+# Java parts of Ribs
+require 'ribs.jar'
+
+require 'bigdecimal'
+
+require 'ribs/db'
+require 'ribs/definition'
+require 'ribs/session'
+require 'ribs/meat'
+require 'ribs/core_ext/time'
+
+# The Ribs module includes most functionality needed for Ribs. The
+# module is strictly a namespace and isn't generally supposed to be
+# mixed in.
+#
+module Ribs
+  class << self
+
+    # The with_session method provides an easy way of working with a
+    # low level Ribs session. It will get a session for the database
+    # in question, yield that session to the block and then release
+    # the session when finished. This should generally not be needed,
+    # but wrapping a block if code with this method is a good way of
+    # opening a session and make sure it doesn't get fully closed
+    # until after the block.
+    # 
+    # +from+ decides which database definition to get a session for.
+    #
+    def with_session(from = :default)
+      s = Ribs::Session.get(from)
+      yield s
+    ensure
+      s.release
+    end
+  end
+end
+
+module Kernel
+
+  # The main method for defining a Ribs model object can be used
+  # either from inside the class to define it on, or outside by
+  # providing a parameter for the class to act on. This gives some
+  # flexibility about where definitions should go. The implementation
+  # also keeps it open whether the model class is a real class or a
+  # singleton class. The end result of calling the Ribs! method will
+  # be to generate a definition for a database mapping, based on the
+  # information provided inside the optional block. The block will
+  # yield an object of type Ribs::Rib.
+  #
+  # +user_options+ currently takes these parameters:
+  # * <tt>:on</tt> - The class to define this mapping on. Default will be the receiver of the method call.
+  # * <tt>:db</tt> - The database to define this mapping for. <tt>:default</tt> is the default value.
+  # * <tt>:from</tt> - The hibernate XML file to fetch mapping information from. By default nil, and currently doesn't do anything.
+  #
+  def Ribs!(user_options = {}, &block)
+    default_options = {:on => self, :db => :default, :from => nil}
+    options = default_options.merge user_options
+    Ribs::define_ribs(options[:on], options, &block)
+  end
+end

data/lib/ribs/core_ext/time.rb

@@ -0,0 +1,21 @@
+
+class Time
+  JavaSqlDate = java.sql.Date
+  JavaSqlTime = java.sql.Time
+  JavaSqlTimestamp = java.sql.Timestamp
+
+  # Returns this Time object as an instance of java.sql.Date
+  def to_java_sql_date
+    JavaSqlDate.new(self.to_i*1000)
+  end
+
+  # Returns this Time object as an instance of java.sql.Time
+  def to_java_sql_time
+    JavaSqlTime.new(self.to_i*1000)
+  end
+
+  # Returns this Time object as an instance of java.sql.Timestamp
+  def to_java_sql_time_stamp
+    JavaSqlTimestamp.new(self.to_i*1000)
+  end
+end

data/lib/ribs/db.rb

@@ -0,0 +1,188 @@
+module Ribs
+  # A DB instance represents a specific database configuration,
+  # including properties for the Hibernate connection.
+  class DB
+    Properties = java.util.Properties
+    Environment = org.hibernate.cfg.Environment
+    Configuration = org.hibernate.cfg.Configuration
+    
+    class << self
+      # All the defined databases
+      attr_accessor :databases
+      
+      # Defines a new database. Takes the name of the database as
+      # parameter. There can only be one database with a specific name
+      # at any time. The default name is <tt>:main</tt>. After
+      # creating the DB instance, this will be yielded to the
+      # block. This block needs to be provided. The db is not
+      # registered until after the block has executed.
+      #
+      def define(name = :main)
+        db = DB.new(name)
+
+        yield db
+        register db
+
+        db.create
+
+        db
+      end
+      
+      # Will register a new database, making sure that one and only
+      # one database is always the default. The rules are simple for
+      # this: If the argument is the only database in the system, it
+      # is the default. If there are more databases in the system, and
+      # the argument has the default flag set, then all other
+      # databases are reset to not be default.
+      #
+      def register(db)
+        if self.databases.empty?
+          db.default = true
+        elsif db.default?
+          self.databases.each do |name, db|
+            db.default = false
+          end
+        end
+        self.databases[db.name] = db
+      end
+      
+      # Gets the named database instance, or the default one if +name+
+      # is nil.
+      def get(name = nil)
+        if name && name != :default
+          self.databases[name]
+        else
+          self.databases.find do |name, db|
+            db.default?
+          end[1]
+        end
+      end
+    end
+
+    self.databases = {}
+
+    # Name of the database. Default is <tt>:main</tt>
+    attr_accessor :name
+    # The JDBC uri of the database. This follows the same rules as
+    # Hibernate JDBC URLs. It's necessary to provide this.
+    attr_accessor :uri
+    # Driver for the database connection. Necessary to provide.
+    attr_accessor :driver
+    # The database Hibernate dialect to use. This is currently
+    # necessary. The available choices are:
+    #
+    # * Cache71
+    # * DataDirectOracle9
+    # * DB2390
+    # * DB2400
+    # * DB2
+    # * Derby
+    # * Firebird
+    # * FrontBase
+    # * H2
+    # * HSQL
+    # * Informix
+    # * Ingres
+    # * Interbase
+    # * JDataStore
+    # * Mckoi
+    # * MimerSQL
+    # * MySQL5
+    # * MySQL5InnoDB
+    # * MySQL
+    # * MySQLInnoDB
+    # * MySQLMyISAM
+    # * Oracle9
+    # * Oracle
+    # * Pointbase
+    # * PostgreSQL
+    # * Progress
+    # * RDBMSOS2200
+    # * SAPDB
+    # * SQLServer
+    # * Sybase11
+    # * SybaseAnywhere
+    # * Sybase
+    # * TimesTen
+    # 
+    # See the package org.hibernate.dialect at
+    # http://www.hibernate.org/hib_docs/v3/api/ for an explanation of
+    # the different dialects.
+    attr_accessor :dialect
+    # The username to connect with. Can be nil
+    attr_accessor :username
+    # The password to connect with. Can be nil
+    attr_accessor :password
+    # A hash of properties to pass on to hibernate. Can be any string
+    # to string value.
+    attr_accessor :properties
+    # Is this database the default one? true or false.
+    attr_accessor :default
+    # All the mappings that have been defined for this database
+    attr_reader :mappings
+    
+    # Creates the database with the specific name, or <tt>:main</tt>
+    # if none is provided.
+    def initialize(name = :main)
+      self.name = name
+      self.properties = {}
+    end
+    
+    # Is this database the default?
+    def default?
+      self.default
+    end
+
+    # Creates the Hibernate Configuration object and the session
+    # factory that provides connections to this database.
+    def create
+      properties = Properties.new
+      properties.set_property(Environment::DIALECT, "org.hibernate.dialect.#{self.dialect}Dialect") if self.dialect
+      properties.set_property(Environment::USER, self.username) if self.username
+      properties.set_property(Environment::PASS, self.password) if self.password
+      properties.set_property(Environment::URL, self.uri) if self.uri
+      properties.set_property(Environment::DRIVER, self.driver) if self.driver
+      self.properties.each do |key, value|
+        properties.set_property(key, value)
+      end
+      @configuration = Configuration.new.add_properties(properties)
+      @configuration.set_interceptor org.jruby.ribs.EntityNameInterceptor.new
+      @mappings = @configuration.create_mappings
+      reset_session_factory!
+    end
+
+    # Resets the session factory. This is necessary after some
+    # configuration changes have happened.
+    def reset_session_factory!
+      @session_factory = @configuration.build_session_factory
+    end
+    
+    # Fetch a new Ribs session connected to the this database. Returns
+    # a Ribs::Session object.
+    def session
+      sessions = (Thread.current[:ribs_db_sessions] ||= {})
+      if curr = sessions[self.object_id]
+        curr[1] += 1 #reference count
+        Session.new(self, curr[0])
+      else
+        sess = @session_factory.open_session
+        sessions[self.object_id] = [sess,1]
+        Session.new(self, sess)
+      end
+    end
+    
+    # Release a Ribs::Session object that is connected to this
+    # database. That Session object should not be used after this
+    # method has been invoked.
+    def release(session)
+      res = Thread.current[:ribs_db_sessions][self.object_id]
+      if res[0] == session.hibernate_session
+        res[1] -= 1
+        if res[1] == 0
+          res[0].close
+          Thread.current[:ribs_db_sessions].delete(self.object_id)
+        end
+      end
+    end
+  end
+end