JORA automatically constructs list of fields, which should be fetched from
the database table, creates new object instances and assigns extracted vales to
object components. Method used to retrieve data from the database server 
depends on the type of Java object component. For example, if component has 
<TT>int</TT> type, then <TT>getInt()</TT> method is used. 
If component type is <TT>java.io.InputStream</TT>, then method
<TT>getBinaryStream</TT> is used for peeking value of this column.
If component has non built-in type (such as <TT>int, char, float...</TT>), 
then extracting of NULL values is handled by assigning <TT>null</TT> to this 
object component.<P>

<I><B>Important!</I></B>
Different SQL databases support different sets of basic types. 
For examples types DATE, TIME, TIMESTAMP, which are defined in SQL-92 standard,
are implemented by only a very small subset of the major databases.
In some cases JDBC driver failed to map JDBC type at the type supported
by concrete database (for example, with MS SQL 6.5 and JDBC-ODBC bridge,
method <CODE>java.sql.PreparedStatement.setDate()</CODE> throws 
"Driver not capable" exception). JORA tries to fix this problem by
doing conversion of the object to string and allowing database server to 
perform necessary conversion from string to target database type.
There is also a problem with choosing types for table columns when
database table is created. Different vendors use different names for
the same type. For example most of database supports BLOBs, but
in Oracle it will be named <TT>"LONG RAW"</TT>, 
in MS SQL and Sybase - <TT>"IMAGE"</TT>, <TT>"BYTE"</TT> in Informix and
<TT>"LONG VARCHAR FOR BIT DATA"</TT> in DB2. Unfortunately JORA can
not help you in solving this problem  and creating portable applications,
working with different databases. You should either choose most standard
types (such as <TT>INTEGER, CHAR, VARCHAR</TT>) or tune your application
for concrete database.<P>

JORA can return set of selected objects in two ways: as an array of objects
or by means of <I><B>Cursor</B></I>. Cursor allows you to successively 
access selected objects.
As far as polymorphic queries can require issuing of more than 
one SQL statement to fetch data from different tables, it is also task of 
the <TT>Cursor</TT> class to construct necessary SQL statements for 
each such table. Extracting selected objects into array makes it possible
to perform random access to selected objects. It is possible to limit
size of the array, so that only restricted number of objects will be 
placed in the array. Objects placed into the array should have no
components with "lazy" extraction, such as <TT>InputStream</TT>
or <TT>Blob</TT>, because they will be closed after fetching of the next 
record.
<B><I>Attention!</B></I> Because of polymorphic select is
represented by several SQL statements, sorting directives will not work 
correctly in this case (records will be ordered only locally within
each table).<P>

Cursor can be also used for updating or deleting current records 
pointed by cursor. In this case clause "for update" should be added
kin select stattement: <CODE>Assembly.table.select("for update");</CODE>
<B>Not</B> all database drivers support such operations 
with cursor. So this methods will no work with such database drivers.
Alternative way for execution update/remove operations is to 
use primary key to locate affected record.<P>


JORA also supports "Query By Example" approach for selecting objects from 
database. In this case, you do not need to explicitly specify select condition,
but instead of it pass object, which non-null components are used
as search criteria. More precisely, components of the object with 
non built-in type (<TT>int, char,...</TT>) are check for null, and
components with non-null values are added to search condition.
The result of such query will be a set of objects, having the same values
of components from the search list as object used as example.
It is convenient to use this approach when user should fill some request form 
and then application shows list of objects matching specified criteria.
Also using Query by Example approach can cause better performance, because
in this case JORA caches prepared SQL statements and database server have
not to parse them each time again. JORA uses hash table to search for 
previously prepared statements.<P>

As far as it was mentioned above, JORA supports complex object, which
fields are automatically scattered when object is constructed from
database tables values, and gathered when record is inserted or updated. 
Such complex object can be also included in search condition,
which is formed by programmer. But JORA can't help you in this case. 
Suggested approach, which allows you to preserve data encapsulation, 
is to add to the class special method, which can be used to construct query.
For example, if we have <TT>Complex</TT> class, which consists of two 
components, we can define the following method for constructing
search condition:

<PRE>
    public class Complex { 
        public double re;
	public double im;

       /** Normal comparison method
        */
	public boolean equal(Complex c) { 
	    return c.re == re && c.im == im;
	}
       /** Generate condition for SQL statement
        */
        public String sqlEqual(String name, Complex c) { 
	    return name+"_re="+c.re+" AND "+name+"_im="+c.im;
        }
    }
</PRE>

Consider the following class with component of <TT>Complex</TT> class:

<PRE>
    public class Resistor { 
        public int     id;
        public String  name;
        public Complex resistance;

        public Static Table table = new Table("Resistor", session, "id");
    } 
</PRE>

The definition of correspondent database table can be:

<PRE>
    create Table Resistor(
        id            INTEGER PRIMARY KEY,
        name          VARCHAR(80),
        resistance_re REAL,
        resistance_im REAL
    );
</PRE>

Symbol '_' is used as separator of field names of compound objects.
This symbol is defined in class <TT>Table</TT> and can be changed to
any other symbol. The query of <TT>Resistor</TT> objects can be constructed
in the following way:

<PRE>
    public Resistor findResistor(Complex resistance) { 
        return Table.Resistor.select("where " + 
                                     Resistor.sqlEqual("resistance",
				                       resistance));
    }
</PRE>

This solution is not so elegant, but at least it makes it possible to use
such approaches as polymorphism and encapsulation. See also example in previous
paragraph with <TT>Point</TT> object.<P>



<H2><A NAME = "manip">Insert, update and delete commands</A></H2>

It is possible to insert new record in the table using 
<CODE>Table.insert(Object obj)</CODE> method. Values of componets of specified
object will be stored in correspondent columns of new database record.
If some object component is <TT>null</TT>, then value of record
column will be <TT>NULL</TT>. In case of components of <TT>Serializable</TT>
type, the closure of referenced objects (i.e. object referenced by this object,
objects referenced from objects referenced by this objects,...)
will be packed and placed in database BLOB field using standard Java
serialization mechanism.<P>

Update and insert commands can be performed either by using table primary key
or cursor current object. In the first case affected record is determined
by primary key field of the object. Located record is either deleted or
updated with values of components of specified object. 
JORA supports only keys of atomic types, if you need to 
update record in table with compound key, then use cursor.
In the second case record located by current cursor 
position is used. It is not necessary to specify object in this case, 
because current object of <TT>Cursor</TT> class is used for updating
current record. <B><I>Attention!</B></I> Cursors are not supported by all
databases.<P>


<TABLE BORDER WIDTH=80% ALIGN="CENTER">
<CAPTION><A HNAME="atypes">Atomic types for components of classes mapped on database tables</A></CAPTION>
<TR><TD>byte</TD><TD>Byte</TD><TD>String</TD></TR>
<TR><TD>short</TD><TD>Short</TD><TD>char[]</TD></TR>
<TR><TD>int</TD><TD>Integer</TD><TD>java.sql.Date</TD></TR>
<TR><TD>long</TD><TD>Long</TD><TD>java.sql.Time</TD></TR>
<TR><TD>float</TD><TD>Float</TD><TD>java.sql.Timestamp</TD></TR>
<TR><TD>double</TD><TD>Double</TD><TD>java.math.BigDecimal</TD></TR>
<TR><TD>boolean</TD><TD>Boolean</TD><TD>java.io.InputStream</TD></TR>
</TABLE><P>

<H2><A NAME = "about">Release notes</A></H2>

JORA is distributed as separate Java package together with documentation
prepared by <B>javadoc</B> <A HREF="Package-jora.html">Package-jora.html</A>
and test program containing classes 
<A HREF="Test.java">Test.java</A>,
<A HREF="Employee.java">Employee.java</A>, 
<A HREF="Programmer.java">Programmer.java</A>, 
<A HREF="Manager.java">Manager.java</A>, 
<A HREF="Experience.java">Experience.java</A> and 
<A HREF="Activity.java">Activity.java</A>.
Special script <TT>compile</TT> can be used to compile JORA package and 
test program and create HTML documentation. 
This test program was tuned for Microsoft SQL server and is using default 
account "sa" with empty password. So you may need to change in this test
driver, database URL, user name and password according to concrete database 
server your are using.
Also names of SQL types, which are used for table creation, are candidates for 
replacing. Test can be executed by running <TT>java Test</TT> command.<P>
 

JORA is freeware and is distributed with sources and without any restrictions.
E-mail support is guaranteed. I will do my best to fix all reported bugs 
and extend JORA functionality. Any suggestions and comments are welcome.
Version of Jora for JDBC 2.0, supporting batch statement execution,
efficient update and delete for current record, <TT>Blob</TT> and <TT>Clob</TT>
data types, will be available as soon as implementation of JDBC 2.0 will 
be ready.
<P> 

<HR>
<P ALIGN="CENTER"><A HREF="http://www.ispras.ru/~knizhnik">
<B>Look for new version at my homepage</B></A><B> | </B>
<A HREF="mailto:knizhnik@altavista.net">
<B>E-mail me about bugs and problems</B></A></P>
</BODY>
</HTML>