org.wandora.modules.servlet

Class CachedAction

java.lang.Object

org.wandora.modules.AbstractModule

org.wandora.modules.ScriptModule

org.wandora.modules.servlet.AbstractAction

org.wandora.modules.servlet.CachedAction

All Implemented Interfaces:

Module, ActionHandler, ServletModule.RequestListener

Direct Known Subclasses:

FNGAPIAction, GenericTemplateAction, ImageResizeAction, RequestForwarder

public abstract class CachedAction
extends AbstractAction

This is a base class for actions that take advantage of caching services. You can naturally also directly use the caching service without deriving from this class, but many common operations are already done here.

As described in the CacheService class, the basic idea in caching is that each cached page has a unique key identifying it. If in the future you need a page with a key that has already been cached, you can just return the cached page instead. The key itself is just any string that identifies the page. As such, everything that affects the page has to be somehow included in the key. This class contains a method, buildCacheKey, that takes a String map and builds a cache key based on that. The key will essentially be a serialisation of the Map. It is not required that you use this method to make the key but it is suitable for most situations.

Obviously it is not useful to cache actions that are highly dynamic and requests with the exact same key are unlikely to happen often.

To have an action use caching at all, the caching parameter in init parameters has to be set to true. By default caching is turned off. This is because many actions derive from this class that could potentially benefit from caching in some situations but not always.

When extending this class, you have to override at least the doOutput method, which writes the page into a stream. The stream might either be returned directly, or it may be written to a disk from where a copy is then automatically returned to the request.

You can also override returnOutput, which forwards data from an input stream into an HTTP response. The input stream might be coming from a cached file, or directly from do Output. The default implementation sets the HTTP headers possibly defined in AbstractAction and then copies the output directly. If you wish to set additional headers, such as content type or character encoding, the way to do it is to use writeMetadata in doOutput, which writes some extra information at the start of the stream, and then readMetadata at returnOutput, which reads it. Then you can add headers, or do anything else necessary, based on the metadata. The writing and reading of metadata must always be done symmetrically.

Author:

olli

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
class	CachedAction.OutputProvider A class used to pass an output stream to the doOutput method.

Field Summary

Fields

Modifier and Type	Field and Description
protected CacheService	cache The cache service used to cache this action.
protected boolean	caching Is caching turned on.
protected java.util.concurrent.ExecutorService	threadPool

Fields inherited from class org.wandora.modules.servlet.AbstractAction

actionParamKey, handledActions, httpHeaders, isDefaultAction, replacements, replacementsInitialized, servletModule

Fields inherited from class org.wandora.modules.ScriptModule

engine, initScript, persistentObjects, scriptManager, startScript, stopScript

Fields inherited from class org.wandora.modules.AbstractModule

autoStart, isInitialized, isRunning, logging, loggingModule, moduleManager

Constructor Summary

Constructors

Constructor and Description
CachedAction()

Method Summary

Modifier and Type	Method and Description
static java.lang.String	buildCacheKey(java.util.Map<java.lang.String,java.lang.String> params) Builds a cache key from a Map of Strings.
protected abstract boolean	doOutput(javax.servlet.http.HttpServletRequest req, ModulesServlet.HttpMethod method, java.lang.String action, CachedAction.OutputProvider out, User user) Does the output that might be either cached or returned directly.
protected abstract java.lang.String	getCacheKey(javax.servlet.http.HttpServletRequest req, ModulesServlet.HttpMethod method, java.lang.String action) Should return a string that uniquely identifies this request.
java.util.Collection<Module>	getDependencies(ModuleManager manager) Returns all the modules this module depends on.
boolean	handleAction(javax.servlet.http.HttpServletRequest req, javax.servlet.http.HttpServletResponse resp, ModulesServlet.HttpMethod method, java.lang.String action, User user) Handles this action.
void	init(ModuleManager manager, java.util.HashMap<java.lang.String,java.lang.Object> settings) Initialises the module.
static java.util.Map<java.lang.String,java.lang.String>	readMetadata(java.io.InputStream in) Use this to read the metadata written by writeMetadata method.
private static java.lang.String	readUntilZero(java.io.InputStream in)
protected void	returnOutput(java.io.InputStream cacheIn, javax.servlet.http.HttpServletResponse resp) Writes a page read from an input stream into an HTTP servlet response.
void	start(ModuleManager manager) Starts the module.
void	stop(ModuleManager manager) Stops the module.
static void	writeMetadata(java.util.Map<java.lang.String,java.lang.String> data, java.io.OutputStream out) Use this to write some metadata at the start of the cached file, for example the mime type and character encoding of the file.

Methods inherited from class org.wandora.modules.servlet.AbstractAction

addHandledAction, doReplacements, handleRequest, isHandleAction, setActionParamKey, setHttpHeaders

Methods inherited from class org.wandora.modules.ScriptModule

getScriptEngine

Methods inherited from class org.wandora.modules.AbstractModule

isInitialized, isRunning, requireLogging, toString

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

cache

protected CacheService cache

The cache service used to cache this action.

caching

protected boolean caching

Is caching turned on.

threadPool

protected java.util.concurrent.ExecutorService threadPool

Constructor Detail

CachedAction

public CachedAction()

Method Detail

getDependencies

public java.util.Collection<Module> getDependencies(ModuleManager manager)
                                             throws ModuleException

Description copied from interface: Module

Returns all the modules this module depends on. This method will be called after init and the dependencies are allowed to depend on the parameters passed to init. The modules that this module depends on must be returned as a collection. In addition, if any required module is not present, a MissingDependencyException should be thrown. Typically you will use the requireModule and optionalModule methods of the manager to make sure that the modules exist and add them to the collection. requireModule will automatically throw the exception too if the module is not found whereas optionalModule does not.

Specified by:

getDependencies in interface Module

Overrides:

getDependencies in class AbstractAction

Parameters:

manager - The module manager handling this module.

Returns:

A collection of modules this module depends on.

Throws:

ModuleException

init

public void init(ModuleManager manager,
                 java.util.HashMap<java.lang.String,java.lang.Object> settings)
          throws ModuleException

Description copied from interface: Module

Initialises the module. After constructor, this is the first method called in the life cycle of a module. It should not perform anything time consuming or anything with notable outside side effects. It should only read the parameters and initialise the module so that it can later be started. Note that a module being initialised doesn't mean that it necessarily will ever be started.

A ModuleException may be thrown if something vital is missing from the parameters or they are not sensible. In some cases you may not want to throw an exception even if vital initialisation information is missing. If, for example, it is possible that the module is initialised in some other way between the init and the start method calls. A ModuleException may also be thrown at the start method if the module is still not initialised.

Specified by:

init in interface Module

Overrides:

init in class AbstractAction

Parameters:

manager - The module manager handling this module. You may keep a reference to it if needed.

Throws:

ModuleException

start

public void start(ModuleManager manager)
           throws ModuleException

Description copied from interface: Module

Starts the module. This will be called after init and getDependencies and signals that the module should now begin to perform whatever it was designed to do. This method call however should not block for long, so any time consuming tasks should be started in their own threads. You will typically get references to the required modules again in start using the findModule method of the manager and then store those references to instance variables for later use. You may throw a ModuleException if the module is not in a state where it can be started or it immediately becomes obvious that it cannot be started with the provided settings.

Specified by:

start in interface Module

Overrides:

start in class AbstractAction

Parameters:

manager - The module manager handling this module.

Throws:

ModuleException

stop

public void stop(ModuleManager manager)

Description copied from interface: Module

Stops the module. Should stop all threads used by the module, free any large data structures and perform other cleanup. It is possible that the module will be started again later with a start method call (and foregoing init and getDependencies calls). The module should be left in a state where this is possible.

Specified by:

stop in interface Module

Overrides:

stop in class AbstractAction

Parameters:

manager - The module manager handling this module.

buildCacheKey

public static java.lang.String buildCacheKey(java.util.Map<java.lang.String,java.lang.String> params)

Builds a cache key from a Map of Strings. Essentially serialises the map, with the keys having been sorted so that the same set of key-value pairs always returns the same cache key, even if the keys are returned in different order from the maps.

Parameters:

params - A map of key value pairs used in the cache key.

Returns:

A cache key.

getCacheKey

protected abstract java.lang.String getCacheKey(javax.servlet.http.HttpServletRequest req,
                                                ModulesServlet.HttpMethod method,
                                                java.lang.String action)

Should return a string that uniquely identifies this request. A future request with the same cache key may use the cached copy of the page. If you don't want some requests cached at all, return a null cache key for those pages. You can use the buildCacheKey method to create a cache key out of a map.

Parameters:

req - The HTTP request which, result of which is to be cached.

method - The method of the HTTP request.

action - The parsed action parameter from the request.

Returns:

A cache key that uniquely identifies the results of this request being processed.

returnOutput

protected void returnOutput(java.io.InputStream cacheIn,
                            javax.servlet.http.HttpServletResponse resp)
                     throws java.io.IOException

Writes a page read from an input stream into an HTTP servlet response. The input stream might be coming from a cached file, or directly from the doOutput method if caching is not in use. In any case, the contents of it need to be written to the response object. Note that any HTTP headers must be set before writing anything else.

If you used writeMetadata in doOutput, you have to override this method and use readMetadata correspondingly to read the metadata from the start of the stream. You can then, for example, set any HTTP headers you read from the metadata. After this, you can call this super implementation which will do the rest of the stream copying.

Make absolutely certain that the input stream is closed before returning from this method. Failing to do so may cause the caching service to become locked which can then lock the whole application. It is best to put the contents in a try-finally block and then call cacheIn.close in the finally part. Do this even if you call the super implementation as your code could possibly fail before reaching that part.

Parameters:

cacheIn -

resp -

Throws:

java.io.IOException

writeMetadata

public static void writeMetadata(java.util.Map<java.lang.String,java.lang.String> data,
                                 java.io.OutputStream out)
                          throws java.io.IOException

Use this to write some metadata at the start of the cached file, for example the mime type and character encoding of the file. Use this in doOutput as the first thing after opening the output stream. Read the metadata with readMetadata method in an overridden returnOutput.

Throws:

java.io.IOException

readUntilZero

private static java.lang.String readUntilZero(java.io.InputStream in)
                                       throws java.io.IOException

Throws:

java.io.IOException

readMetadata

public static java.util.Map<java.lang.String,java.lang.String> readMetadata(java.io.InputStream in)
                                                                     throws java.io.IOException

Use this to read the metadata written by writeMetadata method. These two methods must always be used in pair, do not try to use readMetadata if you haven't used writeMetadata. Make your cache keys in such a way that you'll always know whether metadata has been used or not. Use readMetadata by overriding returnOutput and reading it from the cache InputStream as the first thing, after that you can use the original returnOutput for the rest of the input stream.

Throws:

java.io.IOException

doOutput

protected abstract boolean doOutput(javax.servlet.http.HttpServletRequest req,
                                    ModulesServlet.HttpMethod method,
                                    java.lang.String action,
                                    CachedAction.OutputProvider out,
                                    User user)
                             throws javax.servlet.ServletException,
                                    java.io.IOException,
                                    ActionException

Does the output that might be either cached or returned directly. The OutputProvider is used to get the output stream where the output should be written. Before you get this stream, you may abort the action by returning false but after the output stream is retrieved, you are committed to outputting the page that then might be cached for future use. Therefore you should do all the preparations first, and only then get the output stream when you know that you will be able to output something sensible.

If you opened the output stream using the output provider, you must make sure that the stream is properly closed. It is best to place all your code after this in a try-finally block and close the stream in the finally part. Failing to do this may cause the caching service to become locked, which in turn could potentially lock the whole application.

Throws:

javax.servlet.ServletException

java.io.IOException

ActionException

handleAction

public boolean handleAction(javax.servlet.http.HttpServletRequest req,
                            javax.servlet.http.HttpServletResponse resp,
                            ModulesServlet.HttpMethod method,
                            java.lang.String action,
                            User user)
                     throws javax.servlet.ServletException,
                            java.io.IOException,
                            ActionException

Description copied from class: AbstractAction

Handles this action. Prior to calling this action, it's already been determined that this action should try to handle the action by either matching the action request parameter with the action id of this action, or this being the default action. Perform any operations needed here and then write the response into the response object. You will typically want to call setHttpHeaders to set the HTTP headers in the response after you know that you definitely will handle the request but before you write anything else into the response stream. If for whatever reason this method shouldn't handle the request after all, return false. Otherwise return true.

Specified by:

handleAction in class AbstractAction

Parameters:

req - The HTTP Request.

resp - The HTTP response.

method - The HTTP method of the request.

action - The parsed action id.

user - The logged in user, or null if not applicable.

Returns:

True if the action was handled and a response sent. False otherwise in which case other actions may try to handle this action.

Throws:

javax.servlet.ServletException

java.io.IOException

ActionException