=begin

= RDBC = Ruby Database Connectivity.

This archive is an easy sample (I think so) for RDBC. 

== RDBC outline

RDBC means Ruby Database Connectivity. 
The target of RDBC is a unified(?) set of APIs
to access RDBMS like JDBC of Java.
The composition of RDBC is like that of JDBC.
Almost all the names of the classs and the methods
are mimiced. So(?) your knowledge of JDBC would
surely help you (and me ;-).

Currently, the bridges for Oracle and for Postgres
are prepared to connect RDBC with the actual
Database servers.
Those bridges merely call existent Ruby wrappers
written by the elder Ruby hackers. That is,
the oracle bridge is on the oracle module of Mr. Yoshidam,
and the postgres bridge on the postgres module of Mr. matz.

On RDBC, it is (almost) needless for the user
to call 'new' for her/himself. Almost all 'new' is
implicitly done by the method of other object.
Samples are embedded on the last of the scripts.

RDBC does not hide the SQL commands, as in JDBC.


== On Driver and Bridge:

Bridges are classes each of which act as a go-between for
a couple of classes and functions; the formers are
which RDBC user acts on directly, and the latters
each of which is expected to correspond with each class
in RDBMS.

For example, StatementBridge is a class for the
direct access on the function on RDBMS which is
related to Statement. So RDBMS-dependent procedure
is owed to xxxBridge classes (and Driver class).

Actually, xxxBridge classes (and Driver class)
inherit and embody the abstract (toy? model)
classes in the RDBC1 module. This is (now)
an assumption for implementation of them.

As a sample of the embodiment, I made Drivers
for postgres and for oracle.


== On the relation of each object:

Each of RDBC objects comstructs a family tree
(often one-to-many relation) by Composite class.
Here it is:

Driver
| Connection
| | ConnectionBridge
| | Statement
| | | StatementBridge
| | | ResultSet
| | | | ResultSetBridge
| | | | ResultSetMetaData
| | | | | ResultSetMetaDataBridge

Merely Bridges are one-to-one to its parent, and,
all of them are one of the leafs of the tree.

Composite#close communicate from a parent
to a child (children). So, if we do close
on the upperside of the tree, then RDBC object
on the lowerside is invalidated, and the Bridge
releases the corresponding RDBMS resource.
(On Bridge, I strongly recommend the coming
 Driver authors to do so.)

On the end of RDBC application, DriverManager
closes all of existing Drivers, so the user
might not close objects explicitly.


== ToDo
* A kind of system (classes?) to transfer HUGE data
  between RDB server and script, like Blob/Clob.
  I need "Stream" class which has read & write
  (like IO), where String#pack would be powerless
  to treat HUGE byte sequence.
  ...And with ResultSet#getData, in need.
* ResultSet#each. (As a common-sense of Ruby application :-)
* Not MAKE-BELIEVE version :-)
* Bridges on other RDBMSs. More and more....
* And anything, more and more....


20001029 NAKAMURA AKIFUMI (BXQ04723@nifty.ne.jp)
=end


