Caching Message Data in a Custom Module
You can use the message cache to store the message data that a module produces into a separate cache. This data is typically the output message that the next module in the cache might access. You can then access this cached message data from any other module in the route, not just the next module in the route.
The message cache uses the built-in akcache module. You use methods on the AKExchange class to add, remove, and replace messages in the message cache. You can also add and remove messages from the cache by configuring the akcache module in the route configuration file. For more information on the akcache module, see Cache Module.
The following image shows that as each module traverses the route, it can write to or read from the message cache:
When using the message cache, you can:
- Store a message in the cache
- Access data from the cache in the same or a different module
- Get a module's output message from the cache
- Delete a single message from the cache
- Delete all messages from the cache (clearing the entire cache)
You only use the message cache while the data is traversing the route on the Akula Server. After the route is complete and the server sends the last message back to the client, the message cache is deleted.
You use the message cache when you have more than one module in a route. Each module can save their output message in the message cache and also access previously-saved messages. For information about using multiple custom modules in a route, see Using Multiple Modules.
The Akula Server also provides a data cache that lets a module cache any object that implements the java.io.Serializable interface. The data cache can then be accessed by any other module in the app scope. Objects in the data cache persist across requests. You use the Akula Server Java API to access the data cache from within a module. For more information, see Caching Data Objects in a Custom Module.
This section describes the following topics:
Storing messages in the message cache
Each module can store its output message prior to completing its processing, so that modules that are invoked later in the route can access it.
Output messages are not cached by default. You must explicitly store the message in the cache for later use. You must do this before the module finishes processing by adding calls to the AKExchange object in a custom module. You can also store messages in a cache without writing a custom module. You do this by adding the akcache module to a route configuration file.
Storing cached messages in a custom module
To store the current output message in the cache, use the AKExchange object's
addMessageToCache() method. This method takes a key (or name) for that message, and the message body that you want to add to the cache, as the following example shows:
In a subsequent module (or later in the same module), you can access the same output message by the name that you specified in the
If you add a message to the cache with the same name as a previous message to the message cache, Akula overwrites the existing message body. As a result, you should try to give your message a unique name. One technique is to include the unique name of the module in the name of the key.
Storing cached messages in a route configuration file
You can cache a module's output message in the message cache by adding the akcache module in your route. You add the akcache module in the route directly after the module whose output you want to cache. You set the akcache module's directive to
AddMessageToCache and you pass the name of the cache as the
cacheKey route parameter. The syntax for this is as follows:
The following example route configuration file shows two data connector modules (akhttp) whose output messages are cached. The third module (not shown) would include methods to get the data from the cache and combine them:
Accessing data in the message cache
You can access cached messages at any time from any custom module in your route.
Accessing a cached message by name
To access a cached message by name, use the
getMessageFromCache() method. This method takes a String that specifies the name of the message in the cache, as the following example shows:
In this example, it is assumed that you have previously stored message data with the name of the key set to "module1CacheData".
Accessing all cache bodies
You can use the AKExchange class's
getMessageCacheKeySet() method to get a Set of keys that reference the available messages in the message cache.
The following example consolidates the bodies of all cached messages by first accessing the
Set<String> of keys, and then calling the
getMessageFromCache() method for each of those keys:
You can also use the AKExchange class's
getMessageCacheEntrySet() method to get a
Set<String, AKMessage> of entries which you can then iterate over.
Combining data from multiple modules
The message cache lets you combine the data from multiple modules into a single output message.
The following example gets the cached messages from two modules and concatenates it in the message body:
The following custom module example is more complex. It uses XPath to extract just a portion of each of the cached messages and combines the results into XML output:
Clearing the message cache
You can clear a single entry in the message cache or all entries in the message cache.
To clear a single entry in the message cache, use the
removeMessageFromCache() method and pass it the key of the cached message that you want to remove, as the following example shows:
To clear all entries in the message cache in a custom module, use the AKExchange class's
clearMessageCache() method, as the following example shows: