Cache Plugin

Name	Cache Plugin
Vendor	Bob Swift, Jason Dillon, and other contributors
Authors	Bob Swift
Homepage	http://confluence.atlassian.com/display/CONFEXT/Cache+Plugin
Issue Management	http://developer.atlassian.com/jira/browse/cache
Continuous Integration	n/a
Categories	Content Macros
Most Recent Version	3.1.0
Availability	Confluence v2.4.2 to v2.10
State	Stable
Support
License	Freeware / Open Source (BSD)
Price	Free
Release Docs	http://confluence.atlassian.com/display/CONFEXT/Cache+Plugin
Java API Docs	n/a
Download Source	http://svn.atlassian.com/svn/public/contrib/confluence/cache-plugin/trunk
Download JAR	cache-plugin-3.1.0.jar

Additions and corrections to above

JVM requirements	Java 1.4 and above
Installation requirements	Confluence Repository Client or upload from Confluence's administration console. Cannot be installed in /WEB-INF/lib

Description

Allows cache control of page-level elements.

Caches the rendered contents of the body of this macro. Very useful when using macros that might be slow to render content, but where it does not really need to be dynamically generated for each and every request. Specifically, this can improve performance for accessing dynamic data from sql, excel, and similar macros. Cache will be refreshed if the body of the macro changes or if attachments to this page have been added, removed, or have newer versions. The cache applies to all users that view this page.

Based on OSCache.

Documentation

• Help available in the notation guide.

Parameters

• refresh - Cache refresh period. Default is a day. A number will be treated as seconds. A number followed by one of the following characters will be treated as follows:
  • s - seconds.
  • m - minutes.
  • h - hours.
  • d - days.

    Any data after a s, m, h, or d is ignored. For example, 10days is the same as 10d or 10 days.

• cron - Cron-like expression for finer grained expiration. See Cron Expressions.
• showRefresh - Show a refresh icon if showRefresh=true. Default is false. When the refresh icon is clicked, the cache for this macro will be discarded forcing the data to be regenerated.
• showDate - Show the date and time that data was generated if showDate=true. Default is false. The date field follows the refresh icon and before the data.
• checkAttachments - Default is true. If true, the cache will be refreshed if there is any change in the attachments on this page. This includes adding, removing, or changing the version of any attachment. For instance, if you are caching the rendering of the an excel spreadsheet, then the data will be refresh if the attached spreadsheet is updated.
• title - Title to show when mouse is over the refresh icon. Default is "Refresh".

Customization

• For normal usage, properties do not need to be changed.
• Properties for the cache behavior are specified in .../WEB-INF/classes/oscache.properties.
• The properties file ships with Confluence and applies to the cache macro and other components using the defaults for the OSCache support. The default is:

  cache.memory=true
  cache.capacity=100
  

• The capacity property equal to 100 means that 100 distinct renderings of the cache macro will be cached. Additional distinct renderings will replace previously cached entries. You should increase the capacity only if you used the cache macro in many places (over 100) that are accessed regularly and the extra JVM memory used will be acceptable.

Usage

{cache}
Something to cache for a day
{cache}

{cache:refresh=30m}
This will be cached for 30 minutes
{cache}

{cache:refresh=2 hours}
The excel data will be cached for 2 hours
{excel:file=^Report.xls}
{cache}

{cache:cron=30 * * * *|showRefresh=true|title=Refresh data from database}
This will be cached until 30 minutes past each hour of the day
{sql:dataSource=ReportDS}
select * from report
{sql}
{cache}

{cache:refresh=1d|showRefresh=true|showDate=true}
{beanshell}
System.out.println("Hello world " + (new Date()) );
{beanshell}
{cache}

Advanced Example

• Site Statistics

Tips and Techniques

• Page display performance tips and techniques

Compatibility With Other Macros

Macros known to be allowed in the body of the cache macro

• SQL Plugin
• CSV Macro
• Beanshell Macro
• Groovy Macro
• Jython Macro
• Excel Plugin
• HTML Plugin
• XSLT Macro
• Jasper Report Plugin - with some exceptions for images
• Confluence Chart Plugin - see Site Statistics for examples.

  Caching chart images If you use the cache macro around the chart macro, you must use the attachment support provided by CHRT-38.

Macros known to not work with the cache macro

• {excerpt} - if the excerpt is defined within a cache, you will not be able to retrieve it's contents using the {excerpt-include} macro.
• Flowchart macro and other graphviz related macros
• Other macros that generate dynamic images

Other information

Cache Refresh

• To force all cache macros on a page to refresh, use a request attribute
  • Example

    http://localhost/display/SCRIPT/test?refresh=true
    

Cache Flushing

• To force all or portions of the entire cache to be flushed, use a request attribute on a page that uses the cache macro
  • Example - all

    http://localhost/display/SCRIPT/test?cache-flush=all
    

  • Example - refresh first cache macro on page

    http://localhost/display/SCRIPT/test?refresh=1
    

Warnings, restrictions, and dependencies

This macro support Macro Security Plugin

Screenshots

showRefresh=true and showDate=true	showRefresh=true

Version History

• Previous versions were included in Scripting and External Content Macros

Release Notes

• 3.2.0 beta
  When: 03-Feb-2008
  Who: Bob Swift
  What:
• Beta only - not in plugin repository
• See Indexing External Content for information
• Tested on 2.5.2 and 2.7.1

• 3.1.0
  When: 24-Jun-2007
  Who: Bob Swift
  What:

Open Issues

New issue tracking JIRA project