# Interface DbAdapter

All Known Implementing Classes:
  `AutoAdapter, DB2Adapter, DerbyAdapter, FirebirdAdapter, FrontBaseAdapter, H2Adapter, HSQLDBAdapter, IngresAdapter, JdbcAdapter, MySQLAdapter, OracleAdapter, PostgresAdapter, SQLiteAdapter, SQLServerAdapter, SybaseAdapter`

public interface DbAdapter
A Cayenne extension point that abstracts the differences between specifics of JDBC interfaces to various databases. Cayenne already ships with a number of built-in adapters for most common databases and users can provide their own custom adapters.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `bindParameter(CallableStatement statement, CSParameter<?> parameter)`
  Binds an object value to CallableStatement's parameter.
  `void`
  `bindParameter(PreparedStatement statement, PSParameter<?> parameter)`
  Binds an object value to PreparedStatement's parameter.
  `DbAttribute`
  `buildAttribute(String name, String typeName, int type, int size, int scale, boolean allowNulls)`
  Creates and returns a DbAttribute based on supplied parameters (usually obtained from database metadata).
  `String`
  `createFkConstraint(DbRelationship rel)`
  Returns a SQL string that can be used to create a foreign key constraint for the relationship, or null if foreign keys are not supported.
  `PkGenerator`
  `createPkGenerator()`
  Returns a new primary key generator of the default type associated with this adapter.
  `String`
  `createTable(DbEntity entity)`
  Returns a SQL string that can be used to create database table corresponding to `entity` parameter.
  `void`
  `createTableAppendColumn(StringBuffer sqlBuffer, DbAttribute column)`
  Append the column type part of a "create table" to the given `StringBuffer`
  `String`
  `createUniqueConstraint(DbEntity source, Collection<DbAttribute> columns)`
  Returns a DDL string to create a unique constraint over a set of columns, or null if the unique constraints are not supported.
  `int`
  `defaultCharColumnLength()`
  Returns the length to use for an unconstrained character column (a CHAR/VARCHAR-family column with no max length) when this database requires a length.
  `Collection<String>`
  `dropTableStatements(DbEntity table)`
  Returns a collection of SQL statements needed to drop a database table.
  `String[]`
  `externalTypesForJdbcType(int type)`
  Deprecated, for removal: This API element is subject to removal in a future version.
  use `nativeColumnTypes(int)`
  `SQLAction`
  `getAction(Query query, DataNode node)`
  Returns an instance of SQLAction that should handle the query.
  `String`
  `getBatchTerminator()`
  Returns a String used to terminate a batch in command-line tools.
  `EJBQLTranslator`
  `getEjbqlTranslator()`
  Returns the `EJBQLTranslator` for EJBQL to SQL translation.
  `default EJBQLTranslator`
  `getEjbqlTranslatorFactory()`
  Deprecated, for removal: This API element is subject to removal in a future version.
  in favor of `getEjbqlTranslator()`.
  `ExtendedTypeMap`
  `getExtendedTypes()`
  Returns a map of ExtendedTypes that is used to translate values between Java and JDBC layer.
  `ProcedureTranslator`
  `getProcedureTranslator(ProcedureQuery query, EntityResolver entityResolver)`
  Returns the `ProcedureTranslator` for the given query.
  `QuotingStrategy`
  `getQuotingStrategy()`
  Deprecated, for removal: This API element is subject to removal in a future version.
  in favor of `getQuotingStrategy(DbEntity)`
  `QuotingStrategy`
  `getQuotingStrategy(DbEntity entity)`
  Resolves the `QuotingStrategy` to use for the given entity: this adapter's strategy when the entity's DataMap enables SQL identifier quoting, and `QuotingStrategy.NONE` otherwise.
  `SelectTranslator`
  `getSelectTranslator(Select<?> query, EntityResolver entityResolver)`
  Returns the `SelectTranslator` for the given query.
  `SQLTreeProcessor`
  `getSqlTreeProcessor()`
  `List<String>`
  `getSystemCatalogs()`
  `List<String>`
  `getSystemSchemas()`
  `NativeColumnType[]`
  `nativeColumnTypes(int type)`
  Returns the database-native types that the given JDBC `type` (see `Types`) maps to, or null if the type is not supported.
  `default int`
  `preferredBindingType(int jdbcType)`
  Returns the JDBC type that this adapter prefers to bind for a given mapped JDBC type.
  `default NativeColumnType`
  `preferredNativeColumnType(DbAttribute column)`
  `boolean`
  `supportsBatchUpdates()`
  Returns `true` if the target database supports batch updates.
  `boolean`
  `supportsCatalogsOnReverseEngineering()`
  Returns true if a target database supports catalogs on reverse engineering.
  `boolean`
  `supportsGeneratedKeys()`
  Returns true if a target database supports key autogeneration.
  `default boolean`
  `supportsGeneratedKeysForBatchInserts()`
  Returns true if a target database supports key autogeneration in a batch insert.
  `boolean`
  `supportsUniqueConstraints()`
  Returns true if a target database supports UNIQUE constraints.
  `String`
  `tableTypeForTable()`
  Returns the name of the table type (as returned by `DatabaseMetaData.getTableTypes`) for a simple user table.
  `String`
  `tableTypeForView()`
  Returns the name of the table type (as returned by `DatabaseMetaData.getTableTypes`) for a view table.
  `boolean`
  `typeSupportsLength(int type)`
  `boolean`
  `typeSupportsScale(int type)`
  Returns true if supplied type can have a scale attribute as a part of column definition.
  `DbAdapter`
  `unwrap()`
  Allows the users to get access to the adapter decorated by a given adapter.

- ## Method Details

  - ### getBatchTerminator

    String getBatchTerminator()
    Returns a String used to terminate a batch in command-line tools. E.g. ";" on Oracle or "go" on Sybase.
    Since:
      1.0.4

  - ### getSelectTranslator

    SelectTranslator getSelectTranslator(Select<?> query, EntityResolver entityResolver)
    Returns the `SelectTranslator` for the given query. The default implementation ignores the query, but the parameter is retained so adapters can pick a translator based on it.
    Since:
      4.2

  - ### getProcedureTranslator

    ProcedureTranslator getProcedureTranslator(ProcedureQuery query, EntityResolver entityResolver)
    Returns the `ProcedureTranslator` for the given query. The default implementation ignores the query, but the parameter is retained so adapters can pick a translator based on it.
    Since:
      5.0

  - ### getSqlTreeProcessor

    SQLTreeProcessor getSqlTreeProcessor()
    Returns:
      `SQLTreeProcessor` that can adjust SQL tree to specific database flavour
    Since:
      4.2

  - ### getAction

    SQLAction getAction(Query query, DataNode node)
    Returns an instance of SQLAction that should handle the query.
    Since:
      1.2

  - ### supportsUniqueConstraints

    boolean supportsUniqueConstraints()
    Returns true if a target database supports UNIQUE constraints.
    Since:
      1.1

  - ### supportsCatalogsOnReverseEngineering

    boolean supportsCatalogsOnReverseEngineering()
    Returns true if a target database supports catalogs on reverse engineering.
    Since:
      4.0

  - ### supportsGeneratedKeys

    boolean supportsGeneratedKeys()
    Returns true if a target database supports key autogeneration. This feature also requires JDBC3-compliant driver.
    Since:
      1.2

  - ### supportsGeneratedKeysForBatchInserts

    default boolean supportsGeneratedKeysForBatchInserts()
    Returns true if a target database supports key autogeneration in a batch insert.
    Since:
      4.2
    See Also:
      - `supportsGeneratedKeys()`

  - ### supportsBatchUpdates

    boolean supportsBatchUpdates()
    Returns `true` if the target database supports batch updates.

  - ### typeSupportsLength

    boolean typeSupportsLength(int type)

  - ### typeSupportsScale

    boolean typeSupportsScale(int type)
    Returns true if supplied type can have a scale attribute as a part of column definition.
    Since:
      5.0

  - ### defaultCharColumnLength

    int defaultCharColumnLength()
    Returns the length to use for an unconstrained character column (a CHAR/VARCHAR-family column with no max length) when this database requires a length.
    Since:
      5.0

  - ### preferredNativeColumnType

    default NativeColumnType preferredNativeColumnType(DbAttribute column)
    Since:
      5.0

  - ### dropTableStatements

    Collection<String> dropTableStatements(DbEntity table)
    Returns a collection of SQL statements needed to drop a database table.
    Since:
      3.0

  - ### createTable

    String createTable(DbEntity entity)
    Returns a SQL string that can be used to create database table corresponding to `entity` parameter.

  - ### createUniqueConstraint

    String createUniqueConstraint(DbEntity source, Collection<DbAttribute> columns)
    Returns a DDL string to create a unique constraint over a set of columns, or null if the unique constraints are not supported.
    Since:
      1.1

  - ### createFkConstraint

    String createFkConstraint(DbRelationship rel)
    Returns a SQL string that can be used to create a foreign key constraint for the relationship, or null if foreign keys are not supported.

  - ### externalTypesForJdbcType

    @Deprecated(since="5.0", forRemoval=true) String[] externalTypesForJdbcType(int type)
    Deprecated, for removal: This API element is subject to removal in a future version.
    use `nativeColumnTypes(int)`
    Returns an array of RDBMS types that can be used with JDBC `type`. Valid JDBC types are defined in java.sql.Types.

  - ### nativeColumnTypes

    NativeColumnType[] nativeColumnTypes(int type)
    Returns the database-native types that the given JDBC `type` (see `Types`) maps to, or null if the type is not supported. The first variant is used for column DDL.
    Since:
      5.0

  - ### getExtendedTypes

    ExtendedTypeMap getExtendedTypes()
    Returns a map of ExtendedTypes that is used to translate values between Java and JDBC layer.

  - ### createPkGenerator

    PkGenerator createPkGenerator()
    Returns a new primary key generator of the default type associated with this adapter. DataNode would use this generator, unless explicitly overridden. DbAdapter does not cache the generator as it is often stateful.
    Since:
      5.0

  - ### buildAttribute

    DbAttribute buildAttribute(String name, String typeName, int type, int size, int scale, boolean allowNulls)
    Creates and returns a DbAttribute based on supplied parameters (usually obtained from database metadata).
    Parameters:
      `name` - database column name
      `typeName` - database specific type name, may be used as a hint to determine the right JDBC type.
      `type` - JDBC column type
      `size` - database column size (ignored if less than zero)
      `scale` - database column scale, i.e. the number of decimal digits (ignored if less than zero)
      `allowNulls` - database column nullable parameter

  - ### bindParameter

    void bindParameter(PreparedStatement statement, PSParameter<?> parameter) throws Exception
    Binds an object value to PreparedStatement's parameter.
    Throws:
      `Exception`
    Since:
      5.0

  - ### bindParameter

    void bindParameter(CallableStatement statement, CSParameter<?> parameter) throws Exception
    Binds an object value to CallableStatement's parameter.
    Throws:
      `Exception`
    Since:
      5.0

  - ### preferredBindingType

    default int preferredBindingType(int jdbcType)
    Returns the JDBC type that this adapter prefers to bind for a given mapped JDBC type. The default implementation is an identity function; adapters whose drivers require a different type (e.g. remapping the `N*` character types to their non-national counterparts) override this. The returned type is resolved into the `PSParameter` at binding creation time, so it matches the type actually sent to the PreparedStatement.
    Since:
      5.0

  - ### tableTypeForTable

    String tableTypeForTable()
    Returns the name of the table type (as returned by `DatabaseMetaData.getTableTypes`) for a simple user table.

  - ### tableTypeForView

    String tableTypeForView()
    Returns the name of the table type (as returned by `DatabaseMetaData.getTableTypes`) for a view table.

  - ### createTableAppendColumn

    void createTableAppendColumn(StringBuffer sqlBuffer, DbAttribute column)
    Append the column type part of a "create table" to the given `StringBuffer`
    Parameters:
      `sqlBuffer` - the `StringBuffer` to append the column type to
      `column` - the `DbAttribute` defining the column to append type for
    Since:
      3.0

  - ### getQuotingStrategy

    @Deprecated(since="5.0", forRemoval=true) QuotingStrategy getQuotingStrategy()
    Deprecated, for removal: This API element is subject to removal in a future version.
    in favor of `getQuotingStrategy(DbEntity)`
    Returns the SQL identifier quoting style (start/end quote characters) for this adapter. Whether quoting is applied is decided by the caller, which uses this instance when quoting is enabled and `QuotingStrategy.NONE` otherwise.
    Since:
      4.0

  - ### getQuotingStrategy

    QuotingStrategy getQuotingStrategy(DbEntity entity)
    Resolves the `QuotingStrategy` to use for the given entity: this adapter's strategy when the entity's DataMap enables SQL identifier quoting, and `QuotingStrategy.NONE` otherwise.
    Since:
      5.0

  - ### unwrap

    DbAdapter unwrap()
    Allows the users to get access to the adapter decorated by a given adapter.
    Since:
      4.0

  - ### getEjbqlTranslator

    EJBQLTranslator getEjbqlTranslator()
    Returns the `EJBQLTranslator` for EJBQL to SQL translation.
    Since:
      5.0

  - ### getEjbqlTranslatorFactory

    @Deprecated(since="5.0", forRemoval=true) default EJBQLTranslator getEjbqlTranslatorFactory()
    Deprecated, for removal: This API element is subject to removal in a future version.
    in favor of `getEjbqlTranslator()`.

  - ### getSystemCatalogs

    List<String> getSystemCatalogs()
    Returns:
      list of system catalogs
    Since:
      4.1

  - ### getSystemSchemas

    List<String> getSystemSchemas()
    Returns:
      list of system schemas
    Since:
      4.1