Package org.apache.ignite.spi.checkpoint.jdbc

## Class JdbcCheckpointSpi

- java.lang.Object
- - org.apache.ignite.spi.IgniteSpiAdapter
  - - org.apache.ignite.spi.checkpoint.jdbc.JdbcCheckpointSpi

- All Implemented Interfaces:
    `CheckpointSpi`, `IgniteSpi`

      @IgniteSpiMultipleInstancesSupport(true)
      public class JdbcCheckpointSpi
      extends IgniteSpiAdapter
      implements CheckpointSpi

  This class defines JDBC checkpoint SPI implementation. All checkpoints are stored in the database table and available from all nodes in the grid. Note that every node must have access to the database. The reason of having it is because a job state can be saved on one node and loaded on another (e.g., if a job gets preempted on a different node after node failure).

  # Configuration

  ## Mandatory

  This SPI has following mandatory configuration parameters.
  - DataSource (see `setDataSource(DataSource)`).

  ## Optional

  This SPI has following optional configuration parameters:
  - Checkpoint table name (see `setCheckpointTableName(String)`).
  - Checkpoint key field name (see `setKeyFieldName(String)`).
  - Checkpoint key field type (see `setKeyFieldType(String)`).
  - Checkpoint value field name (see `setValueFieldName(String)`).
  - Checkpoint value field type (see `setValueFieldType(String)`).
  - Checkpoint expiration date field name (see `setExpireDateFieldName(String)`).
  - Checkpoint expiration date field type (see `setExpireDateFieldType(String)`).
  - Number of retries in case of any failure (see `setNumberOfRetries(int)`).
  - User name (see `setUser(String)`).
  - Password (see `setPwd(String)`).

  ## Apache DBCP

  Apache DBCP project provides various wrappers for data sources and connection pools. You can use these wrappers as Spring beans to configure this SPI from Spring configuration file. Refer to `Apache DBCP` project for more information.

  ## Java Example

  `JdbcCheckpointSpi` can be configured as follows:

       IgniteConfiguration cfg = new IgniteConfiguration();

       GridJdbcCheckpointSpi checkpointSpi = new GridJdbcCheckpointSpi();

       javax.sql.DataSource ds = ... // Set datasource.

       // Set jdbc checkpoint SPI parameters.
       checkpointSpi.setDataSource(ds);
       checkpointSpi.setUser("test");
       checkpointSpi.setPassword("test");

       // Override default checkpoint SPI.
       cfg.setCheckpointSpi(checkpointSpi);

       // Starts grid.
       G.start(cfg);

  ## Spring Example

  `JdbcCheckpointSpi` can be configured from Spring XML configuration file:

       <bean id="grid.custom.cfg" class="org.apache.ignite.configuration.IgniteConfiguration" singleton="true">
           ...
           <property name="checkpointSpi">
               <bean class="org.apache.ignite.spi.checkpoint.jdbc.JdbcCheckpointSpi">
                   <property name="dataSrc"><ref bean="anyPooledDataSourceBean" /></property>
                   <property name="checkpointTableName" value="GRID_CHECKPOINTS" />
                   <property name="user" value="test" />
                   <property name="password" value="test" />
               </bean>
           </property>
           ...
       </bean>

  For information about Spring framework visit www.springframework.org

- - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `static String` | `DFLT_CHECKPOINT_TABLE_NAME` | Default checkpoint table name (value is `CHECKPOINTS`).
    `static String` | `DFLT_EXPIRE_DATE_FIELD_NAME` | Default expiration date field name (value is `EXPIRE_DATE`).
    `static String` | `DFLT_EXPIRE_DATE_FIELD_TYPE` | Default expiration date field type (value is `DATETIME`).
    `static String` | `DFLT_KEY_FIELD_NAME` | Default checkpoint key field name (value is `NAME`).
    `static String` | `DFLT_KEY_FIELD_TYPE` | Default checkpoint key field type (value is `VARCHAR(256)`).
    `static int` | `DFLT_NUMBER_OF_RETRIES` | Default number of retries in case of errors (value is `2`).
    `static String` | `DFLT_VALUE_FIELD_NAME` | Default checkpoint value field name (value is `VALUE`).
    `static String` | `DFLT_VALUE_FIELD_TYPE` | Default checkpoint value field type (value is `BLOB`).

    - ### Fields inherited from class org.apache.ignite.spi.IgniteSpiAdapter

      `ignite, igniteInstanceName`

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `JdbcCheckpointSpi()` |

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `String` | `getCheckpointTableName()` | Gets checkpoint table name.
    `String` | `getDataSourceInfo()` | Gets data source description.
    `String` | `getExpireDateFieldName()` | Gets expiration date field name for checkpoint table.
    `String` | `getExpireDateFieldType()` | Gets expiration date field type for checkpoint table.
    `String` | `getKeyFieldName()` | Gets key field name for checkpoint table.
    `String` | `getKeyFieldType()` | Gets key field type for checkpoint table.
    `int` | `getNumberOfRetries()` | Gets number of retries in case of DB failure.
    `String` | `getPwd()` | Gets checkpoint jdbc password.
    `String` | `getUser()` | Gets checkpoint jdbc user name.
    `String` | `getValueFieldName()` | Gets value field name for checkpoint table.
    `String` | `getValueFieldType()` | Gets value field type for checkpoint table.
    `byte[]` | `loadCheckpoint​(String key)` | Loads checkpoint from storage by its unique key.
    `protected void` | `onContextDestroyed0()` | Method to be called in the beginning of onContextDestroyed() method.
    `boolean` | `removeCheckpoint​(String key)` | This method instructs the checkpoint provider to clean saved data for a given `key`.
    `boolean` | `saveCheckpoint​(String key, byte[] state, long timeout, boolean overwrite)` | Saves checkpoint to the storage.
    `void` | `setCheckpointListener​(CheckpointListener lsnr)` | Sets the checkpoint listener.
    `JdbcCheckpointSpi` | `setCheckpointTableName​(String tblName)` | Sets checkpoint table name.
    `JdbcCheckpointSpi` | `setDataSource​(DataSource dataSrc)` | Sets DataSource to use for database access.
    `JdbcCheckpointSpi` | `setExpireDateFieldName​(String expDateName)` | Sets checkpoint expiration date field name.
    `JdbcCheckpointSpi` | `setExpireDateFieldType​(String expDateType)` | Sets checkpoint expiration date field type.
    `JdbcCheckpointSpi` | `setKeyFieldName​(String keyName)` | Sets checkpoint key field name.
    `JdbcCheckpointSpi` | `setKeyFieldType​(String keyType)` | Sets checkpoint key field type.
    `JdbcCheckpointSpi` | `setName​(String name)` | Sets SPI name.
    `JdbcCheckpointSpi` | `setNumberOfRetries​(int retryNum)` | Sets number of retries in case of any database errors.
    `JdbcCheckpointSpi` | `setPwd​(String pwd)` | Sets checkpoint database password.
    `JdbcCheckpointSpi` | `setUser​(String user)` | Sets checkpoint database user name.
    `JdbcCheckpointSpi` | `setValueFieldName​(String valName)` | Sets checkpoint value field name.
    `JdbcCheckpointSpi` | `setValueFieldType​(String valType)` | Sets checkpoint value field type.
    `void` | `spiStart​(String igniteInstanceName)` | This method is called to start SPI.
    `void` | `spiStop()` | This method is called to stop SPI.

    - ### Methods inherited from class org.apache.ignite.spi.IgniteSpiAdapter

      `addTimeoutObject, assertParameter, checkConfigurationConsistency0, clientFailureDetectionTimeout, configInfo, createSpiAttributeName, failureDetectionTimeout, failureDetectionTimeoutEnabled, failureDetectionTimeoutEnabled, getConsistentAttributeNames, getExceptionRegistry, getLocalNode, getName, getNodeAttributes, getSpiContext, ignite, initFailureDetectionTimeout, injectables, injectResources, isNodeStopping, onBeforeStart, onClientDisconnected, onClientReconnected, onContextDestroyed, onContextInitialized, onContextInitialized0, registerMBean, removeTimeoutObject, started, startInfo, startStopwatch, stopInfo, unregisterMBean`

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

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

    - ### Methods inherited from interface org.apache.ignite.spi.IgniteSpi

      `getName, getNodeAttributes, onClientDisconnected, onClientReconnected, onContextDestroyed, onContextInitialized`

- - ### Field Detail

    - #### DFLT_NUMBER_OF_RETRIES

          public static final int DFLT_NUMBER_OF_RETRIES

      Default number of retries in case of errors (value is `2`).
      See Also:
        Constant Field Values

    - #### DFLT_EXPIRE_DATE_FIELD_TYPE

          public static final String DFLT_EXPIRE_DATE_FIELD_TYPE

      Default expiration date field type (value is `DATETIME`).
      See Also:
        Constant Field Values

    - #### DFLT_EXPIRE_DATE_FIELD_NAME

          public static final String DFLT_EXPIRE_DATE_FIELD_NAME

      Default expiration date field name (value is `EXPIRE_DATE`).
      See Also:
        Constant Field Values

    - #### DFLT_VALUE_FIELD_TYPE

          public static final String DFLT_VALUE_FIELD_TYPE

      Default checkpoint value field type (value is `BLOB`).
      See Also:
        Constant Field Values

    - #### DFLT_VALUE_FIELD_NAME

          public static final String DFLT_VALUE_FIELD_NAME

      Default checkpoint value field name (value is `VALUE`).
      See Also:
        Constant Field Values

    - #### DFLT_KEY_FIELD_TYPE

          public static final String DFLT_KEY_FIELD_TYPE

      Default checkpoint key field type (value is `VARCHAR(256)`).
      See Also:
        Constant Field Values

    - #### DFLT_KEY_FIELD_NAME

          public static final String DFLT_KEY_FIELD_NAME

      Default checkpoint key field name (value is `NAME`).
      See Also:
        Constant Field Values

    - #### DFLT_CHECKPOINT_TABLE_NAME

          public static final String DFLT_CHECKPOINT_TABLE_NAME

      Default checkpoint table name (value is `CHECKPOINTS`).
      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### JdbcCheckpointSpi

          public JdbcCheckpointSpi()

  - ### Method Detail

    - #### getNumberOfRetries

          public int getNumberOfRetries()

      Gets number of retries in case of DB failure.
      Returns:
        Number of retries.

    - #### getDataSourceInfo

          public String getDataSourceInfo()

      Gets data source description.
      Returns:
        Description for data source.

    - #### getUser

          public String getUser()

      Gets checkpoint jdbc user name.
      Returns:
        User name for checkpoint jdbc.

    - #### getPwd

          public String getPwd()

      Gets checkpoint jdbc password.
      Returns:
        Password for checkpoint jdbc.

    - #### getCheckpointTableName

          public String getCheckpointTableName()

      Gets checkpoint table name.
      Returns:
        Checkpoint table name.

    - #### getKeyFieldName

          public String getKeyFieldName()

      Gets key field name for checkpoint table.
      Returns:
        Key field name for checkpoint table.

    - #### getKeyFieldType

          public String getKeyFieldType()

      Gets key field type for checkpoint table.
      Returns:
        Key field type for checkpoint table.

    - #### getValueFieldName

          public String getValueFieldName()

      Gets value field name for checkpoint table.
      Returns:
        Value field name for checkpoint table.

    - #### getValueFieldType

          public String getValueFieldType()

      Gets value field type for checkpoint table.
      Returns:
        Value field type for checkpoint table.

    - #### getExpireDateFieldName

          public String getExpireDateFieldName()

      Gets expiration date field name for checkpoint table.
      Returns:
        Create date field name for checkpoint table.

    - #### getExpireDateFieldType

          public String getExpireDateFieldType()

      Gets expiration date field type for checkpoint table.
      Returns:
        Expiration date field type for checkpoint table.

    - #### setDataSource

          @IgniteSpiConfiguration(optional=false)
          public JdbcCheckpointSpi setDataSource​(DataSource dataSrc)

      Sets DataSource to use for database access. This parameter is mandatory and must be provided for this SPI to be able to start.

      Apache DBCP project provides various wrappers for data sources and connection pools. You can use these wrappers as Spring beans to configure this SPI from Spring configuration file. Refer to `Apache DBCP` project for more information.

      Parameters:
        `dataSrc` - DataSource object to set.
      Returns:
        `this` for chaining.

    - #### setNumberOfRetries

          @IgniteSpiConfiguration(optional=true)
          public JdbcCheckpointSpi setNumberOfRetries​(int retryNum)

      Sets number of retries in case of any database errors. By default the value is `DFLT_NUMBER_OF_RETRIES`.
      Parameters:
        `retryNum` - Number of retries in case of any database errors.
      Returns:
        `this` for chaining.

    - #### setUser

          @IgniteSpiConfiguration(optional=true)
          public JdbcCheckpointSpi setUser​(String user)

      Sets checkpoint database user name. Note that authentication will be performed only if both, `user` and `password` are set.
      Parameters:
        `user` - Checkpoint database user name to set. `null` is a valid value that means that no user provided. Authentication won't be performed in this case.
      Returns:
        `this` for chaining.
      See Also:
        `setPwd(String)`

    - #### setPwd

          @IgniteSpiConfiguration(optional=true)
          public JdbcCheckpointSpi setPwd​(String pwd)

      Sets checkpoint database password. Note that authentication will be performed only if both, `user` and `password` are set.
      Parameters:
        `pwd` - Checkpoint database password to set. `null` is a valid value that means that no password provided. Authentication won't be performed in this case.
      Returns:
        `this` for chaining.
      See Also:
        `setUser(String)`

    - #### setCheckpointTableName

          @IgniteSpiConfiguration(optional=true)
          public JdbcCheckpointSpi setCheckpointTableName​(String tblName)

      Sets checkpoint table name. By default `DFLT_CHECKPOINT_TABLE_NAME` is used.
      Parameters:
        `tblName` - Checkpoint table name to set.
      Returns:
        `this` for chaining.

    - #### setKeyFieldName

          @IgniteSpiConfiguration(optional=true)
          public JdbcCheckpointSpi setKeyFieldName​(String keyName)

      Sets checkpoint key field name. By default, `DFLT_KEY_FIELD_NAME` is used. Note that you may also want to change key field type (see `setKeyFieldType(String)`).
      Parameters:
        `keyName` - Checkpoint key field name to set.
      Returns:
        `this` for chaining.

    - #### setKeyFieldType

          @IgniteSpiConfiguration(optional=true)
          public JdbcCheckpointSpi setKeyFieldType​(String keyType)

      Sets checkpoint key field type. The field should have corresponding SQL string type (`VARCHAR`, for example). By default `DFLT_EXPIRE_DATE_FIELD_TYPE` is used.
      Parameters:
        `keyType` - Checkpoint key field type to set.
      Returns:
        `this` for chaining.

    - #### setValueFieldName

          @IgniteSpiConfiguration(optional=true)
          public JdbcCheckpointSpi setValueFieldName​(String valName)

      Sets checkpoint value field name. By default `DFLT_VALUE_FIELD_NAME` is used. Note that you may also want to change the value type (see `setValueFieldType(String)`).
      Parameters:
        `valName` - Checkpoint value field name to set.
      Returns:
        `this` for chaining.

    - #### setValueFieldType

          @IgniteSpiConfiguration(optional=true)
          public JdbcCheckpointSpi setValueFieldType​(String valType)

      Sets checkpoint value field type. Note, that the field should have corresponding SQL `BLOB` type, and the default value of `DFLT_VALUE_FIELD_TYPE`, which is `BLOB`, won't work for all databases. For example, if using `HSQL DB`, then the type should be `longvarbinary`.
      Parameters:
        `valType` - Checkpoint value field type to set.
      Returns:
        `this` for chaining.

    - #### setExpireDateFieldName

          @IgniteSpiConfiguration(optional=true)
          public JdbcCheckpointSpi setExpireDateFieldName​(String expDateName)

      Sets checkpoint expiration date field name. By default `DFLT_EXPIRE_DATE_FIELD_NAME` is used. Note that you may also want to change the expiration date field type (see `setExpireDateFieldType(String)`).
      Parameters:
        `expDateName` - Checkpoint expiration date field name to set.
      Returns:
        `this` for chaining.

    - #### setExpireDateFieldType

          @IgniteSpiConfiguration(optional=true)
          public JdbcCheckpointSpi setExpireDateFieldType​(String expDateType)

      Sets checkpoint expiration date field type. By default `DFLT_EXPIRE_DATE_FIELD_TYPE` is used. The field should have corresponding SQL `DATETIME` type.
      Parameters:
        `expDateType` - Checkpoint expiration date field type to set.
      Returns:
        `this` for chaining.

    - #### spiStart

          public void spiStart​(String igniteInstanceName)
                        throws IgniteSpiException

      This method is called to start SPI. After this method returns successfully kernel assumes that SPI is fully operational.
      Specified by:
        `spiStart` in interface `IgniteSpi`
      Parameters:
        `igniteInstanceName` - Name of Ignite instance this SPI is being started for (`null` for default Ignite instance).
      Throws:
        `IgniteSpiException` - Throws in case of any error during SPI start.

    - #### spiStop

          public void spiStop()
                       throws IgniteSpiException

      This method is called to stop SPI. After this method returns kernel assumes that this SPI is finished and all resources acquired by it are released.

      Note that this method can be called at any point including during recovery of failed start. It should make no assumptions on what state SPI will be in when this method is called.

      Specified by:
        `spiStop` in interface `IgniteSpi`
      Throws:
        `IgniteSpiException` - Thrown in case of any error during SPI stop.

    - #### onContextDestroyed0

          protected void onContextDestroyed0()

      Method to be called in the beginning of onContextDestroyed() method.
      Overrides:
        `onContextDestroyed0` in class `IgniteSpiAdapter`

    - #### loadCheckpoint

          public byte[] loadCheckpoint​(String key)
                                throws IgniteSpiException

      Loads checkpoint from storage by its unique key.
      Specified by:
        `loadCheckpoint` in interface `CheckpointSpi`
      Parameters:
        `key` - Checkpoint key.
      Returns:
        Loaded data or `null` if there is no data for a given key.
      Throws:
        `IgniteSpiException` - Thrown in case of any error while loading checkpoint data. Note that in case when given `key` is not found this method will return `null`.

    - #### removeCheckpoint

          public boolean removeCheckpoint​(String key)

      This method instructs the checkpoint provider to clean saved data for a given `key`.
      Specified by:
        `removeCheckpoint` in interface `CheckpointSpi`
      Parameters:
        `key` - Key for the checkpoint to remove.
      Returns:
        `true` if data has been actually removed, `false` otherwise.

    - #### saveCheckpoint

          public boolean saveCheckpoint​(String key,
                                        byte[] state,
                                        long timeout,
                                        boolean overwrite)
                                 throws IgniteSpiException

      Saves checkpoint to the storage.
      Specified by:
        `saveCheckpoint` in interface `CheckpointSpi`
      Parameters:
        `key` - Checkpoint unique key.
        `state` - Saved data.
        `timeout` - Every intermediate data stored by checkpoint provider should have a timeout. Timeout allows for effective resource management by checkpoint provider by cleaning saved data that are not needed anymore. Generally, the user should choose the minimum possible timeout to avoid long-term resource acquisition by checkpoint provider. Value `0` means that timeout will never expire.
        `overwrite` - Whether or not overwrite checkpoint if it already exists.
      Returns:
        `true` if checkpoint has been actually saved, `false` otherwise.
      Throws:
        `IgniteSpiException` - Thrown in case of any error while saving checkpoint data.

    - #### setCheckpointListener

          public void setCheckpointListener​(CheckpointListener lsnr)

      Sets the checkpoint listener.
      Specified by:
        `setCheckpointListener` in interface `CheckpointSpi`
      Parameters:
        `lsnr` - The listener to set or `null`.

    - #### setName

          public JdbcCheckpointSpi setName​(String name)

      Sets SPI name.
      Overrides:
        `setName` in class `IgniteSpiAdapter`
      Parameters:
        `name` - SPI name.
      Returns:
        `this` for chaining.