Package org.eclipse.net4j.spi.db

# Class DBAdapter

java.lang.Object
org.eclipse.net4j.spi.db.DBAdapter

All Implemented Interfaces:
  `IDBAdapter`, `IDBAdapterID`

Direct Known Subclasses:
  `DerbyAdapter`, `H2Adapter`, `HSQLDBAdapter`, `MYSQLAdapter`, `PostgreSQLAdapter`

public abstract class DBAdapter extends Object implements IDBAdapter
A useful base class for implementing custom `DB adapters`.

Service providers should subclass this type rather than implement `IDBAdapter` directly. The subclass must provide a stable name and version that identify the adapter's database system and behavior. The registry compares names case-insensitively and compares dot-separated numeric version components; trailing zero components do not create a distinct registration.

Providers contributing an adapter through the database adapter extension point should ensure that the descriptor's name and version agree with the adapter created by the provider. The descriptor identity is used for registration and lookup, and remains authoritative if the created adapter reports different metadata.

Author:
  Eike Stepper

## Nested Class Summary

Nested Classes
Modifier and Type
Class
Description
`static final class`
`DBAdapter.FieldInfo`
`static final class`
`DBAdapter.IndexInfo`

## Nested classes/interfaces inherited from interface org.eclipse.net4j.db.IDBAdapter

`IDBAdapter.Registry`

## Field Summary

### Fields inherited from interface org.eclipse.net4j.db.IDBAdapter

`REGISTRY`

## Constructor Summary

Constructors
Constructor
Description
`DBAdapter(String name, String version)`

## Method Summary

Modifier and Type
Method
Description
`DBType`
`adaptType(DBType type)`
Provide a way for the DBAdapter to override unsupported DB types with replacements.
`protected void`
`addIndex(Connection connection, IDBTable table, String name, IDBIndex.Type type, List<DBAdapter.FieldInfo> fieldInfos)`
`protected void`
`addIndexField(StringBuilder builder, IDBField field)`
`protected void`
`alterTable(Connection connection, IDBTable table, IDBTableDelta delta)`
`protected void`
`appendFieldDefs(Appendable appendable, IDBTable table, String[] defs)`
`void`
`appendFieldNames(Appendable appendable, IDBTable table)`
Appends the field names used by the adapter's table SQL generation.
`String`
`convertString(PreparedStatement preparedStatement, int parameterIndex, String value)`
Converts a string before it is bound to a prepared statement.
`String`
`convertString(ResultSet resultSet, int columnIndex, String value)`
Converts a string read from a result-set column.
`String`
`convertString(ResultSet resultSet, String columnLabel, String value)`
Converts a string read from a named result-set column.
`Object`
`convertToSQL(Object value)`
Converts a Java value to the value used by SQL query execution.
`IDBConnectionProvider`
`createConnectionProvider(DataSource dataSource)`
`protected String`
`createConstraints(IDBTable table)`
`protected void`
`createField(Connection connection, String tableName, IDBField field)`
Deprecated.
As of 4.13 use `createField(Connection, IDBField)` instead.
`protected void`
`createField(Connection connection, IDBField field)`
`protected String`
`createFieldDefinition(IDBField field)`
`protected String[]`
`createFieldDefinitions(IDBTable table)`
`protected void`
`createIndex(Connection connection, IDBIndex index, IDBIndexDelta delta)`
`protected void`
`createIndex(IDBIndex index, StringBuilder builder)`
`protected void`
`createIndex(IDBIndex index, Statement statement, int num)`
`protected void`
`createIndexFields(IDBIndex index, StringBuilder builder)`
`DataSource`
`createJDBCDataSource()`
Deprecated.
As of 4.2 no longer supported because of IP issues for external build dependencies (the vendor driver libs).
`protected void`
`createPrimaryKey(IDBIndex index, StringBuilder builder)`
`void`
`createSchema(Connection connection, String schemaName)`
`protected void`
`createTable(Connection connection, IDBTable table, IDBTableDelta delta)`
`boolean`
`createTable(IDBTable table, Statement statement)`
`Set<IDBTable>`
`createTables(Iterable<? extends IDBTable> tables, Connection connection)`
`protected void`
`doCreateTable(IDBTable table, Statement statement)`
`protected void`
`dropField(Connection connection, String tableName, String fieldName)`
Deprecated.
As of 4.13 use `dropField(Connection, IDBField)` instead.
`protected void`
`dropField(Connection connection, IDBField field)`
`protected void`
`dropIndex(Connection connection, IDBIndex index, IDBIndexDelta delta)`
`protected void`
`dropIndex(IDBIndex index, StringBuilder builder)`
`protected void`
`dropPrimaryKey(IDBIndex index, StringBuilder builder)`
`protected void`
`dropTable(Connection connection, IDBTable table, IDBTableDelta delta)`
`boolean`
`dropTable(IDBTable table, Statement statement)`
`Collection<IDBTable>`
`dropTables(Iterable<? extends IDBTable> tables, Connection connection)`
`boolean`
`equals(Object obj)`
`protected void`
`forEachTable(Connection connection, String schemaName, boolean caseSensitive, org.eclipse.net4j.util.ConsumerWithException<String,SQLException> tableNameConsumer)`
Enumerates the tables that belong to a schema while reading a database schema.
`String`
`format(PreparedStatement stmt)`
Formats a prepared statement for diagnostic output.
`String`
`format(ResultSet resultSet)`
Formats a result set for diagnostic output.
`protected static void`
`generateReservedWords(Connection connection, String[] words)`
`static int`
`getDefaultDBLength(DBType type)`
`String`
`getDefaultSchemaName(Connection connection)`
`protected String`
`getDropTableSQL(IDBTable table)`
`int`
`getFieldLength(DBType type)`
Returns the column length for the given database type.
`static void`
`getIndexInfos(DatabaseMetaData metaData, String schemaName, String tableName, Consumer<DBAdapter.IndexInfo> consumer)`
`Driver`
`getJDBCDriver()`
Deprecated.
As of 4.2 no longer supported because of IP issues for external build dependencies (the vendor driver libs).
`int`
`getJDBCTypeForNull(DBType type)`
Returns the JDBC type to use when binding a null value for the given database type.
`int`
`getMaxFieldNameLength()`
`int`
`getMaxTableNameLength()`
`String`
`getName()`
Returns the provider's adapter name.
`protected String`
`getNullableConstraint()`
`String[]`
`getSQL92ReservedWords()`
Returns the SQL-92 reserved words used by the adapter implementation.
`protected String`
`getTypeName(IDBField field)`
`String`
`getVersion()`
Returns the provider's adapter version.
`int`
`hashCode()`
`boolean`
`isCaseSensitive()`
`boolean`
`isColumnNotFoundException(SQLException ex)`
`boolean`
`isDuplicateKeyException(SQLException ex)`
Check if an exception indicates a constraint violation (duplicate key)
`boolean`
`isDuplicateKeyTransactionAbort()`
Returns whether a duplicate-key exception aborts the current JDBC transaction and therefore requires a savepoint to recover from it.
`protected boolean`
`isPrimaryKeyShadow(Connection connection, IDBTable table, String name, IDBIndex.Type type, IDBField[] fields)`
`boolean`
`isReservedWord(String word)`
`boolean`
`isTableNotFoundException(SQLException ex)`
`boolean`
`isTypeIndexable(DBType type)`
`boolean`
`isValidFirstChar(char ch)`
Check if a character is valid as first character.
`Connection`
`modifyConnection(Connection connection)`
`IDBSchemaTransaction`
`openSchemaTransaction(IDBDatabase database, IDBConnection currentConnection)`
Opens a schema transaction through the adapter extension point.
`protected void`
`readFields(Connection connection, IDBTable table)`
`protected void`
`readIndices(Connection connection, DatabaseMetaData metaData, IDBTable table, String schemaName)`
`protected void`
`readIndices(Connection connection, ResultSet resultSet, IDBTable table, int indexNameColumn, int indexTypeColumn, int fieldNameColumn, int fieldPositionColumn)`
Deprecated.
As of 4.13 no longer supported.
`IDBSchema`
`readSchema(Connection connection, String name)`
`void`
`readSchema(Connection connection, IDBSchema schema)`
`protected ResultSet`
`readTables(Connection connection, DatabaseMetaData metaData, String schemaName)`
`String`
`sqlCharIndex(Object substring, Object string)`
`protected String`
`sqlCharIndexFunction()`
`String`
`sqlConcat(Object... strings)`
`protected String`
`sqlModifyField(String tableName, String fieldName, String definition)`
`String`
`sqlModifyField(IDBField field)`
`String`
`sqlRenameField(IDBField field, String oldName)`
`String`
`sqlSubstring(Object string, Object startIndex)`
`String`
`sqlSubstring(Object string, Object startIndex, Object length)`
`protected String`
`sqlSubstringFunction()`
`String`
`toString()`
`void`
`updateSchema(Connection connection, IDBSchema schema, IDBSchemaDelta delta)`
`protected void`
`validateTable(IDBTable table, Statement statement)`

### Methods inherited from class java.lang.Object

`clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

### Methods inherited from interface org.eclipse.net4j.db.IDBAdapter

`getReservedWords`

## Constructor Details

### DBAdapter

public DBAdapter(String name, String version)

## Method Details

### getName

public String getName()
Description copied from interface: `IDBAdapter`
Returns the provider's adapter name. Registry registration and lookup compare this value case-insensitively; the value returned by this method is not lowercased for the caller.

Specified by:
  `getName` in interface `IDBAdapter`
Specified by:
  `getName` in interface `IDBAdapterID`
Returns:
  the adapter name

### getVersion

public String getVersion()
Description copied from interface: `IDBAdapter`
Returns the provider's adapter version. Registry registration and lookup compare dot-separated numeric components and ignore trailing zero components, while the original representation returned here remains available to callers.

Specified by:
  `getVersion` in interface `IDBAdapter`
Specified by:
  `getVersion` in interface `IDBAdapterID`
Returns:
  the adapter version

### hashCode

public int hashCode()

Overrides:
  `hashCode` in class `Object`

### equals

public boolean equals(Object obj)

Overrides:
  `equals` in class `Object`

### isCaseSensitive

public boolean isCaseSensitive()

Specified by:
  `isCaseSensitive` in interface `IDBAdapter`

### getDefaultSchemaName

public String getDefaultSchemaName(Connection connection)

Specified by:
  `getDefaultSchemaName` in interface `IDBAdapter`

### createConnectionProvider

public IDBConnectionProvider createConnectionProvider(DataSource dataSource)

Specified by:
  `createConnectionProvider` in interface `IDBAdapter`
Since:
  4.3

### modifyConnection

public Connection modifyConnection(Connection connection)

Specified by:
  `modifyConnection` in interface `IDBAdapter`
Since:
  4.5

### createSchema

public void createSchema(Connection connection, String schemaName)

Specified by:
  `createSchema` in interface `IDBAdapter`

### openSchemaTransaction

public IDBSchemaTransaction openSchemaTransaction(IDBDatabase database, IDBConnection currentConnection)
Description copied from interface: `IDBAdapter`
Opens a schema transaction through the adapter extension point.

Specified by:
  `openSchemaTransaction` in interface `IDBAdapter`
Since:
  4.9

### readSchema

public IDBSchema readSchema(Connection connection, String name)

Specified by:
  `readSchema` in interface `IDBAdapter`
Since:
  4.2

### readSchema

public void readSchema(Connection connection, IDBSchema schema)

Specified by:
  `readSchema` in interface `IDBAdapter`
Since:
  4.2

### forEachTable

protected void forEachTable(Connection connection, String schemaName, boolean caseSensitive, org.eclipse.net4j.util.ConsumerWithException<String,SQLException> tableNameConsumer)
Enumerates the tables that belong to a schema while reading a database schema.

Since:
  4.14

### readTables

protected ResultSet readTables(Connection connection, DatabaseMetaData metaData, String schemaName) throws SQLException

Throws:
  `SQLException`
Since:
  4.3

### readFields

protected void readFields(Connection connection, IDBTable table) throws SQLException

Throws:
  `SQLException`
Since:
  4.2

### readIndices

protected void readIndices(Connection connection, DatabaseMetaData metaData, IDBTable table, String schemaName) throws SQLException

Throws:
  `SQLException`
Since:
  4.2

### addIndex

protected void addIndex(Connection connection, IDBTable table, String name, IDBIndex.Type type, List<DBAdapter.FieldInfo> fieldInfos)

Since:
  4.2

### isPrimaryKeyShadow

protected boolean isPrimaryKeyShadow(Connection connection, IDBTable table, String name, IDBIndex.Type type, IDBField[] fields)

Since:
  4.2

### updateSchema

public void updateSchema(Connection connection, IDBSchema schema, IDBSchemaDelta delta) throws DBException

Specified by:
  `updateSchema` in interface `IDBAdapter`
Throws:
  `DBException`
Since:
  4.2

### createTable

protected void createTable(Connection connection, IDBTable table, IDBTableDelta delta)

Since:
  4.2

### dropTable

protected void dropTable(Connection connection, IDBTable table, IDBTableDelta delta)

Since:
  4.2

### alterTable

protected void alterTable(Connection connection, IDBTable table, IDBTableDelta delta)

Since:
  4.2

### createField

protected void createField(Connection connection, IDBField field)

Since:
  4.13

### dropField

protected void dropField(Connection connection, IDBField field)

Since:
  4.13

### createIndex

protected void createIndex(Connection connection, IDBIndex index, IDBIndexDelta delta)

Since:
  4.2

### createPrimaryKey

protected void createPrimaryKey(IDBIndex index, StringBuilder builder)

Since:
  4.2

### createIndex

protected void createIndex(IDBIndex index, StringBuilder builder)

Since:
  4.2

### createIndexFields

protected void createIndexFields(IDBIndex index, StringBuilder builder)

Since:
  4.2

### dropIndex

protected void dropIndex(Connection connection, IDBIndex index, IDBIndexDelta delta)

Since:
  4.2

### dropPrimaryKey

protected void dropPrimaryKey(IDBIndex index, StringBuilder builder)

Since:
  4.2

### dropIndex

protected void dropIndex(IDBIndex index, StringBuilder builder)

Since:
  4.2

### createTables

public Set<IDBTable> createTables(Iterable<? extends IDBTable> tables, Connection connection) throws DBException

Specified by:
  `createTables` in interface `IDBAdapter`
Throws:
  `DBException`

### createTable

public boolean createTable(IDBTable table, Statement statement) throws DBException

Specified by:
  `createTable` in interface `IDBAdapter`
Throws:
  `DBException`

### dropTables

public Collection<IDBTable> dropTables(Iterable<? extends IDBTable> tables, Connection connection) throws DBException

Specified by:
  `dropTables` in interface `IDBAdapter`
Throws:
  `DBException`

### dropTable

public boolean dropTable(IDBTable table, Statement statement)

Specified by:
  `dropTable` in interface `IDBAdapter`

### getDropTableSQL

protected String getDropTableSQL(IDBTable table)

### getMaxTableNameLength

public int getMaxTableNameLength()

Specified by:
  `getMaxTableNameLength` in interface `IDBAdapter`
Since:
  2.0

### getMaxFieldNameLength

public int getMaxFieldNameLength()

Specified by:
  `getMaxFieldNameLength` in interface `IDBAdapter`
Since:
  2.0

### getFieldLength

public int getFieldLength(DBType type)
Description copied from interface: `IDBAdapter`
Returns the column length for the given database type.

Specified by:
  `getFieldLength` in interface `IDBAdapter`
Parameters:
  `type` - the `DBType` to check.
Returns:
  the supported column length for the type.
Since:
  4.2

### isTypeIndexable

public boolean isTypeIndexable(DBType type)

Specified by:
  `isTypeIndexable` in interface `IDBAdapter`

### toString

public String toString()

Overrides:
  `toString` in class `Object`

### convertString

public String convertString(PreparedStatement preparedStatement, int parameterIndex, String value)
Description copied from interface: `IDBAdapter`
Converts a string before it is bound to a prepared statement.

Specified by:
  `convertString` in interface `IDBAdapter`
Since:
  4.3

### convertString

public String convertString(ResultSet resultSet, int columnIndex, String value)
Description copied from interface: `IDBAdapter`
Converts a string read from a result-set column.

Specified by:
  `convertString` in interface `IDBAdapter`
Since:
  4.3

### convertString

public String convertString(ResultSet resultSet, String columnLabel, String value)
Description copied from interface: `IDBAdapter`
Converts a string read from a named result-set column.

Specified by:
  `convertString` in interface `IDBAdapter`
Since:
  4.3

### doCreateTable

protected void doCreateTable(IDBTable table, Statement statement) throws SQLException

Throws:
  `SQLException`
Since:
  2.0

### createIndex

protected void createIndex(IDBIndex index, Statement statement, int num) throws SQLException

Throws:
  `SQLException`
Since:
  2.0

### addIndexField

protected void addIndexField(StringBuilder builder, IDBField field)

### createConstraints

protected String createConstraints(IDBTable table)

Since:
  2.0

### createFieldDefinition

protected String createFieldDefinition(IDBField field)

Since:
  2.0

### getNullableConstraint

protected String getNullableConstraint()

Since:
  4.12

### getTypeName

protected String getTypeName(IDBField field)

### getSQL92ReservedWords

public String[] getSQL92ReservedWords()
Description copied from interface: `IDBAdapter`
Returns the SQL-92 reserved words used by the adapter implementation.

Specified by:
  `getSQL92ReservedWords` in interface `IDBAdapter`

### isReservedWord

public boolean isReservedWord(String word)

Specified by:
  `isReservedWord` in interface `IDBAdapter`

### validateTable

protected void validateTable(IDBTable table, Statement statement) throws DBException

Throws:
  `DBException`
Since:
  2.0

### createFieldDefinitions

protected String[] createFieldDefinitions(IDBTable table)

Since:
  4.2

### appendFieldNames

public void appendFieldNames(Appendable appendable, IDBTable table)
Description copied from interface: `IDBAdapter`
Appends the field names used by the adapter's table SQL generation.

Specified by:
  `appendFieldNames` in interface `IDBAdapter`

### appendFieldDefs

protected void appendFieldDefs(Appendable appendable, IDBTable table, String[] defs)

Since:
  4.2

### adaptType

public DBType adaptType(DBType type)
Description copied from interface: `IDBAdapter`
Provide a way for the DBAdapter to override unsupported DB types with replacements. The default implementation just returns the given type. Subclasses may override single types with replacements.

Specified by:
  `adaptType` in interface `IDBAdapter`
Since:
  3.0

### getJDBCTypeForNull

public int getJDBCTypeForNull(DBType type)
Description copied from interface: `IDBAdapter`
Returns the JDBC type to use when binding a null value for the given database type.

Specified by:
  `getJDBCTypeForNull` in interface `IDBAdapter`
Since:
  4.14

### isValidFirstChar

public boolean isValidFirstChar(char ch)
Description copied from interface: `IDBAdapter`
Check if a character is valid as first character. (e.g., underscores are forbidden as first character in Derby elements.

Specified by:
  `isValidFirstChar` in interface `IDBAdapter`
Since:
  4.0

### isDuplicateKeyException

public boolean isDuplicateKeyException(SQLException ex)
Description copied from interface: `IDBAdapter`
Check if an exception indicates a constraint violation (duplicate key)

Specified by:
  `isDuplicateKeyException` in interface `IDBAdapter`
Since:
  4.0

### isDuplicateKeyTransactionAbort

public boolean isDuplicateKeyTransactionAbort()
Description copied from interface: `IDBAdapter`
Returns whether a duplicate-key exception aborts the current JDBC transaction and therefore requires a savepoint to recover from it.

Specified by:
  `isDuplicateKeyTransactionAbort` in interface `IDBAdapter`

### isTableNotFoundException

public boolean isTableNotFoundException(SQLException ex)

Specified by:
  `isTableNotFoundException` in interface `IDBAdapter`
Since:
  4.2

### isColumnNotFoundException

public boolean isColumnNotFoundException(SQLException ex)

Specified by:
  `isColumnNotFoundException` in interface `IDBAdapter`
Since:
  4.2

### sqlRenameField

public String sqlRenameField(IDBField field, String oldName)

Specified by:
  `sqlRenameField` in interface `IDBAdapter`
Since:
  4.2

### sqlModifyField

public String sqlModifyField(IDBField field)

Specified by:
  `sqlModifyField` in interface `IDBAdapter`
Since:
  4.2

### sqlModifyField

protected String sqlModifyField(String tableName, String fieldName, String definition)

Since:
  4.2

### sqlCharIndex

public String sqlCharIndex(Object substring, Object string)

Specified by:
  `sqlCharIndex` in interface `IDBAdapter`

### sqlCharIndexFunction

protected String sqlCharIndexFunction()

Since:
  4.13

### sqlSubstring

public String sqlSubstring(Object string, Object startIndex, Object length)

Specified by:
  `sqlSubstring` in interface `IDBAdapter`

### sqlSubstring

public String sqlSubstring(Object string, Object startIndex)

Specified by:
  `sqlSubstring` in interface `IDBAdapter`

### sqlSubstringFunction

protected String sqlSubstringFunction()

Since:
  4.13

### sqlConcat

public String sqlConcat(Object... strings)

Specified by:
  `sqlConcat` in interface `IDBAdapter`

### format

public String format(PreparedStatement stmt)
Description copied from interface: `IDBAdapter`
Formats a prepared statement for diagnostic output.

Specified by:
  `format` in interface `IDBAdapter`
Since:
  4.2

### format

public String format(ResultSet resultSet)
Description copied from interface: `IDBAdapter`
Formats a result set for diagnostic output.

Specified by:
  `format` in interface `IDBAdapter`
Since:
  4.2

### convertToSQL

public Object convertToSQL(Object value)
Description copied from interface: `IDBAdapter`
Converts a Java value to the value used by SQL query execution.

Specified by:
  `convertToSQL` in interface `IDBAdapter`
Since:
  4.9

### getIndexInfos

public static void getIndexInfos(DatabaseMetaData metaData, String schemaName, String tableName, Consumer<DBAdapter.IndexInfo> consumer) throws SQLException

Throws:
  `SQLException`
Since:
  4.13

### getDefaultDBLength

public static int getDefaultDBLength(DBType type)

Since:
  4.2

### generateReservedWords

protected static void generateReservedWords(Connection connection, String[] words) throws SQLException

Throws:
  `SQLException`
Since:
  4.9

### readIndices

@Deprecated protected void readIndices(Connection connection, ResultSet resultSet, IDBTable table, int indexNameColumn, int indexTypeColumn, int fieldNameColumn, int fieldPositionColumn) throws SQLException
Deprecated.
As of 4.13 no longer supported. Use `getIndexInfos(DatabaseMetaData, String, String, Consumer)` instead.

Throws:
  `SQLException`
Since:
  4.2

### createField

@Deprecated protected void createField(Connection connection, String tableName, IDBField field)
Deprecated.
As of 4.13 use `createField(Connection, IDBField)` instead.

Since:
  4.6

### dropField

@Deprecated protected void dropField(Connection connection, String tableName, String fieldName)
Deprecated.
As of 4.13 use `dropField(Connection, IDBField)` instead.

Since:
  4.6

### getJDBCDriver

@Deprecated public Driver getJDBCDriver()
Deprecated.
As of 4.2 no longer supported because of IP issues for external build dependencies (the vendor driver libs).

Specified by:
  `getJDBCDriver` in interface `IDBAdapter`
Since:
  4.2

### createJDBCDataSource

@Deprecated public DataSource createJDBCDataSource()
Deprecated.
As of 4.2 no longer supported because of IP issues for external build dependencies (the vendor driver libs).

Specified by:
  `createJDBCDataSource` in interface `IDBAdapter`
Since:
  4.2