Page: Caching Data Objects in a Custom Module
Page: Cache Module
Page: Using Multiple Modules
Page: Caching Message Data in a Custom Module
Page: Getting Binary Data with the SQL Module
Page: HTTP Module
Page: Convert Module
Page: Working With the Request
Page: Getting HTTP Query String Parameters
Page: Getting Request Path Parameters
Page: Getting HTTP Headers
Caching Data Objects in a Custom Module
The object caching service on the Akula Server lets you write and read Serializable objects to a server-side cache. All objects written to the cache must implement the java.io.Serializable interface. All core Java data types, such as String, Boolean, and Date already implement java.io.Serializable. You can also write any of your own objects to the cache as long as they implement java.io.Serializable.
This document contains the following sections:
About the object cache
The object cache on the Akula Server:
- Lets one module write a value to the cache that can be read by the same module or by a different module in the same app scope. The modules can be in the same route or in different routes but must be in the same app scope.
- Is persistent across multiple requests to the same app scope. That means a module can cache data during one request, and then read that data back later during a different request.
- Lets the module cache data that can be accessed during a request from any user, or cache data that can only be accessed during a request from a specific user.
Represents each cached object by the object's value and the object's key, which is a unique identifier for each object in the cache. Two objects in the cache cannot have the same key value.
In addition to the object caching service, the Akula Server also provides the Cache module that lets a module cache message data during a request. That message data can then be accessed by any other module. However, cached message data is only available during the lifetime of the request. At the end of the request, the message cache is cleared. For more information, see Cache Module.
Using the object cache
Using the object cache is a two-step process:
- Configure one or more cache managers for the app scope in the app_root/AKZ-INF/config/scope/cache-template.xml file.
Each cache manager is defined by its name, or key, and an implementation class. The implementation class references a cache provider, which implements the AKCacheProvider interface and defines the characteristics of the cache itself. A cache manager implementation can be associated with a single cache provider, or multiple cache providers.
You can define multiple cache managers. Each cache manager can use the same class with different settings such as cache size, cache timeout, or other settings. Or, each cache manger can use a different class.
- Use the Akula Server Java API in a custom module to write and read objects in the cache.
In your custom module, use the AKCacheService class to obtain a reference to a cache manager defined in the cache-template.xml file. The
AKCacheService.getCacheManager()method returns an AKCacheManager object. Use methods of the AKCacheManager object to write and read the cache.
Configuring a cache manager
Configure cache managers for an app scope in the app_root/AKZ-INF/config/scope/cache-template.xml, as shown below:
<cache-manager> tag has two required attributes:
key: Specifies the name of the cache manager. Use this value to reference the cache manager from your module.
class: Specifies implementation class for the cache manager. In this example, the cache manager uses the com.verivo.akula.cache.manager.AKLocalCacheManager and com.verivo.akula.security.cache.memcached.MemcachedCacheManager classes that ship with the Akula Server. Alternatively, you can define your own cache manager by creating a class that implements the com.verivo.akula.api.cache.manager.AKCustomCacheManager interface.
<property> child tags specify the settings of the cache manager. The value of the
key attribute of the
<property> tag corresponds to the name of a property of the cache manager class. If you define your own custom cache manager, you can use the
<property> tag to set its properties.
After editing the cache-template.xml file, package the AKZ file corresponding to the app scope and deploy it on the Akula Server.
Using the cache manger classes supplied with Akula
Akula ships with two predefined cache manager classes:
This section describes both.
The Akula Server ships with the com.verivo.akula.cache.manager.AKLocalCacheManager class that implements an in-memory cache manager.
AKLocalCacheManager is not distributed as part of the Akula Server Java API, but is local to the instance of the server. Therefore, it does not appear in the Akula Server Java API Reference.
The AKLocalCacheManager class lets you set the following properties of the cache:
Determines which elements to remove when the cache size limit is reached, as determined by
Specifies the maximum size of the cache, in bytes. If a cache write causes the cache to exceed the maximum number of bytes, then entries in the cache are automatically removed based on the
The default value is 0 corresponding to no limit.
Specifies the duration, in seconds, of a cache entry before it is automatically removed from the cache.
The default value is 0 corresponding to no limit.
Specifies the duration, in seconds, in which a cached object must be accessed before it is automatically removed from the cache.
The default value is 0 corresponding to no limit.
Memcached is a caching system for objects that runs independently of the Akula Server. By externalizing session caching, you take some load off the Akula Server. Memcached runs on Unix, Linux, Windows, and Mac OS X. The servers running Memcached do not need to be the same platform as the server running Akula. Akula supports Memcached version 1.4.13 or later.
Memcached is not persistent, which means that if the Memcached service restarts, the session data is lost.
The Akula Server ships with the com.verivo.akula.security.cache.memcached.MemcachedCacheManager class that implements support for distributed caching with the Memcached utility.
MemcachedCacheManager is not distributed as part of the Akula Server Java API, but is local to the instance of the server. Therefore, it does not appear in the Akula Server Java API Reference.
The MemcachedCacheManager class lets you set the following properties of the cache:
Specifies the locations of the servers running Memcached.
|Specifies a unique name used by the caching server.|
To use Memcached:
- Install Memcached on your caching server.
- Configure the service to accept connections from remote hosts. For information about configuring Memcached, see Configuring Memcached.
- Start the Memcached service.
To test that Memcached is available and can be reached from a remote host, you can use telnet. For example:
Access the object cache from a custom module
From within a custom module, use the following classes to access the object cache:
- AKCacheService - Use this class to obtain a reference to a cache manager defined in the cache-template.xml file.
- AKCacheManager - Use this class to write and read the object cache.
The AKCacheManager class defines three types of methods that you use to access the object cache. All the methods of the AKCacheManager class require you to pass a key value as a method argument to identify a cached object:
Write an object to the cache. This object must implement the java.io.Serializable interface.
A module can write objects to the cache that can be read back during a request from any user. These cached objects are called scope-level objects.
Or, a module can write objects specific to the user who made the request to the app scope. These objects can only be read from the cache during a request from the same user who wrote them. These cached objects are called user-level objects.
When calling a put method to write data for the current user, the method automatically determines the currently logged in user that made the request to the app scope. Therefore, you do not have to pass any user information to the put method. However, the request must be from a user who has already logged in. Otherwise, the app scope has no way of determining the user's identity.
Read data from the cache.
A module can read an object for the specific user who made the request or for the scope handling the request.
Delete data from the cache.
A module can remove an object for the specific user who made the request or for the scope handling the request.
Writing and reading data cache data
The following example uses the
putScope() method to write data to the cache at the app-scope level. That means any module in the app scope can access the data regardless of the user making the request:
Another module in the app scope can read the data by using the following code and then write the value to its output message:
Because the get methods of the AKCacheManager class all return an object of type Serializable, cast the returned value to the appropriate data type.
If a module attempts to read a value from the cache by using a get method before you have written the object to the cache, then the get method returns null.
putUser() method to write data to the cache that is specific to the user making the request. For example:
You can only call
A module can read back that data during the same request, or on a later request made by the same user:
Passing options to the put methods
The put methods take an optional
options argument passed as a
Map<String, Object> object. You can use the
options argument to pass information to the cache manager for a specific cache write.
The information that you can pass in the
options argument is based on your cache manager. For example, for the built-in AKLocalCacheManager class, you can pass three values in the
options argument that override the corresponding settings of the AKLocalCacheManager set in the cache-template.xml file:
trueto make the object remain in the cache until it is explicitly removed.
timeToLive– The number of seconds for this object to remain in the cache before it is deleted.
timeToIdle– The number of seconds during which the cached object must be accessed before it is automatically removed from the cache.
The following example sets the
timeToLive option for AKLocalCacheManager:
If you define your own custom cache manager, then you can define the values supported by the
Clearing the cache
Use the AKCacheManager's
clear() method to clear the cache. This method removes all objects from the cache, including all scope and user objects.
Alternatively, you can use the AKCacheManager remove methods,
removeUser(), to remove individual objects from the cache.
Writing a custom cache manager and cache provider
The Akula Server ships with the com.verivo.akula.cache.manager.AKLocalCacheManager class that defines an in-memory object cache. However, you might want to implement your own cache manager and cache provider for use on the Akula Server:
A custom cache manager implements the AKCustomCacheManager interface. You associate your custom cache manager with one or more cache providers, where the cache provider defines the actual storage mechanism of the cache.
AKCustomCacheManager defines the
getPartition()method that you use to return the cache provider to the cache manager. The Akula Server calls the
getPartition()method every time it accesses the cache for a read, write, or remove operation. The
getPartition()method takes a single argument to identify a cache partition. Your cache manager implementation can return the same cache provider for every partition, return a different cache provider for each partition, or some other combination.
- A custom cache provider implements the AKCacheProvider interface. That interface defines the set of methods that your custom cache provider must implement to work with the Akula Server.
Referencing your custom cache manager in the cache-template.xml file
The cache-template.xml file defines the cache managers available to an app scope, where each cache manager specifies its implementation class. For example, you define a class named my.company.com.MyCustomCacheManager that implements the AKCustomCacheManager interface. You can then define a cache manager that uses your class in the cache-template.xml file:
In this example, the
<cache-manager> tag specifies the class defining the cache manager.
Accessing information in the cache-template.xml file
In the example above where you add your custom cache manager to the cache-template.xml file, the
< tag only specified the name of your class. Therefore, all configuration information about the cache manager must be hard coded in the class. The downside of this implementation is that your custom class is not reusable across different configurations.
To make your custom class more flexible, your custom class can read configuration information from the cache-template.xml file at run time. This configuration information can be any type of information required by your class, such as cache size, timeout duration, or any other information required to control the cache.
The following example adds
<property> tags to the
< tag for your custom class:
To pass the value from the cache-template file to your class, the Akula Server automatically calls a setter method in my.company.com.MyCustomCacheManager for every
<property> tag in cache-template.xml. The setter method has the form:
where Keyname is the name of the
key attribute with an initial capital letter. In your custom class, you specify the data type of the argument to the setter to match the value of the key. For example, for the following
You define the following setter method in your class that is called automatically by the Akula Server:
cacheType key, the data type of the object is String. Therefore, your custom class would define a setter in the form:
Example cache manager and cache provider implementation
Akula ships with the com.verivo.akula.cache.manager.AKLocalCacheManager class that defines a cache manager, and the com.verivo.akula.cache.provider.AKLocalCacheProvider class that implements the cache provider. To help you implement your own custom custom cache manager and cache provider, Akula ships the source code for these classes that you can download from the following links: