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.
gotcha
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.