Essential Viewer Cache
Essential Viewer includes an open source web cache engine that can significantly improve the performance of Essential Viewer when rendering large or complex Views by caching the dynamically-rendered web pages.
By default and for simplicity, the web cache is disabled. However, you can easily enable the cache by making some simple configuration settings.
The configuration of the web cache is controlled in three parts:
- web.xml to prime Essential Viewer to use the web cache engine
- oscache.properties to control the configuration of the web cache engine
- essentialCache.xml to control how the cache is reset or cleared when receiving a new snapshot of the Essential repository or when using the Essential Maintenance Service
The first step to enabling the web cache is to tell Essential Viewer to use the caching engine. This is controlled separately for each Essential Viewer instance (in cases where multiple Essential Viewers are in use).
This is controlled in the file web.xml, which is found in the WEB-INF folder in every Essential Viewer installation, e.g.
C:\Program Files\Tomcat\webapps\essential_viewer\WEB_INF\web.xml
All the settings to enable the cache are already included in web.xml but are commented out and therefore not active. Open the file in a text editor such as TextEdit, Notepad or your favourite IDE. Scroll down to find the line:
Directly after this line, a section starting with is commented out by the XML / HTML comments:
starting with <!— and ending with —>
These comments must be removed.
Remove these comment characters (<!— and —> marked between the 5 *'s at the top and bottom) - preserving all the details of the and - and save the file.
Now that Essential Viewer is primed to use the web cache, the configuration is completed by setting up the cache itself. First, we must tell the web cache engine where to maintain the cache on the local server filesystem.
The cache configuration is managed in a file called oscache.properties which are found in WEB-INF/classes. Open this file in a text editor and find the section labelled: CACHE DIRECTORY. Following the guidance in the file, set the cache.path parameter to define the directory that the cache should use to store the generated web pages. We strongly recommend that you use the pageCache folder in the graph_images folder in Essential Viewer.
NOTE: the path you specify MUST be within your chosen Essential Viewer deployment.
The important point here is to set the full path to the Essential Viewer environment, which means updating the first parts of the example paths provided in the file. Note the use of ‘\\’ characters to define the paths on Windows platforms.
Update the section marked between the 5 *'s in the cache.path shown in the following example:
e.g.
The last step of the configuration is to prime the Essential Viewer platform to ensure that the cache is reset or cleared down whenever a new version of the repository snapshot is published to the Viewer.
This is controlled in the file platform/viewerCache.xml by a directory tag that specifies the folder used in the Cache Configuration with the addition of /application.
If you have used the default location in the last step (graph_images/pageCache within your Essential Viewer) then your configuration is complete. If you have used an alternative location, update the following entry to point to the location of your cache, keeping the “post” attribute unchanged.:
Once you have finished updating the file, save it.
If you have multiple Essential Viewers, this configuration must be repeated for each deployment for which you wish to enable the web cache capability.
Having completed the configuration and saved all the updated files, you must restart Tomcat for these to be activated. When Tomcat has restarted, you will see your cached Views being created in the cache folder that you specified in the second step.
