ServletSpeedster : Documentation

The configuration is given to the ServletSpeeder through it's servlet's
initial parameters.

A short explanation is provided below :

target - The real servlet or jsp that creates our output.
ruleclass - The class that is used for rule watching. Generally
you have no real need to write your own, but nobody tells you that you can't do it.
Usually this field has a value "org.servletspeedster.SpeedsterEventRule" or
"org.servletspeedster.SpeedsterTimeRule"
ruleparameter - The parameter given to the rule at initialization.
In the event based rule this should be an unique string by which
you can invalidate the cache right when you need it
In time based rule this counts the seconds after which
the orignal servlet will be called for a fresh output
watchparameters - List of request parameters which makes the
response unique, for example in long cached lists it could be the offset.
The fields are separated by commas. For example x,y,b.
Parameters not set in the list are discarded when comparing the request
to a cached one.
cachesize - This should be set to the number of pages which your
cache can maximally hold. Be reasonable when specifying it.
Normally this should be in between 1...1000 (1 single page vs list with 1000 offsets)
ignoresession - If you use cookie based sessions
and the cached outputs should depend on the session set this to false.
If you hold session id in the request as a parameter instead of having
it in the cookie, just put it SID in the watchparameters, the setting
ignoresession has no impact on them.
(In pure english, this only affects sites that use cookie based sessions.)
By default the session IS ignored.
forcegb - Forces garbage collection to be called
once a cache seems to be out of date and is replaced by a new one.
This shouldn't be used in normal cases for jvm should be smart enough by itself.
log - If this is set to true, logging will be enabled
even after initialization, maybe helpful while debugging where the cache
goes wrong
This shouldn't be used in normal cases, outputting the lines to system.out can
slow down your application, in performance needing mode be sure it's set to false
compression - If this is set to true, all cached content
in this Speedster will be compressed with gzip, this means it takes a lot less memory but speeds down a bit content creation and serving cached data.
You should probably use this when serving huge page parts.
[Since 0.9.3]
forbiddenpath - Forbids a path for accessing the cached content.
The value of this will be searched in the request real path being served, if it's being found the result will be a little error message.
It is recommended that you use this to avoid any kind of security leaks.
This is just to keep off hackers from your cached content.
If you don't specify this, ServletSpeedster will serve innocently whatever content is being asked for, for session-aware caches this is a MUST BE or any user can fake their identity with asking the stuff directly.
[Since 0.9.3]

An example config is given here:

SpeedsterServlet configuration

<!-- this is an very basic example :) -->
<servlet>
	<servlet-name>testCacher</servlet-name>
	<servlet-class>org.servletspeedster.SpeedsterServlet</servlet-class>
	<init-param>
		<param-name>ruleclass</param-name>
			<!-- the class for the cacheing rule -->
		<param-value>org.servletspeedster.SpeedsterEventRule</param-value>
			<!-- simple event based rule implementation -->
	</init-param>
	<init-param>
		<param-name>target</param-name>
			<!-- who gives us the real output ? -->
		<param-value>/test.jsp</param-value>
			<!-- the real output is received from /test.jsp ? -->
	</init-param>
	<init-param>
		<param-name>cachesize</param-name>
			<!-- cachesize counted in cached output objects -->
		<param-value>10</param-value>
			<!-- this instance can have max. 10 different page outputs in the cache -->
	</init-param>
	<init-param>
		<param-name>ruleparameter</param-name>
			<!-- the parameter for the rule if any, the default time and event rule need it -->
		<param-value>refreshTESTJSP</param-value>
			<!-- the magic string which will be invoked as an event to reset the cache -->
	</init-param>
	<load-on-startup>2</load-on-startup>
		<-- Make sure the servlet is started when you start your servlet engine
		so it could give you some error/warning output right on start-->
</servlet>

Mapping the pseudoname of the cached instance to the servlet

<servlet-mapping>
	<servlet-name>testCacher</servlet-name>
	<url-pattern>/cached/test.jsp</url-pattern>
	<!-- all requests to /cached/test.jsp are handled by the testCacher servlet-->
</servlet-mapping>

Requesting the cached jsp from an xml-syntax jsp page, in this case it fills a table cell.

<td colspan="2" bgcolor="#DDDDDD" align="center">
	<jsp:include page="/cached/top.jsp"/>
	<br/>(Text above is generated by top.jsp)
</td>

Requesting the cached jsp from an non-xml-syntax jsp page, in this case it also fills a table cell.

<td colspan="2" bgcolor="#DDDDDD" align="center">
<%
RequestDispatcher dispatcher = request.getRequestDispacher("/test.jsp");
dispatcher.include(request,response);
%>
</td>

Requesting the cached jsp from an servlet.

RequestDispatcher dispatcher = request.getRequestDispacher("/test.jsp");
dispatcher.include(request,response);

Invalidating the event based cache in java code
(there's a little difference if this resides in a servlet or jsp)

// in jsp
SpeedsterEventRule.invalidateCache(pageContext.getServletContext(),"refreshTESTJSP");
// in servlet
SpeedsterEventRule.invalidateCache(this.getServletContext(),"refreshTESTJSP");

PLEASE MAKE SURE YOU DON'T INVALIDATE CACHES IN CACHED PAGES ;-)

Set up the statistics servlet in your servlet container- To make use of the statistics you will have to declare it as a servlet and put it up under a certain path.
Example setup in web.xml

<!-- define the servlet -->
<servlet>
	<servlet-name>ServletSpeedsterStatistics</servlet-name>
	<servlet-class>org.servletspeedster.Statistics</servlet-class>
	<load-on-startup>1</load-on-startup>
</servlet>

<!-- associate servlet with a path -->
<servlet-mapping>
	<servlet-name>ServletSpeedsterStatistics</servlet-name>
	<url-pattern>/stats.jsp</url-pattern>
</servlet-mapping>

Fix your load-on-startup numbers- The idea of the statistics system is that at first the statistics servlet is being inited and after that the speedsterservlets are initing themselves and during it add themselves to the statistics list.
To achieve that a ServletSpeedster appears in the statistics set it's load-on-startup to greater than the load-on-startup of statistics. To make it disappear from statistics make it smaller than statistics load-on-startup.
If servlet A has load-on-startup set to 1 , the statistics has load-on-startup set to 2 and servlet B has load-on-startup set to 3. B will appear in the statistics and A won't.

Javadoc

Configuration help

How to set up your statistics view [0.9.3 and up]