Use this task to define cacheable objects inside the cachespec.xml,
found inside the Web module WEB-INF or enterprise bean META-INF directory.
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.
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 topic cachespec.xml file
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). See cachespec.xml file
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
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. See Verifying the cacheable page
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.