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

java.lang.Object
  |
  +--org.apache.turbine.util.db.adapter.DB
All Implemented Interfaces:
IDMethod, java.io.Serializable
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
implements java.io.Serializable, IDMethod

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: DB.java,v 1.3 2001/09/12 17:07:38 mpoeschl Exp $
Author:
Jon S. Stevens, Brett McLaughlin, Daniel Rall
See Also:
Serialized Form

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_MSSQL7
          SELECT TOP ...
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 ...
 
Fields inherited from interface org.apache.turbine.util.db.map.IDMethod
AUTO_INCREMENT, AUTOINCREMENT, ID_BROKER, IDBROKERTABLE, NATIVE, NO_ID_METHOD, SEQUENCE
 
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.
 java.lang.String getDateString(java.lang.String dateString)
          This method is used to format any date string.
abstract  java.lang.String getIDMethodSQL(java.lang.Object obj)
          Returns SQL used to get the most recently inserted primary key.
abstract  java.lang.String getIDMethodType()
          Returns the constant from the {@see IDMethod} interface denoting which type of primary key generation method this type of RDBMS uses.
 java.lang.String getIdSqlForAutoIncrement(java.lang.Object obj)
          Deprecated. Use getIDMethodSQL(Object) instead.
 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.
 java.lang.String getSequenceSql(java.lang.Object obj)
          Deprecated. Use getIDMethodSQL(Object) instead.
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

LIMIT_STYLE_MSSQL7

public static final int LIMIT_STYLE_MSSQL7
SELECT TOP ...
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.

getIDMethodType

public abstract java.lang.String getIDMethodType()
Returns the constant from the {@see IDMethod} interface denoting which type of primary key generation method this type of RDBMS uses.

getIDMethodSQL

public abstract java.lang.String getIDMethodSQL(java.lang.Object obj)
Returns SQL used to get the most recently inserted primary key. Databases which have no support for this return null.
Parameters:
obj - Information used for key generation.
Returns:
The most recently inserted database key.

getIdSqlForAutoIncrement

public java.lang.String getIdSqlForAutoIncrement(java.lang.Object obj)
Deprecated. Use getIDMethodSQL(Object) instead.

See Also:
getIDMethodSQL(Object obj)

getSequenceSql

public java.lang.String getSequenceSql(java.lang.Object obj)
Deprecated. Use getIDMethodSQL(Object) instead.

See Also:
getIDMethodSQL(Object obj)

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.

getDateString

public java.lang.String getDateString(java.lang.String dateString)
This method is used to format any date string. Database can use different default date formats.
Returns:
The proper date formated String.


Copyright © 2000-2002 Apache Software Foundation. All Rights Reserved.