16.2.3. Configure the Cache Loader Programmatically

Procedure 16.2. Configure the Cache Loader Programatically

1. Create a New Configuration Builder

   Use the ConfigurationBuilder to create a new configuration object.

   ConfigurationBuilder builder = new ConfigurationBuilder();
   builder.persistence()
   

2. Set Passivation

   passivation affects the way Red Hat JBoss Data Grid interacts with loaders. Passivation removes an object from in-memory cache and writes it to a secondary data loader, such as a system or database. Passivation is false by default.

   ConfigurationBuilder builder = new ConfigurationBuilder();
   builder.persistence()
       .passivation(false)
   

3. Set Up Sharing

   shared indicates that the cache loader is shared by different cache instances. For example, where all instances in a cluster use the same JDBC settings to talk to the same remote, shared database. shared is false by default. When set to true, it prevents duplicate data being written to the cache loader by different cache instances.

   ConfigurationBuilder builder = new ConfigurationBuilder();
   builder.persistence()
       .passivation(false)
       .shared(false)
   

4. Set Up Preloading

   preload is set to false by default. When set to true the data stored in the cache loader is preloaded into the memory when the cache starts. This allows data in the cache loader to be available immediately after startup and avoids cache operations delays as a result of loading data lazily. Preloaded data is only stored locally on the node, and there is no replication or distribution of the preloaded data. JBoss Data Grid will only preload up to the maximum configured number of entries in eviction.

   ConfigurationBuilder builder = new ConfigurationBuilder();
   builder.persistence()
       .passivation(false)
       .shared(false)
       .preload(true)
   

5. Configure the Cache Loader

   addSingleFileStore() adds the SingleFileStore as the cache loader for this configuration. It is possible to create other stores, such as a JDBC Cache Store, which can be added using the addLoader method.

   ConfigurationBuilder builder = new ConfigurationBuilder();
   builder.persistence()
       .passivation(false)
       .shared(false)
       .preload(true)
       .addSingleFileStore()
   

6. Set Up Persistence

   fetchPersistentState determines whether or not to fetch the persistent state of a cache and apply it to the local cache loader when joining the cluster. If the cache loader is shared the fetch persistent state is ignored, as caches access the same cache loader. A configuration exception will be thrown when starting the cache service if more than one cache loader has this property set to true. The fetchPersistentState property is false by default.

   ConfigurationBuilder builder = new ConfigurationBuilder();
   builder.persistence()
       .passivation(false)
       .shared(false)
       .preload(true)
       .addSingleFileStore()
           .fetchPersistentState(true)
   

7. Set Up Purging

   purgeSynchronously controls whether expiration occurs in the eviction thread. When set to true, the eviction thread will block until the purge is finished, rather than bring returned immediately. The purgeSychronously property is set to false by default. If the cache loader supports multi-thread purge, purgeThreads are used to purge expired entries. purgeThreads is set to 1 by default. Check cache loader configuration to determine if multi-thread purge is supported.

   ConfigurationBuilder builder = new ConfigurationBuilder();
   builder.persistence()
       .passivation(false)
       .shared(false)
       .preload(true)
       .addSingleFileStore()
           .fetchPersistentState(true)
           .purgerThreads(3)
           .purgeSynchronously(true)
   

8. Set Modifications

   ignoreModifications determines whether write methods are pushed to the specific cache loader by allowing write operations to the local file cache loader, but not the shared cache loader. In some cases, transient application data should only reside in a file-based cache loader on the same server as the in-memory cache. For example, this would apply with a further JDBC based cache loader used by all servers in the network. ignoreModifications is false by default.

   ConfigurationBuilder builder = new ConfigurationBuilder();
   builder.persistence()
       .passivation(false)
       .shared(false)
       .preload(true)
       .addSingleFileStore()
           .fetchPersistentState(true)
           .purgerThreads(3)
           .purgeSynchronously(true)
           .ignoreModifications(false)
   

9. Asynchronous Settings

   These attributes configure aspects specific to each cache loader. For example, the location attribute points to where the SingleFileStore will keep files containing data. Other loaders may require more complex configuration.

   ConfigurationBuilder builder = new ConfigurationBuilder();
   builder.persistence()
       .passivation(false)
       .shared(false)
       .preload(true)
       .addSingleFileStore()
           .fetchPersistentState(true)
           .purgerThreads(3)
           .purgeSynchronously(true)
           .ignoreModifications(false)
           .purgeOnStartup(false)
           .location(System.getProperty("java.io.tmpdir"))
           .async()
               .enabled(true)
               .flushLockTimeout(15000)
               .threadPoolSize(5)
   

10. Configure Singletons

    singletonStore enables modifications to be stored by only one node in the cluster. This node is called the coordinator. The coordinator pushes the caches in-memory states to disk. This function is activated by setting the enabled attribute to true in all nodes. The shared parameter cannot be defined with singletonStore enabled at the same time. The enabled attribute is false by default.

    ConfigurationBuilder builder = new ConfigurationBuilder();
    builder.persistence()
        .passivation(false)
        .shared(false)
        .preload(true)
        .addSingleFileStore()
            .fetchPersistentState(true)
            .purgerThreads(3)
            .purgeSynchronously(true)
            .ignoreModifications(false)
            .purgeOnStartup(false)
            .location(System.getProperty("java.io.tmpdir"))
            .async()
                .enabled(true)
                .flushLockTimeout(15000)
                .threadPoolSize(5)
            .singletonStore()
               .enabled(true)
    

11. Set Up Push States

    pushStateWhenCoordinator is set to true by default. If true, this property will cause a node that has become the coordinator to transfer in-memory state to the underlying cache loader. This parameter is useful where the coordinator has crashed and a new coordinator is elected.

    ConfigurationBuilder builder = new ConfigurationBuilder();
    builder.persistence()
        .passivation(false)
        .shared(false)
        .preload(true)
        .addSingleFileStore()
            .fetchPersistentState(true)
            .purgerThreads(3)
            .purgeSynchronously(true)
            .ignoreModifications(false)
            .purgeOnStartup(false)
            .location(System.getProperty("java.io.tmpdir"))
            .async()
                .enabled(true)
                .flushLockTimeout(15000)
                .threadPoolSize(5)
            .singletonStore()
               .enabled(true)
               .pushStateWhenCoordinator(true)
               .pushStateTimeout(20000);