To use the renewable cache, you will need JBoss AS 4.0.x and JBoss Cache 1.4.x.

To install the cache, download and unpack the distribution. There you will find the following files and directories:

  • shotoku-cache.jar - base classes; you should copy this to ${JBOSS_HOME}/server/default/lib (or to a lib directory of any other configuration that you are using). Use this as a dependency jar when developing your cache items.
  • shotoku-cache-service.sar - service which manages the updates and update threads; copy it to ${JBOSS_HOME}/server/default/deploy
  • shotoku-cache-admin.war - administration panel, optional; copy it to ${JBOSS_HOME}/server/default/deploy

When you copy these to the proper destinations, you are almost ready to go. You can define initial configuration of the services in the file shotoku-cache-service.sar/META-INF/jboss-service.xml. There you will find the following mbeans:

  • shotoku:service=RenewableCache - the main mbean, which manages updates and update threads. Attributes:
    • Interval - interval between updates of values managed by active cache items (however cache items may define longer update intervals)
    • UpdateThreadCount - initial number of update threads that will be performing the updates (if there are many cache items, or many keys, you will need more then one update thread, to make the updates efficiently)
    • TreeCache - a tree cache mbean, where values will be held.
  • shotoku:service=RenewableCacheMonitor - a service which monitors the cache items, and when it detects that a key wasn't updated for a long time/ is in update for a long time/ an exception was thrown during a key update, issues an alert, which is visible in the administration console, and can also be sent by e-mail. Attributes:
    • AlertEmail, Smtp* - configuration for sending alert e-mails. If you don't want alert e-mails to be sent, set the user to an empty string.
    • Interval - how often cache items will be monitored.
    • MaximumNumberOfAlerts - maximum number of alerts stored. If the number of alerts exceeds this number, any new ones won't be saved.
    • UpdateAlertIntervalMultiplier - how many times must the interval of a cache item be exceeded, before a "key not updated" or a "key too long in update" alert is issued.
    If you want to disable monitoring completely, simply comment out the mbean definition.

You can change most of these configuration options at run-time, through the administration panel, which, after AS startup, is normally available at http://localhost:8080/shotoku-cache-admin.