Use this task to define cacheable objects inside the cachespec.xml
,
found inside the web module WEB-INF
or enterprise bean META-INF
directory.
Before you begin
Enable the dynamic cache. Refer to the Using the dynamic cache service article for more
information.
About this task
You can save a global cachespec.xml
in the application server properties
directory, but the recommended method is to place the cache configuration file with the deployment
module. The root element of the cachespec.xml
file is <cache>, which contains
<cache-entry> elements.
Avoid trouble: In situations where there is a global
cachespec.xml
file in the application server properties directory, and a
cachespec.xml
file in an application, the entries in the two cachespec.xml files
are merged. If there are conflicting entries in the two files, the entries in the in the
cachespec.xml
file that is in the application override the entries in the global
cachespec.xml
file for that application.
The <cache-entry> element can be nested within the <cache> element or a
<cache-instance> element. The <cache-entry> elements that are nested within the
<cache> element are cached in the default cache instance. Any <cache-entry> elements
that are in the <cache-instance> element are cached in the instance that is specified in the
name attribute on the <cache-instance> element.
Within a <cache-entry> element are parameters that allow you to complete the following
tasks to enable the dynamic cache with the cachespec.xml
file:
Procedure
-
Develop a
cachespec.xml
file.
-
Create a caching configuration file.
In the <app_server_root>/properties
directory, locate
the cachespec.sample.xml
file.
-
Copy the
cachespec.sample.xml
file to cachespec.xml
in web
module WEB-INF
or enterprise bean META-INF
directory.
-
Define the cache-entry elements necessary to identify the cacheable objects. See the
cachespec.xml file topic for a list of elements.
-
Develop cache ID rules.
To cache an object, WebSphere® Application Server must know how to generate unique IDs for
different invocations of that object. The <cache-id> element performs that
task. Each cache entry can have multiple cache-ID rules that run in order until either a rule
returns cache-ID that is not empty or no more rules remain to run. If no cache-ID generation rules
produce a valid cache ID, then the object is not cached. Develop the cache IDs in one of two ways:
- Use the <component> element defined in the cache policy of a cache
entry (recommended). Refer to the cachespec_xml file topic for more information about the
<component> element.
- Write custom Java™ code to build the ID from input variables and system state. To configure
the cache entry to use the ID generator, specify your IdGenerator in the XML file by using the
<idgenerator> tag, for example:
<cache-entry>
<class>servlet</class>
<name>/servlet/CommandProcessor</name>
<cache-id>
<idgenerator>com.mycompany.SampleIdGeneratorImpl</idgenerator>
<timeout>60</timeout>
</cache-id>
</cache-entry>
-
Specify dependency ID rules.
Use dependency ID elements to specify additional cache group identifiers that associate
multiple cache entries to the same group identifier.
The dependency ID is generated by
concatenating the dependency ID base string with the values returned by its component elements. If a
required component returns a null value, then the entire dependency ID does not generate and is not
used. You can validate the dependency IDs explicitly through the dynamic cache API, or use another
cache-entry <invalidation> element. Multiple dependency ID rules can exist
per cache entry. All dependency ID rules run separately. See cachespec.xml file topic for a list of
<component> elements.
-
Invalidate other cache entries as a side effect of this object start, if relevant.
You can define invalidation rules in exactly the same manner as dependency IDs. However, the
IDs that are generated by invalidation rules are used to invalidate cache entries that have those
same dependency IDs.
The invalidation ID is generated by concatenating the invalidation ID base
string with the values returned by its component element. If a required component returns a null
value, then the entire invalidation ID is not generated and no invalidation occurs. Multiple
invalidation rules can exist per cache-entry. All invalidation rules run separately.
-
Ensure your cache policy is working correctly.
You can modify the policies within the cachespec.xml
file while your
application is running. The dynamic cache reloads the updated file automatically. If you are caching
static content and you are adding the cache policy to an application for the first time, you must
restart the application. You do not need to restart the application server to activate the new cache
policy. Refer to the Verifying the cacheable page topic for more information.
What to do next
Typically you declare several <cache-entry> elements inside a
cachespec.xml
file. When new versions of the cachespec.xml
are
detected, the old policies are replaced. Objects that cached through the old policy file are not
automatically invalidated from the cache; they are either reused with the new policy or eliminated
from the cache through its replacement algorithm.
For each of the three IDs (cache,
dependency, invalidation) generated by cache entries, a <cache-entry>
can
contain multiple elements. The dynamic cache runs the <cache-id> rules in
order, and the first one that successfully generates an ID is used to cache that output. If the
object is to be cached, each one of the <dependency-id> elements is run to
build a set of dependency IDs for that cache entry. Finally, each of the
<invalidation> elements are run, building a list of IDs that the dynamic
cache invalidates, whether or not this object is cached.