org.apache.turbine.util.db.adapter
Class DB

java.lang.Object
  |
  +--org.apache.turbine.util.db.adapter.DB
Direct Known Subclasses:
DBDB2App, DBDB2Net, DBHypersonicSQL, DBInformix, DBInstantDB, DBInterbase, DBMM, DBNone, DBOdbc, DBOracle, DBPostgres, DBSapDB, DBSybase, DBWeblogic

public abstract class DB
extends java.lang.Object

DB defines the interface for a Turbine database adapter. Support for new databases is added by subclassing DB and implementing its abstract interface, and by registering the new Turbine database adapter and its corresponding JDBC driver in the TurbineResources.properties file.

The Turbine database adapters exist to present a uniform interface to database access across all available databases. Once the necessary adapters have been written and configured, transparent swapping of databases is theoretically supported with zero code changes and minimal configuration file modifications.

Your adapter must be added to the list of available adapters, using a database.adapter entry. The established naming convention for adapters is the String "DB" prepended to a mutation of the short class name of the driver (i.e. no package name) or database name. A JDBC driver corresponding to your adapter should also be added, using the fullly-qualified class name of the driver. If no driver is specified for your adapter, driver.default is used.

 # Configuration for the Mysql/MM adapter.
 database.adaptor=DBMM
 database.adaptor.DBMM=org.gjt.mm.mysql.Driver
 
Hooks to make your adapter the default may also be added.
 #### MySQL MM Driver
 database.default.driver=org.gjt.mm.mysql.Driver
 database.default.url=jdbc:mysql://localhost/DATABASENAME
 

Version:
$Id$
Author:
Jon S. Stevens, Brett McLaughlin

Field Summary
protected  java.lang.String DB_CONNECTION
          The database name.
protected  java.lang.String DB_PASS
          The database password.
protected  java.lang.String DB_USER
          The database user name.
private  java.lang.String JDBCDriver
          The JDBC driver.
static int LIMIT_STYLE_MYSQL
          SELECT ...
static int LIMIT_STYLE_NONE
          database does not support limiting resultsets
static int LIMIT_STYLE_POSTGRES
          SELECT ...
static int LIMIT_STYLE_SYBASE
          SET ROWCOUNT SELECT ...
 
Constructor Summary
protected DB()
          Empty constructor.
 
Method Summary
 boolean escapeText()
          This method is for the SqlExpression.quoteAndEscape rules.
 java.sql.Connection getConnection()
          Returns a JDBC Connection from the DriverManager.
 javax.sql.ConnectionPoolDataSource getConnectionPoolDataSource()
          Returns a new JDBC PooledConnection.
abstract  java.lang.String getIdSqlForAutoIncrement(java.lang.Object obj)
          Returns the last auto-increment key.
 java.lang.String getJDBCDriver()
          Gets the JDBC driver used by this adapter.
 int getLimitStyle()
          This method is used to chek whether the database supports limiting the size of the resultset.
abstract  java.lang.String getSequenceSql(java.lang.Object obj)
          Returns the last auto-increment key.
abstract  char getStringDelimiter()
          Gets the string delimiter (usually '\'').
abstract  java.lang.String ignoreCase(java.lang.String in)
          This method is used to ignore case.
 java.lang.String ignoreCaseInOrderBy(java.lang.String in)
          This method is used to ignore case in an ORDER BY clause.
 void init(java.lang.String url, java.lang.String username, java.lang.String password)
          Performs basic initialization.
abstract  void lockTable(java.sql.Connection con, java.lang.String table)
          Locks the specified table.
 boolean objectDataNeedsTrans()
          This method is used to chek whether writing large objects to the DB requires a transaction.
 void setJDBCDriver(java.lang.String newDriver)
          Sets the JDBC driver used by this adapter.
 boolean supportsNativeLimit()
          This method is used to chek whether the database natively supports limiting the size of the resultset.
 boolean supportsNativeOffset()
          This method is used to chek whether the database natively supports returning results starting at an offset position other than 0.
abstract  java.lang.String toUpperCase(java.lang.String in)
          This method is used to ignore case.
abstract  void unlockTable(java.sql.Connection con, java.lang.String table)
          Unlocks the specified table.
 
Methods inherited from class java.lang.Object
, clone, equals, finalize, getClass, hashCode, notify, notifyAll, registerNatives, toString, wait, wait, wait
 

Field Detail

DB_USER

protected java.lang.String DB_USER
The database user name.

DB_PASS

protected java.lang.String DB_PASS
The database password.

DB_CONNECTION

protected java.lang.String DB_CONNECTION
The database name.

JDBCDriver

private java.lang.String JDBCDriver
The JDBC driver.

LIMIT_STYLE_NONE

public static final int LIMIT_STYLE_NONE
database does not support limiting resultsets

LIMIT_STYLE_POSTGRES

public static final int LIMIT_STYLE_POSTGRES
SELECT ... LIMIT , []

LIMIT_STYLE_MYSQL

public static final int LIMIT_STYLE_MYSQL
SELECT ... LIMIT [, ]

LIMIT_STYLE_SYBASE

public static final int LIMIT_STYLE_SYBASE
SET ROWCOUNT SELECT ... SET ROWCOUNT 0
Constructor Detail

DB

protected DB()
Empty constructor.
Method Detail

getConnection

public java.sql.Connection getConnection()
                                  throws java.sql.SQLException
Returns a JDBC Connection from the DriverManager.
Returns:
A JDBC Connection object for this database.
Throws:
java.sql.SQLException -  

getConnectionPoolDataSource

public javax.sql.ConnectionPoolDataSource getConnectionPoolDataSource()
                                                               throws java.sql.SQLException
Returns a new JDBC PooledConnection. The JDBC driver should support the JDBC 2.0 extenstions. Since the implementation of this class is driver specific, the actual class of the JDBC driver that implements the PooledConnection interface should be defined in the specific DB Adapter
Returns:
A JDBC PooledConnection object for this database.
Throws:
java.sql.SQLException - if the driver does not support PooledConnection objects

init

public void init(java.lang.String url,
                 java.lang.String username,
                 java.lang.String password)
          throws java.lang.Exception
Performs basic initialization. Calls Class.forName() to assure that the JDBC driver for this adapter can be loaded.
Parameters:
url - The URL of the database to connect to.
username - The name of the user to use when connecting.
password - The user's password.
Throws:
java.lang.Exception - The JDBC driver could not be loaded or instantiated.

toUpperCase

public abstract java.lang.String toUpperCase(java.lang.String in)
This method is used to ignore case.
Parameters:
in - The string to transform to upper case.
Returns:
The upper case string.

getStringDelimiter

public abstract char getStringDelimiter()
Gets the string delimiter (usually '\'').
Returns:
The delimeter.

getIdSqlForAutoIncrement

public abstract java.lang.String getIdSqlForAutoIncrement(java.lang.Object obj)
Returns the last auto-increment key. Databases like MySQL which support this feature will return a result, others will return null.
Parameters:
obj - The string information for generating a key.
Returns:
The most recently inserted database key.

getSequenceSql

public abstract java.lang.String getSequenceSql(java.lang.Object obj)
Returns the last auto-increment key. Databases like Oracle which support this feature will return a result, others will return null.
Returns:
The most recently inserted database key.

lockTable

public abstract void lockTable(java.sql.Connection con,
                               java.lang.String table)
                        throws java.sql.SQLException
Locks the specified table.
Parameters:
con - The JDBC connection to use.
table - The name of the table to lock.
Throws:
java.sql.SQLException -  

unlockTable

public abstract void unlockTable(java.sql.Connection con,
                                 java.lang.String table)
                          throws java.sql.SQLException
Unlocks the specified table.
Parameters:
con - The JDBC connection to use.
table - The name of the table to unlock.
Throws:
java.sql.SQLException -  

ignoreCase

public abstract java.lang.String ignoreCase(java.lang.String in)
This method is used to ignore case.
Parameters:
in - The string whose case to ignore.
Returns:
The string in a case that can be ignored.

ignoreCaseInOrderBy

public java.lang.String ignoreCaseInOrderBy(java.lang.String in)
This method is used to ignore case in an ORDER BY clause. Usually it is the same as ignoreCase, but some databases (Interbase for example) does not use the same SQL in ORDER BY and other clauses.
Parameters:
in - The string whose case to ignore.
Returns:
The string in a case that can be ignored.

setJDBCDriver

public void setJDBCDriver(java.lang.String newDriver)
Sets the JDBC driver used by this adapter.
Parameters:
newDriver - The fully-qualified class name of the JDBC driver to use.

getJDBCDriver

public java.lang.String getJDBCDriver()
Gets the JDBC driver used by this adapter.
Returns:
The JDBC Driver classname to use for this DB.

objectDataNeedsTrans

public boolean objectDataNeedsTrans()
This method is used to chek whether writing large objects to the DB requires a transaction. Since this is only true for Postgres, only the DBPostgres needs to override this method and return true.
Returns:
True if writing large objects to the DB requires a transaction.

supportsNativeLimit

public boolean supportsNativeLimit()
This method is used to chek whether the database natively supports limiting the size of the resultset.
Returns:
True if the database natively supports limiting the size of the resultset.

supportsNativeOffset

public boolean supportsNativeOffset()
This method is used to chek whether the database natively supports returning results starting at an offset position other than 0.
Returns:
True if the database natively supports returning results starting at an offset position other than 0.

escapeText

public boolean escapeText()
This method is for the SqlExpression.quoteAndEscape rules. The rule is, any string in a SqlExpression with a BACKSLASH will either be changed to "\\" or left as "\". SapDB does not need the escape character.
Returns:
true if the database needs to escape text in SqlExpressions.

getLimitStyle

public int getLimitStyle()
This method is used to chek whether the database supports limiting the size of the resultset.
Returns:
The limit style for the database.


Copyright © 1999-2001 Apache Software Foundation. All Rights Reserved.