A database adapter class is a class that extends
and encapsulates access to a specific RDBMS implementation. Database
adapter classes already found in Turbine include DBOracle, DBMM, DBSybase,
etc. These classes allow Turbine 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 Turbine or the application built on top of
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
Turbine endeavors to overcome this problem without the need to change the
Turbine framework or Turbine applications for each different database
To add a new database adapter class to Turbine you must follow these
Create a new class DB<dbname> that extends
dbname is the name of the
database or database driver you wish to add to Turbine). 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
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
Implement void unlockTable(Connection con, String table). This method
should release the table lock acquired by the above-mentioned
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.