Package org.apache.cayenne.dba

## Class JdbcPkGenerator

- java.lang.Object
- - org.apache.cayenne.dba.JdbcPkGenerator

- All Implemented Interfaces:
    `PkGenerator`
  Direct Known Subclasses:
    `FrontBasePkGenerator`, `MySQLPkGenerator`, `OpenBasePkGenerator`, `OraclePkGenerator`, `SybasePkGenerator`

      public class JdbcPkGenerator
      extends Object
      implements PkGenerator

  Default primary key generator implementation. Uses a lookup table named "AUTO_PK_SUPPORT" to search and increment primary keys for tables.

- - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `protected JdbcAdapter` | `adapter` |
    `static int` | `DEFAULT_PK_CACHE_SIZE` |
    `protected ConcurrentMap<String,​Queue<Long>>` | `pkCache` |
    `protected int` | `pkCacheSize` |
    `protected long` | `pkStartValue` |

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `JdbcPkGenerator()` |
    `JdbcPkGenerator​(JdbcAdapter adapter)` |

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `protected boolean` | `autoPkTableExists​(DataNode node)` | Checks if AUTO_PK_TABLE already exists in the database.
    `void` | `createAutoPk​(DataNode node, List<DbEntity> dbEntities)` | Generates necessary database objects to provide automatic primary key support.
    `List<String>` | `createAutoPkStatements​(List<DbEntity> dbEntities)` | Returns a list of SQL strings needed to generates database objects to provide automatic primary support for the list of entities.
    `void` | `dropAutoPk​(DataNode node, List<DbEntity> dbEntities)` | Drops table named "AUTO_PK_SUPPORT" if it exists in the database.
    `List<String>` | `dropAutoPkStatements​(List<DbEntity> dbEntities)` | Returns SQL string needed to drop database objects associated with automatic primary key generation.
    `protected String` | `dropAutoPkString()` |
    `Object` | `generatePk​(DataNode node, DbAttribute pk)` | Generates a unique and non-repeating primary key for specified dbEntity.
    `JdbcAdapter` | `getAdapter()` | Get an adapter associated with current PkGenerator
    `int` | `getPkCacheSize()` | Returns a size of the entity primary key cache.
    `protected long` | `longPkFromDatabase​(DataNode node, DbEntity entity)` | Performs primary key generation ignoring cache.
    `protected String` | `pkCreateString​(String entName)` |
    `protected String` | `pkDeleteString​(List<DbEntity> dbEntities)` |
    `protected String` | `pkSelectString​(String entName)` |
    `protected String` | `pkTableCreateString()` |
    `protected String` | `pkUpdateString​(String entName)` |
    `void` | `reset()` | Resets any cached primary keys forcing generator to go to the database next time id generation is requested.
    `int` | `runUpdate​(DataNode node, String sql)` | Runs JDBC update over a Connection obtained from DataNode.
    `void` | `setAdapter​(DbAdapter adapter)` | Install the adapter associated with current PkGenerator
    `void` | `setPkCacheSize​(int pkCacheSize)` | Sets the size of the entity primary key cache.

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

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

- - ### Field Detail

    - #### DEFAULT_PK_CACHE_SIZE

          public static final int DEFAULT_PK_CACHE_SIZE

      See Also:
        Constant Field Values

    - #### adapter

          protected JdbcAdapter adapter

    - #### pkCache

          protected ConcurrentMap<String,​Queue<Long>> pkCache

    - #### pkCacheSize

          protected int pkCacheSize

    - #### pkStartValue

          protected long pkStartValue

  - ### Constructor Detail

    - #### JdbcPkGenerator

          public JdbcPkGenerator()

      Since:
        4.1

    - #### JdbcPkGenerator

          public JdbcPkGenerator​(JdbcAdapter adapter)

  - ### Method Detail

    - #### getAdapter

          public JdbcAdapter getAdapter()

      Description copied from interface: `PkGenerator`
      Get an adapter associated with current PkGenerator
      Specified by:
        `getAdapter` in interface `PkGenerator`

    - #### createAutoPk

          public void createAutoPk​(DataNode node,
                                   List<DbEntity> dbEntities)
                            throws Exception

      Description copied from interface: `PkGenerator`
      Generates necessary database objects to provide automatic primary key support.
      Specified by:
        `createAutoPk` in interface `PkGenerator`
      Parameters:
        `node` - node that provides access to a DataSource.
        `dbEntities` - a list of entities that require primary key auto-generation support
      Throws:
        `Exception`

    - #### createAutoPkStatements

          public List<String> createAutoPkStatements​(List<DbEntity> dbEntities)

      Description copied from interface: `PkGenerator`
      Returns a list of SQL strings needed to generates database objects to provide automatic primary support for the list of entities. No actual database operations are performed.
      Specified by:
        `createAutoPkStatements` in interface `PkGenerator`

    - #### dropAutoPk

          public void dropAutoPk​(DataNode node,
                                 List<DbEntity> dbEntities)
                          throws Exception

      Drops table named "AUTO_PK_SUPPORT" if it exists in the database.
      Specified by:
        `dropAutoPk` in interface `PkGenerator`
      Parameters:
        `node` - node that provides access to a DataSource.
        `dbEntities` - a list of entities whose primary key auto-generation support should be dropped.
      Throws:
        `Exception`

    - #### dropAutoPkStatements

          public List<String> dropAutoPkStatements​(List<DbEntity> dbEntities)

      Description copied from interface: `PkGenerator`
      Returns SQL string needed to drop database objects associated with automatic primary key generation. No actual database operations are performed.
      Specified by:
        `dropAutoPkStatements` in interface `PkGenerator`

    - #### pkTableCreateString

          protected String pkTableCreateString()

    - #### pkDeleteString

          protected String pkDeleteString​(List<DbEntity> dbEntities)

    - #### pkCreateString

          protected String pkCreateString​(String entName)

    - #### pkSelectString

          protected String pkSelectString​(String entName)

    - #### pkUpdateString

          protected String pkUpdateString​(String entName)

    - #### dropAutoPkString

          protected String dropAutoPkString()

    - #### autoPkTableExists

          protected boolean autoPkTableExists​(DataNode node)
                                       throws SQLException

      Checks if AUTO_PK_TABLE already exists in the database.
      Throws:
        `SQLException`

    - #### runUpdate

          public int runUpdate​(DataNode node,
                               String sql)
                        throws SQLException

      Runs JDBC update over a Connection obtained from DataNode. Returns a number of objects returned from update.
      Throws:
        `SQLException` - in case of query failure.

    - #### generatePk

          public Object generatePk​(DataNode node,
                                   DbAttribute pk)
                            throws Exception

      Generates a unique and non-repeating primary key for specified dbEntity.

      This implementation is naive since it does not lock the database rows when executing select and subsequent update. Adapter-specific implementations are more robust.

      Specified by:
        `generatePk` in interface `PkGenerator`
      Throws:
        `Exception`
      Since:
        3.0

    - #### setAdapter

          public void setAdapter​(DbAdapter adapter)

      Description copied from interface: `PkGenerator`
      Install the adapter associated with current PkGenerator
      Specified by:
        `setAdapter` in interface `PkGenerator`

    - #### longPkFromDatabase

          protected long longPkFromDatabase​(DataNode node,
                                            DbEntity entity)
                                     throws Exception

      Performs primary key generation ignoring cache. Generates a range of primary keys as specified by "pkCacheSize" bean property.

      This method is called internally from "generatePkForDbEntity" and then generated range of key values is saved in cache for performance. Subclasses that implement different primary key generation solutions should override this method, not "generatePkForDbEntity".

      Throws:
        `Exception`
      Since:
        3.0

    - #### getPkCacheSize

          public int getPkCacheSize()

      Returns a size of the entity primary key cache. Default value is 20. If cache size is set to a value less or equals than "one", no primary key caching is done.

    - #### setPkCacheSize

          public void setPkCacheSize​(int pkCacheSize)

      Sets the size of the entity primary key cache. If `pkCacheSize` parameter is less than 1, cache size is set to "one".

      Note that our tests show that setting primary key cache value to anything much bigger than 20 does not give any significant performance increase. Therefore it does not make sense to use bigger values, since this may potentially create big gaps in the database primary key sequences in cases like application crashes or restarts.

    - #### reset

          public void reset()

      Description copied from interface: `PkGenerator`
      Resets any cached primary keys forcing generator to go to the database next time id generation is requested. May not be applicable for all generator implementations.
      Specified by:
        `reset` in interface `PkGenerator`