org.apache.torque.adapter

## Class AbstractAdapter

- java.lang.Object
- - org.apache.torque.adapter.AbstractAdapter

- All Implemented Interfaces:
    Serializable, Adapter
  Direct Known Subclasses:
    DerbyAdapter, HsqldbAdapter, MssqlAdapter, MysqlAdapter, NoneAdapter, OracleAdapter, PostgresAdapter

      public abstract class AbstractAdapter
      extends Object
      implements Adapter

  This class is the abstract base for any database adapter Support for new databases is added by subclassing this class and implementing its abstract methods, and by registering the new database adapter and its corresponding JDBC driver 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.

  Version:
    $Id: AbstractAdapter.java 1850586 2019-01-06 18:46:35Z tv $
  Author:
    Jon S. Stevens, Brett McLaughlin, Daniel Rall, Augustin Vidovic, Greg Monroe
  See Also:
    Serialized Form

- - ### Field Summary

    - ### Fields inherited from interface org.apache.torque.adapter.Adapter

      `ADAPTER_KEY, AUTODETECT_ADAPTER, DRIVER_KEY`

  - ### Constructor Summary

    Constructors
    Modifier | Constructor and Description
    --- | ---
    `protected` | `AbstractAdapter()` Empty constructor.

  - ### Method Summary

    All Methods Instance Methods Abstract Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `boolean` | `escapeText()` This method is for the SqlExpression.quoteAndEscape rules.
    `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.
    `abstract String` | `getIDMethodSQL(Object obj)` Returns SQL used to get the most recently inserted primary key.
    `abstract 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.
    `abstract 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.
    `abstract 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()` Returns whether the database can natively limit the size of the ResultSet of a query.
    `boolean` | `supportsNativeOffset()` Returns whether the database natively supports returning results starting at an offset position other than 0.
    `abstract String` | `toUpperCase(String in)` Wraps the input string in a database function to change it to upper case.
    `abstract 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.

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

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

- - ### Constructor Detail

    - #### AbstractAdapter

          protected AbstractAdapter()

      Empty constructor.

  - ### Method Detail

    - #### toUpperCase

          public abstract String toUpperCase(String in)

      Wraps the input string in a database function to change it to upper case.
      Specified by:
        `toUpperCase` in interface `Adapter`
      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

          public 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).
      Specified by:
        `getStringDelimiter` in interface `Adapter`
      Returns:
        The text delimiter.

    - #### getIDMethodType

          public abstract IDMethod getIDMethodType()

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

    - #### getIDMethodSQL

          public abstract String getIDMethodSQL(Object obj)

      Returns SQL used to get the most recently inserted primary key. Databases which have no support for this return `null`.
      Specified by:
        `getIDMethodSQL` in interface `Adapter`
      Parameters:
        `obj` - Information used for key generation.
      Returns:
        The most recently inserted database key.

    - #### getUpdateLockClause

          public String getUpdateLockClause()

      Returns the clause which acquires a write lock on a row when doing a select.
      Specified by:
        `getUpdateLockClause` in interface `Adapter`
      Returns:
        the SQL clause to acquire a write lock. This implementation returns "FOR UPDATE";

    - #### lockTable

          public abstract void lockTable(Connection con,
                                         String table)
                                  throws SQLException

      Locks the specified table.
      Specified by:
        `lockTable` in interface `Adapter`
      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

          public abstract void unlockTable(Connection con,
                                           String table)
                                    throws SQLException

      Unlocks the specified table.
      Specified by:
        `unlockTable` in interface `Adapter`
      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

          public abstract String ignoreCase(String in)

      Wraps the input string in a database function to change it to a case-insensitive representation.
      Specified by:
        `ignoreCase` in interface `Adapter`
      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

          public 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) do not use the same SQL in ORDER BY and other clauses.
      Specified by:
        `ignoreCaseInOrderBy` in interface `Adapter`
      Parameters:
        `in` - The string whose case to ignore.
      Returns:
        The string in a case that can be ignored.

    - #### supportsNativeLimit

          public boolean supportsNativeLimit()

      Returns whether the database can natively limit the size of the ResultSet of a query.
      Specified by:
        `supportsNativeLimit` in interface `Adapter`
      Returns:
        true if the database natively supports limiting the size of the resultset.

    - #### supportsNativeOffset

          public boolean supportsNativeOffset()

      Returns whether the database natively supports returning results starting at an offset position other than 0.
      Specified by:
        `supportsNativeOffset` in interface `Adapter`
      Returns:
        true if the database natively supports returning results starting at an offset position other than 0.

    - #### generateLimits

          public 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.
      Specified by:
        `generateLimits` in interface `Adapter`
      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

          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 "\".
      Specified by:
        `escapeText` in interface `Adapter`
      Returns:
        true if the database needs to escape text in SqlExpressions.

    - #### useIlike

          public boolean useIlike()

      Whether ILIKE should be used for case insensitive like clauses. As most databases do not use ILIKE, this implementation returns false. This behaviour may be overwritten in subclasses.
      Specified by:
        `useIlike` in interface `Adapter`
      Returns:
        true if ilike should be used for case insensitive likes, false if ignoreCase should be applied to the compared strings.

    - #### useEscapeClauseForLike

          public boolean useEscapeClauseForLike()

      Whether an escape clause in like should be used. Example : select * from AUTHOR where AUTHOR.NAME like '\_%' ESCAPE '\'; As most databases do not need the escape clause, this implementation always returns `false`. This behaviour can be overwritten in subclasses.
      Specified by:
        `useEscapeClauseForLike` in interface `Adapter`
      Returns:
        whether the escape clause should be appended or not.

    - #### useMinusForExcept

          public boolean useMinusForExcept()

      Whether to use the MINUS operator instead of the EXCEPT operator. As most databases do not need to replace the EXCEPT operator by the MINUS operator, this implementation always returns `false`. This behaviour can be overwritten in subclasses.
      Specified by:
        `useMinusForExcept` in interface `Adapter`
      Returns:
        whether to use the MINUS operator instead of the EXCEPT operator.

    - #### useGetGeneratedKeys

          public boolean useGetGeneratedKeys()

      whether Statement#getGeneratedKeys() should be used.
      Specified by:
        `useGetGeneratedKeys` in interface `Adapter`
      Returns:
        a `boolean` value

    - #### setCapabilities

          public void setCapabilities(DatabaseMetaData dmd)
                               throws SQLException

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

Copyright © 2000–2020 The Apache Software Foundation. All rights reserved.