Modify the DynaCache configuration file
To cache full pages and fragments on the Web server, update the Dynamic Cache configuration file...
PROFILE_HOME/installedApps/Cell_Name/WC_<Instance>.ear/Stores.war/WEB-INF/cachespec.xml
To change the file, copy the file to your local machine and make the modifications that you need, as described in the following two sections...
We do not recommend changing it directly on the server, as updates to the file are effective immediately.
When you are done with editing the file, you can distribute it to all the application servers in your cluster, as described in Distribute cachespec.xml.
Caching full pages
To mark an entry to be cached using ESI, use the property EdgeCacheable. This property also implies the property of consume-subfragments. That is, the page will be cached as a full page, including all its subfragments, unless one of these subfragments is specified to be cacheable separately (refer to Caching fragments for details). In order to cache pages with ESI, only the parameter and cookie component can be used to define the cache ID.
Example 13-2 shows our cache-entry for the ECActionServlet servlet with a sample cache-id entry for the TopCategoriesDisplay URL, which is used to test full page caching.
<?xml version="1.0" ?>
<!DOCTYPE cache SYSTEM "cachespec.dtd">
<cache>
<cache-entry>
<class>servlet</class>
<name>com.ibm.commerce.struts.ECActionServlet.class</name>
<property name="store-cookies">false</property>
<property name="save-attributes">false</property>
<property name="EdgeCacheable">true</property>
...
<cache-id>
<component id="" type="pathinfo">
<required>true</required>
<value>/TopCategoriesDisplay</value>
</component>
<component id="storeId" type="parameter">
<required>true</required>
</component>
<component id="catalogId" type="parameter">
<required>true</required>
</component>
<component id="categoryId" type="parameter">
<required>false</required>
</component>
</cache-id>
...
</cache>
Caching fragments
Alternate URL is a method for edge caching JavaServer Pages (JSP) files and servlet responses that you cannot request externally. Dynamic cache provides support to recognize the presence of an Edge Side Include (ESI) processor and to generate ESI include tags and appropriate cache policies for edge cacheable fragments. However, for a fragment to be edge cacheable, be able to externally request it from the application server. In other words, if a user types the URL in her browser with the appropriate parameters and cookies for the fragment, WebSphere Application Server must return the content for that fragment.
The child JSP files are edge cacheable only if you can request these JSP files externally, which is not usually the case. For example, if a child JSP file uses one or more request attributes that are determined and set by the controller servlet, you cannot cache that JSP file on the edge. You can use alternate URL support to overcome this limitation by providing an alternate controller servlet URL used to invoke the JSP file.
The alternate URL for a JSP file or a servlet is set in the cachespec.xml file as a property with the name alternate_url. You can set the alternate URL either on a per cache-entry basis or on a per cache-id basis. It is valid only if the EdgeCacheable property is also set for that entry. If the EdgeCacheable property is not set, the alternate_url property is ignored.
A good example for WebSphere Commerce is a JSP, which displays a personalized mini shopping cart, and that is included by fully cached pages, for example, TopCategoriesDisplay (see above). See Example 13-3 for the cachespec.xml entry for the mini shopping cart JSP fragment.
In order to cache the TopCategoriesDisplay page and the mini shopping cart on the edge, we need to construct cache ID rules that only contain URL parameters or cookies. For the store catalog display page, it will not be a problem since all the information needed to cache it is on the URL. However, since the mini current order display is unique per user, we have to use the user's ID as the cache ID.
Since only URL parameters and cookies can be used to define the cache ID rule, and the URL does not contain the user's information, the only other way is to use a cookie that contains the user's ID information as a component of the cache ID.
Cookie support
Since Version 6.0, WebSphere Commerce provides some cookies that can be used as part of the cache-id. The DynaCache Event Listener listens to the session change events triggered by the user ID or store ID change and then performs the following actions:
To use cookies, perform one of the following steps:
Add the following component entry in the cachespec.xml file inside the <cache-id> tags of <cache-entry> elements that are dependent on session information.
<component id="<Component_ID>" type="cookie"> <required>true</required> </component>
Where <Component_ID> is one of the values listed in Table 13-1.
| Component_ID | Definition |
|---|---|
| WC_LANGID
Language ID | |
| WC_CURRID
Currency ID | |
| WC_PROG
Parent organization | |
| WC_CACHEID1
Contract ID | |
| WC_CACHEID2
Member groups | |
| WC_CACHEID3
Buyer contract ID | |
| WC_CACHEID4
User ID | |
| WC_CACHEID5
User type |
Example 13-3 shows how this would look like for the mini shopping cart display, using WC_CACHEID4 to include the user ID in the cache-id.
<cache-entry>
<class>servlet</class>
<name>/ConsumerDirect/include/MiniShopCart.jsp</name>
<property name="EdgeCacheable">true</property>
<property name="alternate_url">/servlet/ConsumerDirect/
de/MiniShopCart.jsp</property>
<property name="save-attributes">false</property>
<property name="do-not-consume">false</property>
<cache-id>
<component id="WC_CACHEID4" type="cookie">
<required>true</required>
</component>
</cache-id>
</cache-entry>
Insert a <cache-id> entry for each store into the cachespec.xml with the structure and properties show below for the mini shopping cart display.
<cache-entry>
<class>servlet</class>
<name>/ConsumerDirect/include/MiniShopCart.jsp</name>
<property name="EdgeCacheable">true</property>
<property name="alternate_url">/servlet/ConsumerDirect/include/MiniShopCart.jsp</property>
<property name="save-attributes">false</property>
<property name="do-not-consume">false</property>
<cache-id>
<component id="WC_CACHEID4_10001" type="cookie">
<required>true</required>
</component>
</cache-id>
<cache-id>
<component id="WC_CACHEID4_10002" type="cookie">
<required>true</required>
</component>
</cache-id>
</cache-entry>
At runtime the cookie generator dynamically produces a cookie named based on the storeId. For example, given the storeId 10001 and an English store, the cookie WC_LANGID_10001=-1 will be generated.
Distribute cachespec.xml
Once your cachespec.xml file is complete, you need to distribute it to your application servers. To do this:
- Open the admin console and navigate to...
Applications | Enterprise Applications
- Select your WebSphere Commerce application, WC_<Instance_Name>. In our case, the application is WC_demo.
- Click Update.
- On the Preparing for the application installation page, select Single file and enter...
Stores.war/WEB-INF/cachespec.xml
...in the field...
Relative path to file field
The relative path always starts at the root of the EAR.
In the box...
Upload the new or replacement files
...choose...
Local filesystem
...and specify your modified cachespec.xml file using the full path and filename.
- Click Next. A confirmation page is displayed stating the relative path just entered.
- Click OK. The application is now patched. This step only updates the Network Deployment Manager configuration. The updated file is not yet distributed to the application servers.
- When the installation has successfully completed, save the changes to the master configuration by clicking Save to master configuration.
- On the Save page, make sure that Distribute changes to nodes is activated, then click Save. This distributes the updated file to all application servers, where the changes become effective immediately after the file has been copied.
The ESI caching configuration is now complete.