Administration guide > Configure the deployment environment > Configuring data grids > Configuring write-behind loader support



Handle failed write-behind updates

Since the WebSphere eXtreme Scale transaction finishes before the back-end transaction starts, it is possible to have transaction false success.

For example, if you try to insert an entry in an eXtreme Scale transaction which does not exist in the backing map but does exist in the back-end, causing a duplicate key, the eXtreme Scale transaction does succeed. However, the transaction in which the write-behind thread inserts that object into the back-end fails with a duplicate key exception.


Handle failed write-behind updates: client side

Such an update, or any other failed back-end update, is a failed write-behind update. Failed write-behind updates are stored in a failed write-behind update map. This map serves as an event queue for failed updates. The key of the update is a unique Integer object, and the value is an instance of FailedUpdateElement. The failed write-behind update map is configured with an evictor, which evicts the records 1 hour after it has been inserted. So the failed-update records will be lost if they are not retrieved within 1 hour.

The ObjectMap API can be used to retrieve the failed write-behind update map entries. The failed write-behind update map name is: IBM_WB_FAILED_UPDATES_<map name>. See the WriteBehindLoaderConstants API documentation for the prefix names of each of the write-behind system maps. The following is an example.

process failed - example code
ObjectMap failedMap = session.getMap(
    WriteBehindLoaderConstants.WRITE_BEHIND_FAILED_UPDATES_MAP_PREFIX + "Employee");
Object key = null;

session.begin();
while(key = failedMap.getNextKey(ObjectMap.QUEUE_TIMEOUT_NONE)) {
    FailedUpdateElement element = (FailedUpdateElement) failedMap.get(key);
    Throwable throwable = element.getThrowable();
    Object failedKey = element.getKey();
    Object failedValue = element.getAfterImage();
    failedMap.remove(key);
    // Do something interesting with the key, value, or exception.

}
session.commit();

A getNextKey call works with a specific partition for each eXtreme Scale transaction. In a distributed environment, in order to get keys from all partitions, start multiple transactions, as shown in the following example:

getting keys from all partitions - example code
ObjectMap failedMap = session.getMap(
    WriteBehindLoaderConstants.WRITE_BEHIND_FAILED_UPDATES_MAP_PREFIX + "Employee");
while (true) {
    session.begin();
    Object key = null; 
    while(( key = failedMap.getNextKey(5000) )!= null ) {
        FailedUpdateElement element = (FailedUpdateElement) failedMap.get(key);
    Throwable throwable = element.getThrowable();
        Object failedKey = element.getKey();
        Object failedValue = element.getAfterImage();
        failedMap.remove(key);
        // Do something interesting with the key, value, or exception.

    }
    Session.commit();
}

Failed update map provides a way to monitor the application health. If a system produces a lot of records in the failed update map, it is a sign the application or architecture should be re-evaluated or revised to use the write-behind support. Starting from 6.1.0.5, you can use xsadmin script to see the failed update map entry size.


Handle failed write-behind updates: shard listener

It is important to detect and log when a write-behind transaction fails. Every application using write-behind needs to implement a watcher to handle failed write-behind updates. This avoids potentially running out of memory as records in the bad update Map are not evicted because the application is expected to handle them.

The following code shows how to plug in such a watcher, or "dumper," which should be added to the ObjectGrid descriptor XML as in the snippet.

    <objectGrid name="Grid">
        <bean id="ObjectGridEventListener" className="utils.WriteBehindDumper"/>

You can see the ObjectGridEventListener bean that has been added, which is the write-behind watcher referred to above. The watcher interacts over the Maps for all primary shards in a JVM looking for ones with write-behind enabled. If it finds one then it tries to log up to 100 bad updates. It keeps watching a primary shard until the shard is moved to a different JVM. All applications using write-behind must use a watcher similar to this one. Otherwise, the Java™ virtual machines run out of memory because this error map is never evicted

See Write-behind dumper class sample code for more information.


Parent topic:

Configure write-behind loader support


Related concepts

Write-behind caching

Write-behind caching support

Related reference

Example: Writing a write-behind dumper class