org.wandora.modules.servlet

Class GenericTemplateAction

java.lang.Object

org.wandora.modules.AbstractModule

org.wandora.modules.ScriptModule

org.wandora.modules.servlet.AbstractAction

org.wandora.modules.servlet.CachedAction

org.wandora.modules.servlet.GenericTemplateAction

All Implemented Interfaces:

Module, ActionHandler, ServletModule.RequestListener

Direct Known Subclasses:

ChangeUserAction, NewAPIKeyAction, SendEmailAction, UserManagerAction, ViewTopicAction

public class GenericTemplateAction
extends CachedAction

A general purpose action that uses templates for output. This can be used on its own or subclassed in a few different ways.

Standalone use just takes some template specified in initialisation parameters, with parameter name templateKey, and gives it the default context returned by the template manager. You can add objects into the context with initialisation parameters of this action too, by prefixing the context variable name with "context.". The default context, with possible action specific additions, is passed to the template which can then produce the desired page.

To make the produced page depend on the HTTP request parameters, you can forward some of them directly into the template context. To do this, list the request parameters you would like forwarded in an initialisation parameter named forwardRequestParameters, separated by semicolons. Then the contents of the user provided request parameters are copied into the template context. Remember to sanity check any values thus forwarded. You can also set default values for such request parameters which are used if none are provided in the request. Do this by prefixing the initialisation parameter name with "defaultRequestParameter." and then adding the parameter name and put the value in the contents of the param element.

Simplest way to subclass is to just override the getTemplateContext method. It should use getDefaultTemplateContext as basis and then add whatever is needed in the context. If needed, you can then do any side effects here as well, like modifying a database or something similar.

For even more control, override the handleAction method. Then you have to call the template yourself and write the output to the HTTP response object.

This class extends CachedAction so if it is likely that the same page be generated often, it may be of use to cache the page. To do this, set the initialisation parameter caching to true, as per normal CachedAction behaviour. The default implementation will use the action name and all forwarded request parameters in the cache key. Assuming the default context doesn't contain anything dynamic, this should be adequate.

Author:

olli

Nested Class Summary

Nested classes/interfaces inherited from class org.wandora.modules.servlet.CachedAction

CachedAction.OutputProvider

Field Summary

Fields

Modifier and Type	Field and Description
protected java.util.HashMap<java.lang.String,java.lang.String>	defaultRequestParameters
protected java.util.ArrayList<java.lang.String>	forwardRequestParameters
protected java.lang.String	requestContextKey
protected java.util.HashMap<java.lang.String,java.lang.Object>	staticContext
protected java.lang.String	templateKey
protected TemplateManager	templateManager

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

cache, caching, 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
GenericTemplateAction()

Method Summary

Modifier and Type	Method and Description
protected 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 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.
protected java.util.LinkedHashMap<java.lang.String,java.lang.String>	getCacheKeyParams(javax.servlet.http.HttpServletRequest req, ModulesServlet.HttpMethod method, java.lang.String action) Returns the parameters used in building the cache key.
java.util.Collection<Module>	getDependencies(ModuleManager manager) Returns all the modules this module depends on.
protected java.util.LinkedHashMap<java.lang.String,java.lang.String>	getForwardedParameters(javax.servlet.http.HttpServletRequest req) Returns a map of the http request parameters that are to be forwarded to the template context.
protected java.util.HashMap<java.lang.String,java.lang.Object>	getStaticTemplateContext() Gets the static context to for templates.
protected Template	getTemplate(javax.servlet.http.HttpServletRequest req, ModulesServlet.HttpMethod method, java.lang.String action)
protected java.util.HashMap<java.lang.String,java.lang.Object>	getTemplateContext(Template template, javax.servlet.http.HttpServletRequest req, ModulesServlet.HttpMethod method, java.lang.String action, User user) Gets the template context used for a request.
void	init(ModuleManager manager, java.util.HashMap<java.lang.String,java.lang.Object> settings) Initialises the module.
void	putStaticContext(java.lang.String key, java.lang.Object o) Adds a value to the action specific static template context.
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.

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

buildCacheKey, handleAction, readMetadata, writeMetadata

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

requestContextKey

protected java.lang.String requestContextKey

templateManager

protected TemplateManager templateManager

templateKey

protected java.lang.String templateKey

forwardRequestParameters

protected java.util.ArrayList<java.lang.String> forwardRequestParameters

defaultRequestParameters

protected java.util.HashMap<java.lang.String,java.lang.String> defaultRequestParameters

staticContext

protected final java.util.HashMap<java.lang.String,java.lang.Object> staticContext

Constructor Detail

GenericTemplateAction

public GenericTemplateAction()

Method Detail

putStaticContext

public void putStaticContext(java.lang.String key,
                             java.lang.Object o)

Adds a value to the action specific static template context. The key value pair will be passed on to templates in the context.

Parameters:

key - The name of the variable in the context.

o - The value of the context variable.

getTemplate

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

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 CachedAction

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 CachedAction

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 CachedAction

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 CachedAction

Parameters:

manager - The module manager handling this module.

getStaticTemplateContext

protected java.util.HashMap<java.lang.String,java.lang.Object> getStaticTemplateContext()

Gets the static context to for templates. Includes action specific items added with putStaticContext as well as the template manager default context.

Returns:

The static template context.

getForwardedParameters

protected java.util.LinkedHashMap<java.lang.String,java.lang.String> getForwardedParameters(javax.servlet.http.HttpServletRequest req)

Returns a map of the http request parameters that are to be forwarded to the template context.

Parameters:

req - The HTTP request.

Returns:

A Map containing the forwarded parameters and their values.

getTemplateContext

protected java.util.HashMap<java.lang.String,java.lang.Object> getTemplateContext(Template template,
                                                                                  javax.servlet.http.HttpServletRequest req,
                                                                                  ModulesServlet.HttpMethod method,
                                                                                  java.lang.String action,
                                                                                  User user)
                                                                           throws ActionException

Gets the template context used for a request. Contains the static context as well forwarded request parameters. The static context contains both action specific context items and the template manager default context. In addition, the logged in user, if applicable, is added with the variable name user. Usually you don't want anything user specific cached so as a safety measure, the user variable is not added if caching is turned on. If you for some reason do, you will have to override this method.

This should be the main overriding point for extending classes. You can perform any tasks needed and then add things in the context. Often you don't need to override anything else besides this and the basic Module methods.

Parameters:

template - The template to be used.

req - The HTTP request.

method - The method of the HTTP request.

action - The action parameter parsed from the HTTP request.

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

Returns:

The template context used with processing the template for this action.

Throws:

ActionException

getCacheKeyParams

protected java.util.LinkedHashMap<java.lang.String,java.lang.String> getCacheKeyParams(javax.servlet.http.HttpServletRequest req,
                                                                                       ModulesServlet.HttpMethod method,
                                                                                       java.lang.String action)

Returns the parameters used in building the cache key. This implementation uses the request action parameter and all parameters that have been configured to be forwarded from the request into the template context.

Parameters:

req - The HTTP request for which cache key parameters are resolved.

method - The method of the HTTP request.

action - The parsed action parameter from the request.

Returns:

getCacheKey

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

Description copied from class: CachedAction

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.

Specified by:

getCacheKey in class CachedAction

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

Description copied from class: CachedAction

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.

Overrides:

returnOutput in class CachedAction

Throws:

java.io.IOException

doOutput

protected 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

Description copied from class: CachedAction

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.

Specified by:

doOutput in class CachedAction

Throws:

javax.servlet.ServletException

java.io.IOException

ActionException