Package org.apache.torque.adapter

## Interface Adapter

- All Superinterfaces:
    `Serializable`
  All Known Implementing Classes:
    `AbstractAdapter`, `DerbyAdapter`, `HsqldbAdapter`, `MssqlAdapter`, `MysqlAdapter`, `NoneAdapter`, `OracleAdapter`, `PostgresAdapter`

      public interface Adapter
      extends Serializable

  `DB` defines the interface for a Torque database adapter. Support for new databases is added by implementing this interface. A couple of default settings is provided by subclassing `AbstractDBAdapter`. The new database adapter and its corresponding JDBC driver need to be registered in the service configuration file.

  The Torque 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. All database adapters need to be thread safe, as they are instantiated only once fore a given configured database and may be accessed simultaneously from several threads. *

  Version:
    $Id: Adapter.java 1850586 2019-01-06 18:46:35Z tv $
  Author:
    Jon S. Stevens, Brett McLaughlin, Daniel Rall, Augustin Vidovic, Thomas Vandahl, Greg Monroe

- - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `static String` | `ADAPTER_KEY` | Key for the configuration which contains database adapters.
    `static String` | `AUTODETECT_ADAPTER` | Special adapter for auto-detection.
    `static String` | `DRIVER_KEY` | Key for the configuration which contains database drivers.

  - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `boolean` | `escapeText()` | Determines whether backslashes (\) should be escaped in explicit SQL strings.
    `void` | `generateLimits​(Query query, long offset, int limit)` | This method is used to generate the database specific query extension to limit the number of record returned.
    `String` | `getIDMethodSQL​(Object obj)` | Returns SQL used to get the most recently inserted primary key.
    `IDMethod` | `getIDMethodType()` | Returns the constant from the `IDMethod` interface denoting which type of primary key generation method this type of RDBMS uses.
    `char` | `getStringDelimiter()` | Returns the character used to indicate the beginning and end of a piece of text used in a SQL statement (generally a single quote).
    `String` | `getUpdateLockClause()` | Returns the clause which acquires a write lock on a row when doing a select.
    `String` | `ignoreCase​(String in)` | Wraps the input string in a database function to change it to a case-insensitive representation.
    `String` | `ignoreCaseInOrderBy​(String in)` | This method is used to ignore case in an ORDER BY clause.
    `void` | `lockTable​(Connection con, String table)` | Locks the specified table.
    `void` | `setCapabilities​(DatabaseMetaData dmd)` | Update static capabilities of the adapter with actual readings based on the JDBC meta-data
    `boolean` | `supportsNativeLimit()` | This method is used to check whether the database natively supports limiting the size of the resultset.
    `boolean` | `supportsNativeOffset()` | This method is used to check whether the database natively supports returning results starting at an offset position other than 0.
    `String` | `toUpperCase​(String in)` | Wraps the input string in a database function to change it to upper case.
    `void` | `unlockTable​(Connection con, String table)` | Unlocks the specified table.
    `boolean` | `useEscapeClauseForLike()` | Whether an escape clause in like should be used.
    `boolean` | `useGetGeneratedKeys()` | whether Statement#getGeneratedKeys() should be used.
    `boolean` | `useIlike()` | Whether ILIKE should be used for case insensitive like clauses.
    `boolean` | `useMinusForExcept()` | Whether to use the MINUS operator instead of the EXCEPT operator.

- - ### Field Detail

    - #### ADAPTER_KEY

          static final String ADAPTER_KEY

      Key for the configuration which contains database adapters.
      See Also:
        Constant Field Values

    - #### DRIVER_KEY

          static final String DRIVER_KEY

      Key for the configuration which contains database drivers.
      See Also:
        Constant Field Values

    - #### AUTODETECT_ADAPTER

          static final String AUTODETECT_ADAPTER

      Special adapter for auto-detection.
      See Also:
        Constant Field Values

  - ### Method Detail

    - #### toUpperCase

          String toUpperCase​(String in)

      Wraps the input string in a database function to change it to upper case.
      Parameters:
        `in` - The string to transform to upper case, may be a literal string, a prepared statement replacement placeholder(*) or any other database expression.
      Returns:
        The wrapped input string, so that the database evaluates the returned expression to the upper case of the input.

    - #### getStringDelimiter

          char getStringDelimiter()

      Returns the character used to indicate the beginning and end of a piece of text used in a SQL statement (generally a single quote).
      Returns:
        The text delimiter.

    - #### getIDMethodType

          IDMethod getIDMethodType()

      Returns the constant from the `IDMethod` interface denoting which type of primary key generation method this type of RDBMS uses.
      Returns:
        IDMethod constant

    - #### getIDMethodSQL

          String getIDMethodSQL​(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.

    - #### getUpdateLockClause

          String getUpdateLockClause()

      Returns the clause which acquires a write lock on a row when doing a select. Most databases use the "for update" clause.
      Returns:
        the SQL clause to acquire a write lock.

    - #### lockTable

          void lockTable​(Connection con,
                         String table)
                  throws SQLException

      Locks the specified table.
      Parameters:
        `con` - The JDBC connection to use.
        `table` - The name of the table to lock.
      Throws:
        `SQLException` - No Statement could be created or executed.

    - #### unlockTable

          void unlockTable​(Connection con,
                           String table)
                    throws SQLException

      Unlocks the specified table.
      Parameters:
        `con` - The JDBC connection to use.
        `table` - The name of the table to unlock.
      Throws:
        `SQLException` - No Statement could be created or executed.

    - #### ignoreCase

          String ignoreCase​(String in)

      Wraps the input string in a database function to change it to a case-insensitive representation.
      Parameters:
        `in` - The string to transform to a case-insensitive representation, may be a literal string, a prepared statement replacement placeholder(*) or any other database expression.
      Returns:
        The wrapped input string, so that the database evaluates the returned expression to a case-insensitive representation of the input.

    - #### ignoreCaseInOrderBy

          String ignoreCaseInOrderBy​(String in)

      This method is used to ignore case in an ORDER BY clause. Usually it is the same as ignoreCase, but some databases (hsqldb 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.

    - #### supportsNativeLimit

          boolean supportsNativeLimit()

      This method is used to check 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

          boolean supportsNativeOffset()

      This method is used to check 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.

    - #### generateLimits

          void generateLimits​(Query query,
                              long offset,
                              int limit)
                       throws TorqueException

      This method is used to generate the database specific query extension to limit the number of record returned.
      Parameters:
        `query` - The query to modify
        `offset` - the offset Value
        `limit` - the limit Value
      Throws:
        `TorqueException` - if any error occurs when building the query

    - #### escapeText

          boolean escapeText()

      Determines whether backslashes (\) should be escaped in explicit SQL strings. If true is returned, a BACKSLASH will be changed to "\\". If false is returned, a BACKSLASH will be left as "\".
      Returns:
        true if the database needs to escape backslashes in SqlExpressions.

    - #### useIlike

          boolean useIlike()

      Whether ILIKE should be used for case insensitive like clauses.
      Returns:
        true if ilike should be used for case insensitive likes, false if ignoreCase should be applied to the compared strings.

    - #### useEscapeClauseForLike

          boolean useEscapeClauseForLike()

      Whether an escape clause in like should be used. Example : select * from AUTHOR where AUTHOR.NAME like '\_%' ESCAPE '\';
      Returns:
        whether the escape clause should be appended or not.

    - #### useMinusForExcept

          boolean useMinusForExcept()

      Whether to use the MINUS operator instead of the EXCEPT operator.
      Returns:
        whether to use the MINUS operator instead of the EXCEPT operator.

    - #### useGetGeneratedKeys

          boolean useGetGeneratedKeys()

      whether Statement#getGeneratedKeys() should be used.
      Returns:
        a `boolean` value

    - #### setCapabilities

          void setCapabilities​(DatabaseMetaData dmd)
                        throws SQLException

      Update static capabilities of the adapter with actual readings based on the JDBC meta-data
      Parameters:
        `dmd` - database meta data
      Throws:
        `SQLException` - if there are problems getting the JDBC meta data