Database Adapters
A database adapter class is a class that extends
org.apache.torque.adapter.DB
and encapsulates access to a specific
RDBMS implementation. Database adapter classes already found in Torque include
DBOracle, DBMM, DBSybase, etc. These classes allow Torque to gain access to a
wide range of databases in a uniform manner. This allows you to easily swap
between databases without any modification to Torque or the application built
on top of Torque.
Why is this necessary if Java already offers uniform database access
in the form of JDBC? Unfortunately, underlying databases still
use different SQL implementations and conventions. For example, the use
of single and double quotes varies. The use of database adapter classes in
Torque endeavors to overcome this problem.
To add a new database adapter class to Torque you must follow these
steps:
-
Create a new class DB<dbname> that extends
org.apache.torque.adapter.DB
(where dbname is the name of
the database or database driver you wish to add to Torque). DB is an
abstract class, so you need to implement a number of methods.
-
Implement getStringDelimiter(). This method has to return the character
that the specific database implementation uses to indicate string
literals in SQL. This will usually be a single qoute (').
-
Implement String getIdSqlForAutoIncrement(). Databases like MySQL
that make use of auto increment fields will implement this method.
For MySQL it returns "SELECT LAST_INSERT_ID()". Databases that do
not support this must return null.
-
Implement String getSequenceSql(Object obj). Databases like Oracle
that support the concept of unique id generators (called sequences) will
implement this method. Databases that do not support this must return
null.
-
Implement void lockTable(Connection con, String table). This method
should place a lock on a database table. Databases that only support
table level locking obviously do not require this method. Databases
that support row level locking must implement this method to avoid
synchronization problems.
-
Implement void unlockTable(Connection con, String table). This method
should release the table lock acquired by the above-mentioned
method.
-
Implement String ignoreCase(String in). This method should implement
a mechanism for case insensitive comparisons. Usually this converts
the string to Uppercase. Example UPPER (<in>). If such a
mechanism does not exist in your database simple return the in parameter
without any modification. DO NOT return in.toUpper().
-
Some databases (for example Interbase) do not support the function
returned by their implementation of ignoreCase() in the ORDER BY
clause of SELECT statements. If your database falls into this
category you should override the default implementation of
String ignoreCaseInOrderBy(String in). It is NOT required to override
this method for other databases--the default implementation calls
ignoreCase() and respectCase().
If you are adding support for a new RDBMS, then you will probably also
need to create a set of Velocity templates--used by Torque to generate
a SQL schema for your RDBMS--in the directory
conf/torque/templates/sql/base/<dbname>. The recommend method for
doing this is to copy an existing set of templates and adapt them to
your RDBMS as needed.