org.apache.velocity.tools.view.servlet
Class ServletToolboxManager

java.lang.Object
  org.apache.velocity.tools.view.XMLToolboxManager
      org.apache.velocity.tools.view.servlet.ServletToolboxManager

All Implemented Interfaces:

ToolboxManager

public class ServletToolboxManager

extends XMLToolboxManager

A toolbox manager for the servlet environment.

A toolbox manager is responsible for automatically filling the Velocity context with a set of view tools. This class provides the following features:

• configurable through an XML-based configuration file
• assembles a set of view tools (the toolbox) on request
• handles different tool scopes (request, session, application)
• supports any class with a public constructor without parameters to be used as a view tool
• supports adding primitive data values to the context(String,Number,Boolean)

Configuration

The toolbox manager is configured through an XML-based configuration file. The configuration file is passed to the XMLToolboxManager.load(java.io.InputStream input) method. The format is shown in the following example:

 
 <?xml version="1.0"?>
 
 <toolbox>
   <tool>
      <key>link</key>
      <scope>request</scope>
      <class>org.apache.velocity.tools.view.tools.LinkTool</class>
   </tool>
   <tool>
      <key>date</key>
      <scope>application</scope>
      <class>org.apache.velocity.tools.generic.DateTool</class>
   </tool>
   <data type="number">
      <key>luckynumber</key>
      <value>1.37</value>
   </data>
   <data type="string">
      <key>greeting</key>
      <value>Hello World!</value>
   </data>
   <xhtml>true</xhtml>
 </toolbox>    
 

The recommended location for the configuration file is the WEB-INF directory of the web application.

Version:

$Id: ServletToolboxManager.html,v 1.8.2.1 2004/05/17 17:09:45 nbubna Exp $

Author:

Gabriel Sidler, Nathan Bubna, Geir Magnusson Jr.

Field Summary

private java.util.Map	appTools
private boolean	createSession
private static java.util.HashMap	managersMap
private java.util.ArrayList	requestToolInfo
private javax.servlet.ServletContext	servletContext
private static org.apache.commons.digester.RuleSet	servletRuleSet
static java.lang.String	SESSION_TOOLS_KEY
private java.util.ArrayList	sessionToolInfo

Fields inherited from class org.apache.velocity.tools.view.XMLToolboxManager

Constructor Summary

private

ServletToolboxManager(javax.servlet.ServletContext servletContext) Use getInstance(ServletContext,String) instead to ensure there is exactly one ServletToolboxManager per xml toolbox configuration file.

Method Summary

void	addTool(ToolInfo info) Overrides XMLToolboxManager to separate tools by scope.
static ServletToolboxManager	getInstance(javax.servlet.ServletContext servletContext, java.lang.String toolboxFile) ServletToolboxManager factory method.
protected java.lang.Object	getMutex(javax.servlet.http.HttpSession session) Returns a mutex (lock object) unique to the specified session to allow for reliable synchronization on the session.
protected org.apache.commons.digester.RuleSet	getRuleSet() For subclassing convienence.
ToolboxContext	getToolboxContext(java.lang.Object initData) Overrides XMLToolboxManager to handle the separate scopes.
void	setCreateSession(boolean b) Sets whether or not to create a new session when none exists for the current request and session-scoped tools have been defined for this toolbox.
void	setXhtml(java.lang.Boolean value) Sets an application attribute to tell velocimacros and tools (especially the LinkTool) whether they should output XHTML or HTML.

Methods inherited from class org.apache.velocity.tools.view.XMLToolboxManager

load

Methods inherited from class java.lang.Object

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

Field Detail

SESSION_TOOLS_KEY

public static final java.lang.String SESSION_TOOLS_KEY

servletContext

private javax.servlet.ServletContext servletContext

appTools

private java.util.Map appTools

sessionToolInfo

private java.util.ArrayList sessionToolInfo

requestToolInfo

private java.util.ArrayList requestToolInfo

createSession

private boolean createSession

managersMap

private static java.util.HashMap managersMap

servletRuleSet

private static org.apache.commons.digester.RuleSet servletRuleSet

Constructor Detail

ServletToolboxManager

private ServletToolboxManager(javax.servlet.ServletContext servletContext)

Use getInstance(ServletContext,String) instead to ensure there is exactly one ServletToolboxManager per xml toolbox configuration file.

Method Detail

getInstance

public static ServletToolboxManager getInstance(javax.servlet.ServletContext servletContext,
                                                java.lang.String toolboxFile)

ServletToolboxManager factory method. This method will ensure there is exactly one ServletToolboxManager per xml toolbox configuration file.

setCreateSession

public void setCreateSession(boolean b)

Sets whether or not to create a new session when none exists for the current request and session-scoped tools have been defined for this toolbox.

If true, then a call to getToolboxContext(Object) will create a new session if none currently exists for this request and the toolbox has one or more session-scoped tools designed.

If false, then a call to getToolboxContext(Object) will never create a new session for the current request. This effectively means that no session-scoped tools will be added to the ToolboxContext for a request that does not have a session object.

The default value is true.

setXhtml

public void setXhtml(java.lang.Boolean value)

Sets an application attribute to tell velocimacros and tools (especially the LinkTool) whether they should output XHTML or HTML.

Since:

VelocityTools 1.1

See Also:

ViewContext.XHTML

getRuleSet

protected org.apache.commons.digester.RuleSet getRuleSet()

For subclassing convienence.

Overrides:

getRuleSet in class XMLToolboxManager

Since:

VelocityTools 1.1

addTool

public void addTool(ToolInfo info)

Overrides XMLToolboxManager to separate tools by scope. For this to work, we obviously override getToolboxContext(Object) as well.

Specified by:

addTool in interface ToolboxManager

Overrides:

addTool in class XMLToolboxManager

getToolboxContext

public ToolboxContext getToolboxContext(java.lang.Object initData)

Overrides XMLToolboxManager to handle the separate scopes. Application scope tools were initialized when the toolbox was loaded. Session scope tools are initialized once per session and stored in a map in the session attributes. Request scope tools are initialized on every request.

Specified by:

getToolboxContext in interface ToolboxManager

Overrides:

getToolboxContext in class XMLToolboxManager

Parameters:

initData - the ViewContext for the current servlet request

getMutex

protected java.lang.Object getMutex(javax.servlet.http.HttpSession session)

Returns a mutex (lock object) unique to the specified session to allow for reliable synchronization on the session.