org.apache.ignite.cache.store.jdbc

## Class CacheAbstractJdbcStore<K,V>

- java.lang.Object
- - org.apache.ignite.cache.store.jdbc.CacheAbstractJdbcStore<K,V>

- All Implemented Interfaces:
    javax.cache.integration.CacheLoader<K,V>, javax.cache.integration.CacheWriter<K,V>, CacheStore<K,V>, LifecycleAware
  Direct Known Subclasses:
    CacheJdbcPojoStore

      public abstract class CacheAbstractJdbcStore<K,V>
      extends Object
      implements CacheStore<K,V>, LifecycleAware

  Implementation of `CacheStore` backed by JDBC.

  Store works with database via SQL dialect. Ignite ships with dialects for most popular databases:

  - `DB2Dialect` - dialect for IBM DB2 database.
  - `OracleDialect` - dialect for Oracle database.
  - `SQLServerDialect` - dialect for Microsoft SQL Server database.
  - `MySQLDialect` - dialect for Oracle MySQL database.
  - `H2Dialect` - dialect for H2 database.
  - `BasicJdbcDialect` - dialect for any database via plain JDBC.

  ## Configuration

  - Data source (see `setDataSource(DataSource)`
  - Dialect (see `setDialect(JdbcDialect)`
  - Maximum batch size for writeAll and deleteAll operations. (see `setBatchSize(int)`)
  - Max workers thread count. These threads are responsible for load cache. (see `setMaximumPoolSize(int)`)
  - Parallel load cache minimum threshold. (see `setParallelLoadCacheMinimumThreshold(int)`)

  ## Java Example

          ...
          // Create store factory.
          CacheJdbcPojoStoreFactory storeFactory = new CacheJdbcPojoStoreFactory();
          storeFactory.setDataSourceBean("your_data_source_name");
          storeFactory.setDialect(new H2Dialect());
          storeFactory.setTypes(array_with_your_types);
          ...
          ccfg.setCacheStoreFactory(storeFactory);
          ccfg.setReadThrough(true);
          ccfg.setWriteThrough(true);

          cfg.setCacheConfiguration(ccfg);
          ...

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `protected static class` | `CacheAbstractJdbcStore.EntryMapping` Entry mapping description.
    `protected static class` | `CacheAbstractJdbcStore.TypeKind` Type kind.

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected static String` | `ATTR_CONN_PROP` Connection attribute property name.
    `protected static Collection<String>` | `BUILT_IN_TYPES` Built in Java types names.
    `protected Map<String,Map<Object,CacheAbstractJdbcStore.EntryMapping>>` | `cacheMappings` Cache with entry mapping description.
    `protected DataSource` | `dataSrc` Data source.
    `protected JdbcDialect` | `dialect` Database dialect.
    `protected JdbcTypeHasher` | `hasher` Hash calculator.
    `protected Ignite` | `ignite` Auto injected ignite instance.
    `protected IgniteLogger` | `log` Auto-injected logger instance.
    `protected JdbcTypesTransformer` | `transformer` Types transformer.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `CacheAbstractJdbcStore()`

  - ### Method Summary

    All Methods Instance Methods Abstract Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected abstract <R> R` | `buildObject(@Nullable String cacheName, String typeName, CacheAbstractJdbcStore.TypeKind typeKind, JdbcTypeField[] flds, Map<String,Integer> loadColIdxs, ResultSet rs)` Construct object from query result.
    `protected void` | `closeConnection(@Nullable Connection conn)` Closes connection.
    `protected Integer` | `columnIndex(Map<String,Integer> loadColIdxs, String dbName)` Find column index by database name.
    `protected Connection` | `connection()`
    `void` | `delete(Object key)`
    `void` | `deleteAll(Collection<?> keys)`
    `protected void` | `end(@Nullable Connection conn, @Nullable Statement st)` Closes allocated resources depending on transaction status.
    `protected abstract @Nullable Object` | `extractParameter(@Nullable String cacheName, String typeName, CacheAbstractJdbcStore.TypeKind typeKind, String fieldName, Object obj)` Get field value from object for use as query parameter.
    `protected int` | `fillKeyParameters(PreparedStatement stmt, CacheAbstractJdbcStore.EntryMapping m, Object key)`
    `protected int` | `fillKeyParameters(PreparedStatement stmt, int idx, CacheAbstractJdbcStore.EntryMapping em, Object key)`
    `protected void` | `fillParameter(PreparedStatement stmt, int idx, JdbcTypeField field, @Nullable Object fieldVal)` Sets the value of the designated parameter using the given object.
    `protected int` | `fillValueParameters(PreparedStatement stmt, int idx, CacheAbstractJdbcStore.EntryMapping em, Object val)`
    `int` | `getBatchSize()` Get maximum batch size for delete and delete operations.
    `DataSource` | `getDataSource()`
    `JdbcDialect` | `getDialect()` Get database dialect.
    `JdbcTypeHasher` | `getHasher()` Gets hash code calculator.
    `int` | `getMaximumPoolSize()` Get Max workers thread count.
    `int` | `getMaximumWriteAttempts()` Gets maximum number of write attempts in case of database error.
    `int` | `getParallelLoadCacheMinimumThreshold()` Parallel load cache minimum row count threshold.
    `JdbcTypesTransformer` | `getTransformer()` Gets types transformer.
    `JdbcType[]` | `getTypes()` Gets types known by store.
    `protected Ignite` | `ignite()`
    `boolean` | `isSqlEscapeAll()` If `true` all the SQL table and field names will be escaped with double quotes like ({@code "tableName"."
    `protected CacheAbstractJdbcStore.TypeKind` | `kindForName(String type)`
    `protected CacheAbstractJdbcStore.TypeKind` | `kindForName(String type, boolean binarySupported)`
    `V` | `load(K key)`
    `Map<K,V>` | `loadAll(Iterable<? extends K> keys)`
    `void` | `loadCache(IgniteBiInClosure<K,V> clo, Object... args)` Loads all values from underlying persistent storage.
    `protected Connection` | `openConnection(boolean autocommit)` Gets connection from a pool.
    `protected abstract void` | `prepareBuilders(@Nullable String cacheName, Collection<JdbcType> types)` Prepare internal store specific builders for provided types metadata.
    `protected JdbcDialect` | `resolveDialect()` Perform dialect resolution.
    `protected CacheStoreSession` | `session()`
    `void` | `sessionEnd(boolean commit)` Tells store to commit or rollback a transaction depending on the value of the `'commit'` parameter.
    `void` | `setBatchSize(int batchSize)` Set maximum batch size for write and delete operations.
    `void` | `setDataSource(DataSource dataSrc)`
    `void` | `setDialect(JdbcDialect dialect)` Set database dialect.
    `void` | `setHasher(JdbcTypeHasher hasher)` Sets hash code calculator.
    `void` | `setMaximumPoolSize(int maxPoolSize)` Set Max workers thread count.
    `void` | `setMaximumWriteAttempts(int maxWrtAttempts)` Sets maximum number of write attempts in case of database error.
    `void` | `setParallelLoadCacheMinimumThreshold(int parallelLoadCacheMinThreshold)` Parallel load cache minimum row count threshold.
    `void` | `setSqlEscapeAll(boolean sqlEscapeAll)` If `true` all the SQL table and field names will be escaped with double quotes like ({@code "tableName"."
    `void` | `setTransformer(JdbcTypesTransformer transformer)` Sets types transformer.
    `void` | `setTypes(JdbcType... types)` Sets store configurations.
    `void` | `start()` Starts grid component, called on grid start.
    `void` | `stop()` Stops grid component, called on grid shutdown.
    `protected abstract Object` | `typeIdForObject(Object obj)` Calculate type ID for object.
    `protected abstract Object` | `typeIdForTypeName(CacheAbstractJdbcStore.TypeKind kind, String typeName)` Calculate type ID for given type name.
    `void` | `write(javax.cache.Cache.Entry<? extends K,? extends V> entry)`
    `void` | `writeAll(Collection<javax.cache.Cache.Entry<? extends K,? extends V>> entries)`

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

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

- - ### Field Detail

    - #### ATTR_CONN_PROP

          protected static final String ATTR_CONN_PROP

      Connection attribute property name.
      See Also:
        Constant Field Values

    - #### BUILT_IN_TYPES

          protected static final Collection<String> BUILT_IN_TYPES

      Built in Java types names.

    - #### ignite

          @IgniteInstanceResource
          protected Ignite ignite

      Auto injected ignite instance.

    - #### log

          @LoggerResource
          protected IgniteLogger log

      Auto-injected logger instance.

    - #### dataSrc

          protected volatile DataSource dataSrc

      Data source.

    - #### cacheMappings

          protected volatile Map<String,Map<Object,CacheAbstractJdbcStore.EntryMapping>> cacheMappings

      Cache with entry mapping description. (cache name, (key id, mapping description)).

    - #### dialect

          protected JdbcDialect dialect

      Database dialect.

    - #### hasher

          protected JdbcTypeHasher hasher

      Hash calculator.

    - #### transformer

          protected JdbcTypesTransformer transformer

      Types transformer.

  - ### Constructor Detail

    - #### CacheAbstractJdbcStore

          public CacheAbstractJdbcStore()

  - ### Method Detail

    - #### extractParameter

          @Nullable
          protected abstract @Nullable Object extractParameter(@Nullable
                                                                         @Nullable String cacheName,
                                                                         String typeName,
                                                                         CacheAbstractJdbcStore.TypeKind typeKind,
                                                                         String fieldName,
                                                                         Object obj)
                                                                  throws javax.cache.CacheException

      Get field value from object for use as query parameter.
      Parameters:
        `cacheName` - Cache name.
        `typeName` - Type name.
        `typeKind` - Type kind.
        `fieldName` - Field name.
        `obj` - Cache object.
      Returns:
        Field value from object.
      Throws:
        `javax.cache.CacheException` - in case of error.

    - #### buildObject

          protected abstract <R> R buildObject(@Nullable
                                               @Nullable String cacheName,
                                               String typeName,
                                               CacheAbstractJdbcStore.TypeKind typeKind,
                                               JdbcTypeField[] flds,
                                               Map<String,Integer> loadColIdxs,
                                               ResultSet rs)
                                        throws javax.cache.integration.CacheLoaderException

      Construct object from query result.
      Type Parameters:
        `R` - Type of result object.
      Parameters:
        `cacheName` - Cache name.
        `typeName` - Type name.
        `typeKind` - Type kind.
        `flds` - Fields descriptors.
        `loadColIdxs` - Select query columns index.
        `rs` - ResultSet.
      Returns:
        Constructed object.
      Throws:
        `javax.cache.integration.CacheLoaderException` - If failed to construct cache object.

    - #### typeIdForObject

          protected abstract Object typeIdForObject(Object obj)
                                             throws javax.cache.CacheException

      Calculate type ID for object.
      Parameters:
        `obj` - Object to calculate type ID for.
      Returns:
        Type ID.
      Throws:
        `javax.cache.CacheException` - If failed to calculate type ID for given object.

    - #### typeIdForTypeName

          protected abstract Object typeIdForTypeName(CacheAbstractJdbcStore.TypeKind kind,
                                                      String typeName)
                                               throws javax.cache.CacheException

      Calculate type ID for given type name.
      Parameters:
        `kind` - If `true` then calculate type ID for POJO otherwise for binary object .
        `typeName` - String description of type name.
      Returns:
        Type ID.
      Throws:
        `javax.cache.CacheException` - If failed to get type ID for given type name.

    - #### prepareBuilders

          protected abstract void prepareBuilders(@Nullable
                                                  @Nullable String cacheName,
                                                  Collection<JdbcType> types)
                                           throws javax.cache.CacheException

      Prepare internal store specific builders for provided types metadata.
      Parameters:
        `cacheName` - Cache name to prepare builders for.
        `types` - Collection of types.
      Throws:
        `javax.cache.CacheException` - If failed to prepare internal builders for types.

    - #### resolveDialect

          protected JdbcDialect resolveDialect()
                                        throws javax.cache.CacheException

      Perform dialect resolution.
      Returns:
        The resolved dialect.
      Throws:
        `javax.cache.CacheException` - Indicates problems accessing the metadata.

    - #### start

          public void start()
                     throws IgniteException

      Starts grid component, called on grid start.
      Specified by:
        `start` in interface `LifecycleAware`
      Throws:
        `IgniteException` - If failed.

    - #### stop

          public void stop()
                    throws IgniteException

      Stops grid component, called on grid shutdown.
      Specified by:
        `stop` in interface `LifecycleAware`
      Throws:
        `IgniteException` - If failed.

    - #### openConnection

          protected Connection openConnection(boolean autocommit)
                                       throws SQLException

      Gets connection from a pool.
      Parameters:
        `autocommit` - `true` If connection should use autocommit mode.
      Returns:
        Pooled connection.
      Throws:
        `SQLException` - In case of error.

    - #### connection

          protected Connection connection()
                                   throws SQLException

      Returns:
        Connection.
      Throws:
        `SQLException` - In case of error.

    - #### closeConnection

          protected void closeConnection(@Nullable
                                         @Nullable Connection conn)

      Closes connection.
      Parameters:
        `conn` - Connection to close.

    - #### end

          protected void end(@Nullable
                             @Nullable Connection conn,
                             @Nullable
                             @Nullable Statement st)

      Closes allocated resources depending on transaction status.
      Parameters:
        `conn` - Allocated connection.
        `st` - Created statement,

    - #### sessionEnd

          public void sessionEnd(boolean commit)
                          throws javax.cache.integration.CacheWriterException

      Tells store to commit or rollback a transaction depending on the value of the `'commit'` parameter.
      Specified by:
        `sessionEnd` in interface `CacheStore<K,V>`
      Parameters:
        `commit` - `True` if transaction should commit, `false` for rollback.
      Throws:
        `javax.cache.integration.CacheWriterException` - If commit or rollback failed. Note that commit failure in some cases may bring cache transaction into `TransactionState.UNKNOWN` which will consequently cause all transacted entries to be invalidated.

    - #### kindForName

          protected CacheAbstractJdbcStore.TypeKind kindForName(String type,
                                                                boolean binarySupported)

      Parameters:
        `type` - Type name to check.
        `binarySupported` - True if binary marshaller enable.
      Returns:
        `True` if class not found.

    - #### kindForName

          protected CacheAbstractJdbcStore.TypeKind kindForName(String type)

      Parameters:
        `type` - Type name to check.
      Returns:
        `True` if class not found.

    - #### columnIndex

          protected Integer columnIndex(Map<String,Integer> loadColIdxs,
                                        String dbName)

      Find column index by database name.
      Parameters:
        `loadColIdxs` - Select query columns indexes.
        `dbName` - Column name in database.
      Returns:
        Column index.
      Throws:
        `IllegalStateException` - if column not found.

    - #### loadCache

          public void loadCache(IgniteBiInClosure<K,V> clo,
                                @Nullable
                                Object... args)
                         throws javax.cache.integration.CacheLoaderException

      Loads all values from underlying persistent storage. Note that keys are not passed, so it is up to implementation to figure out what to load. This method is called whenever `IgniteCache.loadCache(IgniteBiPredicate, Object...)` method is invoked which is usually to preload the cache from persistent storage.

      This method is optional, and cache implementation does not depend on this method to do anything. Default implementation of this method in `CacheStoreAdapter` does nothing.

      For every loaded value method `IgniteBiInClosure.apply(Object, Object)` should be called on the passed in closure. The closure will then make sure that the loaded value is stored in cache.

      Specified by:
        `loadCache` in interface `CacheStore<K,V>`
      Parameters:
        `clo` - Closure for loaded values.
        `args` - Arguments passes into `IgniteCache.loadCache(IgniteBiPredicate, Object...)` method.
      Throws:
        `javax.cache.integration.CacheLoaderException` - If loading failed.

    - #### load

          @Nullable
          public V load(K key)
                           throws javax.cache.integration.CacheLoaderException

      Specified by:
        `load` in interface `javax.cache.integration.CacheLoader<K,V>`
      Throws:
        `javax.cache.integration.CacheLoaderException`

    - #### loadAll

          public Map<K,V> loadAll(Iterable<? extends K> keys)
                           throws javax.cache.integration.CacheLoaderException

      Specified by:
        `loadAll` in interface `javax.cache.integration.CacheLoader<K,V>`
      Throws:
        `javax.cache.integration.CacheLoaderException`

    - #### write

          public void write(javax.cache.Cache.Entry<? extends K,? extends V> entry)
                     throws javax.cache.integration.CacheWriterException

      Specified by:
        `write` in interface `javax.cache.integration.CacheWriter<K,V>`
      Throws:
        `javax.cache.integration.CacheWriterException`

    - #### writeAll

          public void writeAll(Collection<javax.cache.Cache.Entry<? extends K,? extends V>> entries)
                        throws javax.cache.integration.CacheWriterException

      Specified by:
        `writeAll` in interface `javax.cache.integration.CacheWriter<K,V>`
      Throws:
        `javax.cache.integration.CacheWriterException`

    - #### delete

          public void delete(Object key)
                      throws javax.cache.integration.CacheWriterException

      Specified by:
        `delete` in interface `javax.cache.integration.CacheWriter<K,V>`
      Throws:
        `javax.cache.integration.CacheWriterException`

    - #### deleteAll

          public void deleteAll(Collection<?> keys)
                         throws javax.cache.integration.CacheWriterException

      Specified by:
        `deleteAll` in interface `javax.cache.integration.CacheWriter<K,V>`
      Throws:
        `javax.cache.integration.CacheWriterException`

    - #### fillParameter

          protected void fillParameter(PreparedStatement stmt,
                                       int idx,
                                       JdbcTypeField field,
                                       @Nullable
                                       @Nullable Object fieldVal)
                                throws javax.cache.CacheException

      Sets the value of the designated parameter using the given object.
      Parameters:
        `stmt` - Prepare statement.
        `idx` - Index for parameters.
        `field` - Field descriptor.
        `fieldVal` - Field value.
      Throws:
        `javax.cache.CacheException` - If failed to set statement parameter.

    - #### fillKeyParameters

          protected int fillKeyParameters(PreparedStatement stmt,
                                          int idx,
                                          CacheAbstractJdbcStore.EntryMapping em,
                                          Object key)
                                   throws javax.cache.CacheException

      Parameters:
        `stmt` - Prepare statement.
        `idx` - Start index for parameters.
        `em` - Entry mapping.
        `key` - Key object.
      Returns:
        Next index for parameters.
      Throws:
        `javax.cache.CacheException` - If failed to set statement parameters.

    - #### fillKeyParameters

          protected int fillKeyParameters(PreparedStatement stmt,
                                          CacheAbstractJdbcStore.EntryMapping m,
                                          Object key)
                                   throws javax.cache.CacheException

      Parameters:
        `stmt` - Prepare statement.
        `m` - Type mapping description.
        `key` - Key object.
      Returns:
        Next index for parameters.
      Throws:
        `javax.cache.CacheException` - If failed to set statement parameters.

    - #### fillValueParameters

          protected int fillValueParameters(PreparedStatement stmt,
                                            int idx,
                                            CacheAbstractJdbcStore.EntryMapping em,
                                            Object val)
                                     throws javax.cache.integration.CacheWriterException

      Parameters:
        `stmt` - Prepare statement.
        `idx` - Start index for parameters.
        `em` - Type mapping description.
        `val` - Value object.
      Returns:
        Next index for parameters.
      Throws:
        `javax.cache.CacheException` - If failed to set statement parameters.
        `javax.cache.integration.CacheWriterException`

    - #### getDataSource

          public DataSource getDataSource()

      Returns:
        Data source.

    - #### setDataSource

          public void setDataSource(DataSource dataSrc)

      Parameters:
        `dataSrc` - Data source.

    - #### getDialect

          public JdbcDialect getDialect()

      Get database dialect.
      Returns:
        Database dialect.

    - #### setDialect

          public void setDialect(JdbcDialect dialect)

      Set database dialect.
      Parameters:
        `dialect` - Database dialect.

    - #### getMaximumPoolSize

          public int getMaximumPoolSize()

      Get Max workers thread count. These threads are responsible for execute query.
      Returns:
        Max workers thread count.

    - #### setMaximumPoolSize

          public void setMaximumPoolSize(int maxPoolSize)

      Set Max workers thread count. These threads are responsible for execute query.
      Parameters:
        `maxPoolSize` - Max workers thread count.

    - #### getMaximumWriteAttempts

          public int getMaximumWriteAttempts()

      Gets maximum number of write attempts in case of database error.
      Returns:
        Maximum number of write attempts.

    - #### setMaximumWriteAttempts

          public void setMaximumWriteAttempts(int maxWrtAttempts)

      Sets maximum number of write attempts in case of database error.
      Parameters:
        `maxWrtAttempts` - Number of write attempts.

    - #### getTypes

          public JdbcType[] getTypes()

      Gets types known by store.
      Returns:
        Types known by store.

    - #### setTypes

          public void setTypes(JdbcType... types)

      Sets store configurations.
      Parameters:
        `types` - Store should process.

    - #### getHasher

          public JdbcTypeHasher getHasher()

      Gets hash code calculator.
      Returns:
        Hash code calculator.

    - #### setHasher

          public void setHasher(JdbcTypeHasher hasher)

      Sets hash code calculator.
      Parameters:
        `hasher` - Hash code calculator.

    - #### getTransformer

          public JdbcTypesTransformer getTransformer()

      Gets types transformer.
      Returns:
        Types transformer.

    - #### setTransformer

          public void setTransformer(JdbcTypesTransformer transformer)

      Sets types transformer.
      Parameters:
        `transformer` - Types transformer.

    - #### getBatchSize

          public int getBatchSize()

      Get maximum batch size for delete and delete operations.
      Returns:
        Maximum batch size.

    - #### setBatchSize

          public void setBatchSize(int batchSize)

      Set maximum batch size for write and delete operations.
      Parameters:
        `batchSize` - Maximum batch size.

    - #### getParallelLoadCacheMinimumThreshold

          public int getParallelLoadCacheMinimumThreshold()

      Parallel load cache minimum row count threshold.
      Returns:
        If `0` then load sequentially.

    - #### setParallelLoadCacheMinimumThreshold

          public void setParallelLoadCacheMinimumThreshold(int parallelLoadCacheMinThreshold)

      Parallel load cache minimum row count threshold.
      Parameters:
        `parallelLoadCacheMinThreshold` - Minimum row count threshold. If `0` then load sequentially.

    - #### isSqlEscapeAll

          public boolean isSqlEscapeAll()

      If `true` all the SQL table and field names will be escaped with double quotes like (`"tableName"."fieldsName"`). This enforces case sensitivity for field names and also allows having special characters in table and field names.
      Returns:
        Flag value.

    - #### setSqlEscapeAll

          public void setSqlEscapeAll(boolean sqlEscapeAll)

      If `true` all the SQL table and field names will be escaped with double quotes like (`"tableName"."fieldsName"`). This enforces case sensitivity for field names and also allows having special characters in table and field names.
      Parameters:
        `sqlEscapeAll` - Flag value.

    - #### ignite

          protected Ignite ignite()

      Returns:
        Ignite instance.

    - #### session

          protected CacheStoreSession session()

      Returns:
        Store session.

${current.year} Copyright © Apache Software Foundation
| Follow @ApacheIgnite
Ignite Database and Caching Platform | : ver. 2.16.0
Release Date | : December 15 2023