The renewable cache is designed to fit one use case: when you need to store some data in a cache, and update it periodically in the background. For example, imagine you have a large configuration file, which determines the layout of your web page. You have to:

• on every web page request, read the parsed configuration data, and
• from time to time, update the configuration data, basing on persistent store (filesystem, database, etc ...).

Of course, making the updates a blocking operation on a web page request isn't acceptable. That is where you can use Shotoku Renewable Cache, which will update the values held in cache in the background, on regular intervals of time.

As the backing cache, a JBoss Cache tree cache is used (any configured by the user). The renewable cache operates on units called "cache items". Each cache item is bound with one FQN in the associated tree cache. A cache item then creates and stores objects in tree cache keys (attributes).

To create a cache item, you have to implement an interface CacheItemDataSource, which has two functions:

• init(key) - this is called when a value for a key is requested for the first time. The task of this function is to return an initial value. It is the only blocking operation.
• update(key, currentValue) - this is called when a key is updated. The current value is supplied, and the function may return either a new value, or keep the old value in the cache. This operation is performed by a daemon thread, on specified intervals of time.

Then you just need to register you cache item datasource, and you can read data from it, using a simple get(key) function. To see an example of a cache item and it's usage, click here.

Shotoku Renewable Cache also comes with an administration panel, which lets you change the configuration (for example update intervals) and monitor the state of the updates (when keys where last updated). Thanks to Ajax4JSF, you don't have to refresh the panel to check if anything has changed: all important parts are refreshed automatically.

Also, in the administration console you can see alerts when:

• a key isn't updated for too long
• a key is in update for too long (if this is the case, you can reset the key's update status, so that the service tries to update it again)
• an exception occurred during a key update (the exception will also be logged in the AS log, but only once, and if subsequent updates throw exceptions again, they will be suppressed, until the original alert is "cleared" in the administration console. This way your log will stay relatively clean.)

For all of these alerts, you can configure e-mail notifications. For example, if you get an alert that a key is not updated for too long, it may mean that the interval of updates is too short, that there are not enough update threads or, if the data is read from a remote host, that the host is down.

Check also:

• Example of usage
• Installation and configuration
• Javadocs
• Downloads

Shotoku Renewable Cache works with JBoss AS 4.0.x and JBoss Cache 1.4.x.

Here's how the administration panel looks: