org.firebirdsql.jdbc

## Class AbstractGeneratedKeysQuery

- java.lang.Object
- - org.firebirdsql.jdbc.AbstractGeneratedKeysQuery

- Direct Known Subclasses:
    FBConnection.GeneratedKeysQuery

      public abstract class AbstractGeneratedKeysQuery
      extends java.lang.Object

  Class to add the RETURNING clause to queries for returning generated keys.
  Since:
    2.2
  Author:
    Mark Rotteveel

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `AbstractGeneratedKeysQuery(java.lang.String sql, int autoGeneratedKeys)` Process SQL statement text according to autoGeneratedKeys value.
    `AbstractGeneratedKeysQuery(java.lang.String sql, int[] columnIndexes)` Process SQL statement for adding generated key columns by their ordinal position.
    `AbstractGeneratedKeysQuery(java.lang.String sql, java.lang.String[] columnNames)` Process SQL statement for adding generated key columns by name.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `boolean` | `generatesKeys()` Indicates if the query will generate keys.
    `java.lang.String` | `getQueryString()` Returns the actual query.
    `static boolean` | `isGeneratedKeysSupportLoaded()` Indicates if generated keys support has been loaded and available for use.

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

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

- - ### Constructor Detail

    - #### AbstractGeneratedKeysQuery

          public AbstractGeneratedKeysQuery(java.lang.String sql,
                                    int autoGeneratedKeys)
                                     throws java.sql.SQLException

      Process SQL statement text according to autoGeneratedKeys value.

      For Statement.NO_GENERATED_KEYS the statement will not be processed, for Statement.RETURN_GENERATED_KEYS it will be processed.

      The query will only be modified if 1) it is capable of returning keys (ie INSERT, DELETE and UPDATE) and 2) does not already contain a RETURNING clause.

      Parameters:
        `sql` - SQL statement
        `autoGeneratedKeys` - Valid values `Statement.NO_GENERATED_KEYS` and `Statement.RETURN_GENERATED_KEYS`
      Throws:
        `java.sql.SQLException` - If the supplied autoGeneratedKeys value does not match valid values or if the parser cannot be loaded when autoGeneratedKeys = RETURN_GENERATED_KEYS.

    - #### AbstractGeneratedKeysQuery

          public AbstractGeneratedKeysQuery(java.lang.String sql,
                                    int[] columnIndexes)
                                     throws java.sql.SQLException

      Process SQL statement for adding generated key columns by their ordinal position.

      The query will only be modified if 1) it is capable of returning keys (ie INSERT, DELETE and UPDATE) and 2) does not already contain a RETURNING clause.

      The columns are added in ascending order of their index value, not by the order of indexes in the columnIndexes array. The values of columnIndexes are taken as the ORDINAL_POSITION returned by `DatabaseMetaData.getColumns(String, String, String, String)` . When a column index does not exist for the table of the query, then it will be discarded from the list silently.

      Parameters:
        `sql` - SQL statement
        `columnIndexes` - Array of ORDINAL_POSITION values of the columns to return as generated key
      Throws:
        `java.sql.SQLException` - If the parser cannot be loaded

    - #### AbstractGeneratedKeysQuery

          public AbstractGeneratedKeysQuery(java.lang.String sql,
                                    java.lang.String[] columnNames)
                                     throws java.sql.SQLException

      Process SQL statement for adding generated key columns by name.

      The query will only be modified if 1) it is capable of returning keys (ie INSERT, DELETE and UPDATE) and 2) does not already contain a RETURNING clause.

      The columnNames passed are taken as is and included in a new returning clause. There is no check for actual existence of these columns, nor are they quoted.

      Parameters:
        `sql` - SQL statement
        `columnNames` - Array of column names to return as generated key
      Throws:
        `java.sql.SQLException` - If the parser cannot be loaded

  - ### Method Detail

    - #### generatesKeys

          public boolean generatesKeys()
                                throws java.sql.SQLException

      Indicates if the query will generate keys.
      Returns:
        `true` if the query will generate keys, `false` otherwise
      Throws:
        `java.sql.SQLException` - For errors accessing the metadata

    - #### getQueryString

          public java.lang.String getQueryString()
                                          throws java.sql.SQLException

      Returns the actual query.

      Use `generatesKeys()` to see if this query will in fact generate keys.

      Returns:
        The SQL query
      Throws:
        `java.sql.SQLException` - For errors accessing the metadata

    - #### isGeneratedKeysSupportLoaded

          public static boolean isGeneratedKeysSupportLoaded()

      Indicates if generated keys support has been loaded and available for use.

      This method returns `false` when the antlr-runtime is not on the classpath or the `StatementParser` implementation could not be loaded for other reasons.

      Returns:
        `true` if generated keys can be used in the driver (assuming the Firebird version supports it)

Copyright © 2001-2021 Jaybird (Firebird JDBC/JCA) team. All rights reserved.