DatabaseAdapter (TriActive Java Data Objects API)

Overview

Package

Class

Use

Tree

Deprecated

Index

Help

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

com.triactive.jdo.store.adapter
Class DatabaseAdapter

java.lang.Object
  com.triactive.jdo.store.adapter.DatabaseAdapter

Direct Known Subclasses:: HsqldbAdapter, MysqlAdapter, PointBaseAdapter, PostgresqlAdapter

public abstract class DatabaseAdapter
extends java.lang.Object

Provides methods for adapting SQL language elements to a specific vendor's database. A database adapter is primarily used to map generic JDBC data types and SQL identifiers to specific types/identifiers suitable for the database in use.

Each database adapter corresponds to a particular combination of database, database version, driver, and driver version, etc. as provided by the driver's own metadata. Database adapters cannot be constructed directly, but must be obtained using the getInstance(java.sql.Connection) method.

Author:: Mike Martin
See Also:: DatabaseMetaData

Field Summary
`protected DatabaseIdentifier`	`dbid` The identifier for the underlying database.
`protected java.lang.String`	`identifierQuoteString` The String used to quote SQL identifiers.
`protected java.util.Set`	`keywords` The set of SQL keywords for this DBMS, in upper-case.
`protected int`	`maxCatalogNameLength` The maximum length to be used for a schema name.
`protected int`	`maxColumnNameLength` The maximum length to be used for a column name.
`protected int`	`maxConstraintNameLength` The maximum length to be used for a table constraint name.
`protected int`	`maxCorrelationNameLength` The maximum length to be used for a correlation name.
`protected int`	`maxIndexNameLength` The maximum length to be used for an index name.
`protected int`	`maxSchemaNameLength` The maximum length to be used for a schema name.
`protected int`	`maxTableNameLength` The maximum length to be used for a table name.
`protected boolean`	`storesLowerCaseIdentifiers` `true` if the database stores all identifiers in lower-case.
`protected boolean`	`storesUpperCaseIdentifiers` `true` if the database stores all identifiers in upper-case.
`protected boolean`	`supportsCorrelatedSubqueries` `true` if the database supports correlated subqueries.
`protected boolean`	`supportsGroupByUnrelated` `true` if the database supports using a column that is not in the SELECT statement in a GROUP BY clause.
`protected boolean`	`supportsOrderByUnrelated` `true` if the database supports using a column that is not in the SELECT statement in an ORDER BY clause.
`protected boolean`	`supportsSubqueriesInExists` `true` if the database supports subqueries in EXISTS.
`protected boolean`	`supportsSubqueriesInIns` `true` if the database supports subqueries in IN.
`protected java.util.Map`	`typeMappings` A map of Java types to Mapping classes.
`protected java.util.List`	`types` A list of `TypeInfo` object representing all the data types, in the order returned by `DatabaseMetaData.getTypeInfo()`.

Constructor Summary
`protected`	`DatabaseAdapter()`

Method Summary
`protected void`	`adaptTo(DatabaseIdentifier dbid, java.sql.DatabaseMetaData dmd)` Initializes the database adapter based on the given JDBC metadata.
`SqlExpression`	`avgFunction(SqlExpression expr)` Returns the appropriate SQL expression for the JDOQL AVG() function.
`boolean`	`bitTypeIsReallyBoolean()` `true` if the primary (ie first) eligible boolean data type is `Types.BIT` but in fact it fully behaves as a boolean type.
`SqlExpression`	`cast(SqlExpression expr, java.lang.Class toType)` Returns the appropriate SQL expression for casting an expression to another type.
`SqlExpression`	`countFunction(SqlExpression expr)` Returns the appropriate SQL expression for the JDOQL COUNT() function.
`boolean`	`createIndexesBeforeForeignKeys()`
`protected void`	`createTypeInfo(java.sql.DatabaseMetaData dmd)` Creates TypeInfo objects for all of the data types and saves them in the 'types' list.
`java.lang.String`	`getAddCandidateKeyStatement(ConstraintName ckName, CandidateKey ck)` Returns the appropriate SQL to add a candidate key to its table.
`java.lang.String`	`getAddForeignKeyStatement(ConstraintName fkName, ForeignKey fk)` Returns the appropriate SQL to add a foreign key to its table.
`java.lang.String`	`getAddPrimaryKeyStatement(ConstraintName pkName, PrimaryKey pk)` Returns the appropriate SQL to add a primary key to its table.
`protected DatabaseIdentifier`	`getBestIdentifyingPatterns()` Returns a database identifier containing patterns with which to identify which databases are best supported by this adapter.
`java.lang.String`	`getCreateIndexStatement(IndexName idxName, Index idx)` Returns the appropriate SQL to add an index to its table.
`java.lang.String`	`getCreateTableStatement(BaseTable table, Column[] columns)` Returns the appropriate SQL to create the given table having the given columns.
`java.sql.Timestamp`	`getCurrentTimestamp(java.sql.Connection conn)` Returns a timestamp reflecting the database's current date and time.
`java.lang.String`	`getDropForeignKeyStatement(BaseTable table, ConstraintName fkName)` Returns the appropriate SQL to drop a foreign key from its table.
`java.lang.String`	`getDropTableStatement(BaseTable table)` Returns the appropriate SQL to drop the given table.
`java.lang.String`	`getDropViewStatement(View view)` Returns the appropriate SQL to drop the given view.
`java.lang.String`	`getIdentifierQuoteString()`
`static DatabaseAdapter`	`getInstance(java.sql.Connection conn)` Returns a `DatabaseAdapter` object appropriate for the database currently underlying the given `Connection`.
`int`	`getMaxCatalogNameLength()`
`int`	`getMaxColumnNameLength()`
`int`	`getMaxConstraintNameLength()`
`int`	`getMaxCorrelationNameLength()`
`int`	`getMaxIndexNameLength()`
`int`	`getMaxPreparedStatementParameters()`
`int`	`getMaxSchemaNameLength()`
`int`	`getMaxTableNameLength()`
`protected java.lang.String`	`getQueryCurrentSchemaNameStatement()` Returns a statement that will return the name of the current schema.
`protected java.lang.String`	`getQueryCurrentTimestampStatement()` Returns a statement that will return a timestamp reflecting the database's current date and time.
`java.lang.String`	`getSchemaName(java.sql.Connection conn)` Returns name of the current schema on the specified connection.
`SqlState`	`getSqlState(java.sql.SQLException se)` Returns a SqlState object for the specified SQLException, if one is present and valid.
`TypeInfo`	`getTypeInfo(int dataType)` Returns type information for the database type that best implements the given JDBC type.
`TypeInfo`	`getTypeInfo(int[] candidateDataTypes)` Returns type information for the first one of the given candidate JDBC data types supported by this database.
`int`	`getUnlimitedLengthPrecisionValue(TypeInfo typeInfo)` Returns the precision value to be used when creating string columns of "unlimited" length.
`java.lang.String`	`getVendorID()` Returns the unique vendor ID for databases served by this adapter.
`protected boolean`	`isBestAdapterFor(DatabaseIdentifier dbid, java.sql.DatabaseMetaData dmd)` Returns `true` if this adapter is best suited for use with the specified database, based on its identifier and/or metadata.
`boolean`	`isEmbeddedType(java.lang.Class c)`
`boolean`	`isSqlKeyword(java.lang.String word)` Tests if a given string is a SQL key word.
`SqlExpression`	`lengthMethod(StringExpression str)` Returns the appropriate SQL expression for the JDOQL String.length() method.
`protected java.lang.Class`	`mappingClassFor(java.lang.Class c)`
`protected java.lang.Class`	`mappingClassFor(FieldMetaData fmd)`
`SqlExpression`	`maxFunction(SqlExpression expr)` Returns the appropriate SQL expression for the JDOQL MAX() function.
`SqlExpression`	`minFunction(SqlExpression expr)` Returns the appropriate SQL expression for the JDOQL MIN() function.
`ColumnInfo`	`newColumnInfo(java.sql.ResultSet rs)` A factory for ColumnInfo objects.
`ColumnMapping`	`newColumnMapping(java.lang.Class c)`
`javax.jdo.JDOException`	`newDataStoreException(java.lang.String message, java.sql.SQLException e)` Create the appropriate `JDODataStoreException` or `JDOFatalDataStoreException` for the given `SQLException` based on whether the action causing the exception has aborted the current transaction.
`ForeignKeyInfo`	`newForeignKeyInfo(java.sql.ResultSet rs)` A factory for ForeignKeyInfo objects.
`IndexInfo`	`newIndexInfo(java.sql.ResultSet rs)` A factory for IndexInfo objects.
`Mapping`	`newMapping(java.lang.Class c)`
`Mapping`	`newMapping(FieldMetaData fmd)`
`PrimaryKeyInfo`	`newPrimaryKeyInfo(java.sql.ResultSet rs)` A factory for PrimaryKeyInfo objects.
`QueryStatement`	`newQueryStatement(StoreManager storeMgr, Table table)`
`QueryStatement`	`newQueryStatement(StoreManager storeMgr, Table table, CorrelationName rangeVar)`
`QueryStatement`	`newQueryStatement(StoreManager storeMgr, Table table, CorrelationName rangeVar, QueryStatement subquery)`
`TableExpression`	`newTableExpression(QueryStatement qs, Table table, CorrelationName rangeVar)` Returns a new TableExpression object appropriate for this DBMS.
`TableInfo`	`newTableInfo(java.sql.ResultSet rs)` A factory for TableInfo objects.
`protected TypeInfo`	`newTypeInfo(java.sql.ResultSet rs, int row)` A factory for TypeInfo objects.
`protected static java.util.Set`	`parseKeywordList(java.lang.String list)` Parses a comma-separated list of strings and returns them as a set.
`boolean`	`storesLowerCaseIdentifiers()`
`boolean`	`storesUpperCaseIdentifiers()`
`SqlExpression`	`substringMethod(StringExpression str, NumericExpression begin)` Returns the appropriate SQL expression for the JDOQL String.substring(str,begin) method.
`SqlExpression`	`substringMethod(StringExpression str, NumericExpression begin, NumericExpression end)` Returns the appropriate SQL expression for the JDOQL String.substring(str,begin,end) method.
`SqlExpression`	`sumFunction(SqlExpression expr)` Returns the appropriate SQL expression for the JDOQL SUM() function.
`boolean`	`supportsBooleanComparison()` Indicates whether or not two boolean expressions can be directly compared to each other using the = or <> operator.
`boolean`	`supportsCorrelatedSubqueries()`
`boolean`	`supportsDeferredConstraints()`
`boolean`	`supportsGroupByUnrelated()`
`boolean`	`supportsNullsInCandidateKeys()`
`boolean`	`supportsOrderByUnrelated()`
`boolean`	`supportsSubqueriesInExists()`
`boolean`	`supportsSubqueriesInIns()`
`java.lang.String`	`toString()`

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

dbid

protected DatabaseIdentifier dbid

The identifier for the underlying database.

maxCatalogNameLength

protected int maxCatalogNameLength

The maximum length to be used for a schema name.

maxSchemaNameLength

protected int maxSchemaNameLength

The maximum length to be used for a schema name.

maxTableNameLength

protected int maxTableNameLength

The maximum length to be used for a table name.

maxConstraintNameLength

protected int maxConstraintNameLength

The maximum length to be used for a table constraint name.

maxCorrelationNameLength

protected int maxCorrelationNameLength

The maximum length to be used for a correlation name.

maxIndexNameLength

protected int maxIndexNameLength

The maximum length to be used for an index name.

maxColumnNameLength

protected int maxColumnNameLength

The maximum length to be used for a column name.

storesLowerCaseIdentifiers

protected boolean storesLowerCaseIdentifiers

true if the database stores all identifiers in lower-case.

storesUpperCaseIdentifiers

protected boolean storesUpperCaseIdentifiers

true if the database stores all identifiers in upper-case.

supportsCorrelatedSubqueries

protected boolean supportsCorrelatedSubqueries

true if the database supports correlated subqueries.

supportsSubqueriesInExists

protected boolean supportsSubqueriesInExists

true if the database supports subqueries in EXISTS.

supportsSubqueriesInIns

protected boolean supportsSubqueriesInIns

true if the database supports subqueries in IN.

supportsGroupByUnrelated

protected boolean supportsGroupByUnrelated

true if the database supports using a column that is not in the SELECT statement in a GROUP BY clause.

supportsOrderByUnrelated

protected boolean supportsOrderByUnrelated

true if the database supports using a column that is not in the SELECT statement in an ORDER BY clause.

identifierQuoteString

protected java.lang.String identifierQuoteString

The String used to quote SQL identifiers.

keywords

protected java.util.Set keywords

The set of SQL keywords for this DBMS, in upper-case.

types

protected java.util.List types

A list of TypeInfo object representing all the data types, in the order returned by DatabaseMetaData.getTypeInfo().

typeMappings

protected java.util.Map typeMappings

A map of Java types to Mapping classes. Adapter subclasses may modify this map as needed.

See Also:: Mapping.getDefaultMappingsByType()

Constructor Detail

DatabaseAdapter

protected DatabaseAdapter()

Method Detail

getInstance

public static DatabaseAdapter getInstance(java.sql.Connection conn)
                                   throws java.sql.SQLException

Returns a DatabaseAdapter object appropriate for the database currently underlying the given Connection. Databases are identified by constructing a DatabaseIdentifier using the connection's DatabaseMetaData. Multiple calls to this method with connections producing the same DatabaseIdentifier will return the same DatabaseAdapter.

Parameters:: conn - an open database connection
Returns:: a database adapter object for the database underlying the given connection.
Throws:: java.sql.SQLException - If a database error occurs.

getVendorID

public java.lang.String getVendorID()

Returns the unique vendor ID for databases served by this adapter. A vendor ID is intended to be the shortest possible string that uniquely identifies the DBMS product. They should be all lower-case and have no white space.

It is primarily used as a rough way for user code to distinguish among the dialects of SQL provided by different vendors. It is not intended to distinguish between releases over time of the same product. Strictly speaking two adapter classes could report the same vendor ID if they adapted to different versions of the same product.

The default implementation in this class derives a vendor ID by taking the adapter class name, removing the package prefix and any "Adapter" suffix, and converting to lower case.

getBestIdentifyingPatterns

protected DatabaseIdentifier getBestIdentifyingPatterns()

Returns a database identifier containing patterns with which to identify which databases are best supported by this adapter. This method is used by the default implementation of isBestAdapterFor(com.triactive.jdo.store.adapter.DatabaseIdentifier, java.sql.DatabaseMetaData). Overriding this method is a simple but fairly flexible way for subclasses to define which database(s) they support.

The default implementation in this class returns patterns that match the product name against the following regular expression:

 "(?is).*" + getVendorID() + ".*"

If the vendor ID is a suitably unique keyword that would always be expected to occur in the product name of the target database (and to not occur in any others) then no other methods need to be overridden in order for the right adapter subclass to get selected.

See Also:: getVendorID(), DatabaseIdentifier.matches(com.triactive.jdo.store.adapter.DatabaseIdentifier)

isBestAdapterFor

protected boolean isBestAdapterFor(DatabaseIdentifier dbid,
                                   java.sql.DatabaseMetaData dmd)
                            throws java.sql.SQLException

Returns true if this adapter is best suited for use with the specified database, based on its identifier and/or metadata. This is the definitive method which determines whether or not an adapter will be selected for use. Once an adapter returns true for a database, no other adapters are consulted.

The default implementation in this class matches dbid against the regex patterns returned by getBestIdentifyingPatterns(). Subclasses can override this method to perform a more sophisticated test.

Parameters:: dbid - the database identifier; dmd - the database metadata
Throws:: java.sql.SQLException
See Also:: DatabaseIdentifier.matches(com.triactive.jdo.store.adapter.DatabaseIdentifier)

adaptTo

protected void adaptTo(DatabaseIdentifier dbid,
                       java.sql.DatabaseMetaData dmd)
                throws java.sql.SQLException

Initializes the database adapter based on the given JDBC metadata. Called only once after an adapter object has been selected for use.

Parameters:: dbid - the database identifier; dmd - the database metadata
Throws:: java.sql.SQLException

parseKeywordList

protected static java.util.Set parseKeywordList(java.lang.String list)

Parses a comma-separated list of strings and returns them as a set.

createTypeInfo

protected void createTypeInfo(java.sql.DatabaseMetaData dmd)
                       throws java.sql.SQLException

Creates TypeInfo objects for all of the data types and saves them in the 'types' list. Subclasses should override this method, rather than adaptTo(com.triactive.jdo.store.adapter.DatabaseIdentifier, java.sql.DatabaseMetaData) if they want to customize the contents of types.

Throws:: java.sql.SQLException

getMaxCatalogNameLength

public int getMaxCatalogNameLength()

getMaxSchemaNameLength

public int getMaxSchemaNameLength()

getMaxTableNameLength

public int getMaxTableNameLength()

getMaxConstraintNameLength

public int getMaxConstraintNameLength()

getMaxCorrelationNameLength

public int getMaxCorrelationNameLength()

getMaxIndexNameLength

public int getMaxIndexNameLength()

getMaxColumnNameLength

public int getMaxColumnNameLength()

getMaxPreparedStatementParameters

public int getMaxPreparedStatementParameters()

storesLowerCaseIdentifiers

public boolean storesLowerCaseIdentifiers()

storesUpperCaseIdentifiers

public boolean storesUpperCaseIdentifiers()

getIdentifierQuoteString

public java.lang.String getIdentifierQuoteString()

createIndexesBeforeForeignKeys

public boolean createIndexesBeforeForeignKeys()

supportsCorrelatedSubqueries

public boolean supportsCorrelatedSubqueries()

supportsSubqueriesInExists

public boolean supportsSubqueriesInExists()

supportsSubqueriesInIns

public boolean supportsSubqueriesInIns()

supportsGroupByUnrelated

public boolean supportsGroupByUnrelated()

supportsOrderByUnrelated

public boolean supportsOrderByUnrelated()

supportsDeferredConstraints

public boolean supportsDeferredConstraints()

supportsNullsInCandidateKeys

public boolean supportsNullsInCandidateKeys()

bitTypeIsReallyBoolean

public boolean bitTypeIsReallyBoolean()

true if the primary (ie first) eligible boolean data type is Types.BIT but in fact it fully behaves as a boolean type.

supportsBooleanComparison

public boolean supportsBooleanComparison()

Indicates whether or not two boolean expressions can be directly compared to each other using the = or <> operator. Some DBMS's allow you to say WHERE (X = 12) = (Y = 34), others don't.

Returns:: true if boolean expressions can be compared, false otherwise.

getSqlState

public SqlState getSqlState(java.sql.SQLException se)

Returns a SqlState object for the specified SQLException, if one is present and valid.

Parameters:: se - A caught SQL exception.
Returns:: A SqlState object, or null if se does not contain a valid 5-character SQLSTATE.

newDataStoreException

public javax.jdo.JDOException newDataStoreException(java.lang.String message,
                                                    java.sql.SQLException e)

Create the appropriate JDODataStoreException or JDOFatalDataStoreException for the given SQLException based on whether the action causing the exception has aborted the current transaction.

For historical reasons, the design of this method is flawed. To conform correctly to the spec, if a JDOFatalDataStoreException is returned then there should be some coordination with the appropriate PersistenceManager and its Transaction to allow them to reflect the fact that a transaction is no longer active. At the least, that means that this method would have to be passed a reference to a PersistenceManager.

An outstanding question remains how we can reliably determine via JDBC whether or not a failed statement has aborted the current database transaction. Bottom line, this area is ripe for refactoring.

The current implementation in this class always returns a new JDODataStoreException and never a JDOFatalDataStoreException.

Parameters:: message - The message to include in the JDODataStoreException.; e - The SQLException to create a JDODataStoreException for.
Returns:: A JDODataStoreException or JDOFatalDataStoreException that wraps the given SQLException. A fatal exception is used to indicate that the active transaction has been aborted.

newTypeInfo

protected TypeInfo newTypeInfo(java.sql.ResultSet rs,
                               int row)
                        throws java.sql.SQLException

A factory for TypeInfo objects. This method should always be used instead of directly constructing TypeInfo objects in order to give the DatabaseAdapter an opportunity to modify and/or correct the metadata obtained from the JDBC driver. The type information object is constructed from the current row of the given result set. The ResultSet object passed must have been obtained from a call to DatabaseMetaData.getTypeInfo().