Working With Rails

Rbatis

= Welcome to RBatis!

RBatis is the port of iBatis[http://ibatis.apache.org] to Ruby and Ruby on Rails.

Using RBatis with Ruby on Rails

Currently the best way to use RBatis is in the Ruby on Rails framework. It can be used outside Ruby on Rails but this is not well-documented.

Installing the plugin

In the root of your Ruby on Rails application run:

./script/plugin install https://svn.apache.org/repos/asf/ibatis/trunk/rb/rbatis

Generating a model

You can generate a RBatis derived model using:

./script/generate rbatis account

It will generate a test and an empty RBatis model that looks something like:

class Account < RBatis::Base
end

Statements and resultmaps

There’s two core concepts of RBatis: statements and resultmaps. Statements correspond to normal SQL statements, these are: select :: See RBatis::Select select_one :: See RBatis::SelectOne select_value :: See RBatis::SelectValue insert :: See RBatis::Insert update :: See RBatis::Update delete :: See RBatis::Delete

All statements are declared with RBatis::Repository::ClassMethods#statement.

A resultmap is used by the select statements to map a record in the resultset to a Ruby object, a ResultMap is declared with RBatis::Repository::ClassMethods#resultmap.

Declaring a select and select_one

class Product < RBatis::Base
end

statement :select_one, :find do |productid|
  ["SELECT * FROM product WHERE productid = ?", productid]
end

statement :select, :find_by_category do |category|
  ["SELECT * FROM product WHERE category = ?", category]
end

These statements can be executed using: Product.find(id) Product.find_by_category(category)

But first you need to declare a resultmap. If otherwise specified a statement uses the resultmap named efault.

See RBatis::Select and RBatis::SelectOne.

Declaring a resultmap

A resultmap is used by a select (or select_one) to map one record from the database into a Ruby object. If a resultmap is not specified when declaring the select (or select_one) then the resultmap named efault will be used. This is an example of a resultmap:

resultmap :default,
  :product_id => ["productid", String],
  :name => ["name", String],
  :description => ["descn", String],
  :items => RBatis::LazyAssociation.new(:to => Item, :select => :find_by_product, :key => :product_id)

The left hand side declares the field in the Ruby object and the right hand side is the mapping specification. The mapping specification can be an array in which case the RBatis::Column mapping is automatically used or it can be any other object that responds to +map(record, result) such as for example RBatis::LazyAssociation.

See RBatis::ResultMap.

Declaring a select_value

A select_value selects one value such as a integer or string from the database. For example:

statement :select_value, :find_next_order_id, :result_type => Fixnum do
  "SELECT MAX(orderid) + 1 FROM orders" 
end

See RBatis::SelectValue.

Declaring lazy associations

TODO

See RBatis::LazyAssociation.

Declaring eager associations

Support for outer join eager loading has not yet been implemented. It will be in a coming release.

Writing a custom type

A custom type is any object that implements from_database(record, column). These are implemented on Fixnum and String. The column parameter is anything you pass as the first value to the mapping specification in your resultmap. Here is an example of a hairy multi-column mapping:

class HairyObject
  def initialize(value1, value2)
    # ...
  end
end

class HairyMultiColumnMapping
  def self.from_database(record, columns)
    first_column, second_column = *columns
    HairyObject.new(record[first_column], record[second_column])
  end
end

And this would be used like this in a resultmap:

resultmap :default,
   :hairy => [[:column1, :column2], HairyMultiColumnMapping]

Declaring insert, update and delete

These are relatively simple. Resultmaps are not used with these, you need to handle the mappings yourself using normal Ruby on Rails quoting. Here’s some examples:

statement :insert do |person|
  ["INSERT INTO people (name) VALUES (?)", person.name]
end

statement :update do |person|
  ["UPDATE people SET name = ? WHERE id = ?", person.name, person.person_id]
end

statement :delete do |person|
  ["DELETE FROM people WHERE id = ?", person.person_id]
end

See RBatis::Insert, RBatis::Update, RBatis::Delete.

Using RBatis outside Ruby on Rails

Author:: Jon Tirsen (mailto:jtirsen@apache.org) Copyright:: Copyright© 2006 Apache Software Foundation License:: Apache Version 2.0 (see http://www.apache.org/licenses/)

NOTE: This description has been extracted from the Plugin README and so the formatting may need updating to make browser friendly