Database Adapters

A database adapter class is a class that extends org.apache.turbine.util.db.pool.DB 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 Turbine.

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 encountered.

To add a new database adapter class to Turbine you must follow these steps:

  • Create a new class DB that extends org.apache.turbine.util.db.adapter.DB (where 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 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 (). 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/. The recommend method for doing this is to copy an existing set of templates and adapt them to your RDBMS as needed.