org.apache.velocity.tools.view
Class VelocityView

java.lang.Object
  org.apache.velocity.tools.ToolManager
      org.apache.velocity.tools.view.ViewToolManager
          org.apache.velocity.tools.view.VelocityView

public class VelocityView
extends ViewToolManager

The class provides the following features:

• renders Velocity templates
• provides support for an auto-loaded, configurable toolbox
• provides transparent access to the servlet request attributes, servlet session attributes and servlet context attributes by auto-searching them
• logs to the logging facility of the servlet API

VelocityView supports the following configuration parameters in web.xml:

org.apache.velocity.tools

Path and name of the toolbox configuration file. The path must be relative to the web application root directory. If this parameter is not found, the servlet will check for a toolbox file at '/WEB-INF/tools.xml'.

org.apache.velocity.properties

Path and name of the Velocity configuration file. The path must be relative to the web application root directory. If this parameter is not present, Velocity will check for a properties file at '/WEB-INF/velocity.properties'. If no file is found there, then Velocity is initialized with the settings in the classpath at 'org.apache.velocity.tools.view.velocity.properties'.

Version:

$Id: VelocityView.java 511959 2007-02-26 19:24:39Z nbubna $

Author:

Dave Bryson, Jon S. Stevens, Gabe Sidler, Geir Magnusson Jr., Kent Johnson, Daniel Rall, Nathan Bubna

Field Summary

static java.lang.String	CLEAN_CONFIGURATION_KEY Controls removal of tools or data with invalid configurations before initialization is finished.
static java.lang.String	CONTENT_TYPE_KEY The HTTP content type context key.
static java.lang.String	DEFAULT_CONTENT_TYPE The default content type for the response
static java.lang.String	DEFAULT_OUTPUT_ENCODING Default encoding for the output stream
static java.lang.String	DEFAULT_PROPERTIES_PATH Default Runtime properties.
private java.lang.String	defaultContentType
static java.lang.String	DEPRECATED_TOOLS_KEY Deprecated.
static java.lang.String	DEPRECATED_USER_TOOLS_PATH Deprecated.
static java.lang.String	DEPRECATION_SUPPORT_MODE_KEY Controls support for deprecated tools and configuration.
private boolean	deprecationSupportMode
static java.lang.String	LOAD_DEFAULTS_KEY Controls loading of available default tool configurations provided by VelocityTools.
static java.lang.String	PROPERTIES_KEY This is the string that is looked for when getInitParameter is called ("org.apache.velocity.properties").
static java.lang.String	SERVLET_CONTEXT_KEY Key used to access the ServletContext in the Velocity application attributes.
static java.lang.String	TOOLS_KEY Key used to access the toolbox configuration file path from the Servlet or webapp init parameters ("org.apache.velocity.tools") or to access a live FactoryConfiguration previously placed in the ServletContext attributes.
static java.lang.String	USER_OVERWRITE_KEY Controls whether or not templates can overwrite tool and servlet API variables in the local context.
static java.lang.String	USER_PROPERTIES_PATH Default velocity properties file path.
static java.lang.String	USER_TOOLS_PATH Default toolbox configuration file path.
private static org.apache.velocity.util.SimplePool	writerPool

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

CREATE_SESSION_PROPERTY, DEFAULT_TOOLBOX_KEY, PUBLISH_TOOLBOXES_PROPERTY, servletContext

Fields inherited from class org.apache.velocity.tools.ToolManager

factory, velocity

Constructor Summary

VelocityView(javax.servlet.FilterConfig config)

VelocityView(JeeConfig config)

VelocityView(javax.servlet.ServletConfig config)

VelocityView(javax.servlet.ServletContext context)

Method Summary

protected void	configure(JeeConfig config, ToolboxFactory factory) Here's the configuration lookup/loading order: If deprecationSupportMode is true: Config file optionally specified by org.apache.velocity.toolbox init-param (servlet or servletContext) If none, config file optionally at /WEB-INF/toolbox.xml (deprecated conventional location) If no old toolbox or loadDefaults is true, ConfigurationUtils.getDefaultTools() ConfigurationUtils.getAutoLoaded()(false) Config file optionally specified by servletContext org.apache.velocity.tools init-param Config file optionally at /WEB-INF/tools.xml (new conventional location) Config file optionally specified by servlet org.apache.velocity.tools init-param Remember that as these configurations are added on top of each other, the newer values will always override the older ones.
protected void	configure(JeeConfig config, org.apache.velocity.app.VelocityEngine velocity)
ViewToolContext	createContext(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response) Creates and returns an initialized Velocity context.
protected FactoryConfiguration	getConfiguration(java.lang.String path)
protected FactoryConfiguration	getConfiguration(java.lang.String path, boolean required)
java.lang.String	getDefaultContentType() Returns the configured default Content-Type.
protected FactoryConfiguration	getDeprecatedConfig(JeeConfig config) Deprecated.
protected java.io.InputStream	getInputStream(java.lang.String path, boolean required)
protected org.apache.commons.collections.ExtendedProperties	getProperties(java.lang.String path)
protected org.apache.commons.collections.ExtendedProperties	getProperties(java.lang.String path, boolean required)
protected java.lang.String	getProperty(java.lang.String key, java.lang.String alternate) Simplifies process of getting a property from VelocityEngine, because the VelocityEngine interface sucks compared to the singleton's.
org.apache.velocity.Template	getTemplate(javax.servlet.http.HttpServletRequest request) Gets the requested template.
org.apache.velocity.Template	getTemplate(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response)
org.apache.velocity.Template	getTemplate(java.lang.String name) Retrieves the requested template.
org.apache.velocity.Template	getTemplate(java.lang.String name, java.lang.String encoding) Retrieves the requested template with the specified character encoding.
protected void	init(JeeConfig config) Initializes ToolboxFactory, VelocityEngine, and sets default encoding for processing requests.
protected void	init(JeeConfig config, org.apache.velocity.app.VelocityEngine velocity) Initializes the Velocity runtime, first calling loadConfiguration(JeeConfig) to get a org.apache.commons.collections.ExtendedProperties of configuration information and then calling velocityEngine.init().
void	merge(org.apache.velocity.Template template, org.apache.velocity.context.Context context, java.io.Writer writer) Merges the template with the context.
protected void	performMerge(org.apache.velocity.Template template, org.apache.velocity.context.Context context, java.io.Writer writer) This is here so developers may override it and gain access to the Writer which the template will be merged into.
org.apache.velocity.context.Context	render(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response)
org.apache.velocity.context.Context	render(javax.servlet.http.HttpServletRequest request, java.io.Writer out)
private boolean	setConfig(FactoryConfiguration factory, java.lang.String path, boolean require)
void	setDefaultContentType(java.lang.String type) Sets the configured default Content-Type.
protected void	setDeprecationSupportMode(boolean support) Deprecated.
protected void	setEncoding(JeeConfig config)
private boolean	setProps(org.apache.velocity.app.VelocityEngine velocity, java.lang.String path, boolean require)
void	setVelocityEngine(org.apache.velocity.app.VelocityEngine engine) Overrides super class to ensure engine is not set to null.

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

addToolboxes, autoConfigure, configure, createContext, findConfig, getCreateSession, getPublishToolboxes, getSessionToolbox, getToolboxKey, hasSessionTools, prepareContext, publishToolboxes, publishToolboxes, setCreateSession, setPublishToolboxes, setToolboxKey, unpublishApplicationTools, updateGlobalProperties

Methods inherited from class org.apache.velocity.tools.ToolManager

configure, createContext, createToolbox, debug, getApplicationToolbox, getLog, getRequestToolbox, getToolboxFactory, getUserCanOverwriteTools, getVelocityEngine, hasApplicationTools, hasRequestTools, hasTools, prepareContext, setToolboxFactory, setUserCanOverwriteTools

Methods inherited from class java.lang.Object

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

Field Detail

CONTENT_TYPE_KEY

public static final java.lang.String CONTENT_TYPE_KEY

The HTTP content type context key.

See Also:

Constant Field Values

SERVLET_CONTEXT_KEY

public static final java.lang.String SERVLET_CONTEXT_KEY

Key used to access the ServletContext in the Velocity application attributes.

DEFAULT_CONTENT_TYPE

public static final java.lang.String DEFAULT_CONTENT_TYPE

The default content type for the response

See Also:

Constant Field Values

DEFAULT_OUTPUT_ENCODING

public static final java.lang.String DEFAULT_OUTPUT_ENCODING

Default encoding for the output stream

See Also:

Constant Field Values

TOOLS_KEY

public static final java.lang.String TOOLS_KEY

Key used to access the toolbox configuration file path from the Servlet or webapp init parameters ("org.apache.velocity.tools") or to access a live FactoryConfiguration previously placed in the ServletContext attributes.

See Also:

Constant Field Values

DEPRECATED_TOOLS_KEY

@Deprecated
public static final java.lang.String DEPRECATED_TOOLS_KEY

Deprecated.

See Also:

Constant Field Values

USER_TOOLS_PATH

public static final java.lang.String USER_TOOLS_PATH

Default toolbox configuration file path. If no alternate value for this is specified, the servlet will look here.

See Also:

Constant Field Values

DEPRECATED_USER_TOOLS_PATH

@Deprecated
public static final java.lang.String DEPRECATED_USER_TOOLS_PATH

Deprecated.

See Also:

Constant Field Values

DEFAULT_PROPERTIES_PATH

public static final java.lang.String DEFAULT_PROPERTIES_PATH

Default Runtime properties.

See Also:

Constant Field Values

PROPERTIES_KEY

public static final java.lang.String PROPERTIES_KEY

This is the string that is looked for when getInitParameter is called ("org.apache.velocity.properties").

See Also:

Constant Field Values

USER_PROPERTIES_PATH

public static final java.lang.String USER_PROPERTIES_PATH

Default velocity properties file path. If no alternate value for this is specified, the servlet will look here.

See Also:

Constant Field Values

LOAD_DEFAULTS_KEY

public static final java.lang.String LOAD_DEFAULTS_KEY

Controls loading of available default tool configurations provided by VelocityTools. The default behavior is conditional; if DEPRECATION_SUPPORT_MODE_KEY has not been set to false and there is an old toolbox.xml configuration present, then the defaults will not be loaded unless you explicitly set this property to true in your init params. If there is no toolbox.xml and/or the deprecation support is turned off, then the default tools will be loaded automatically unless you explicitly set this property to false in your init params.

See Also:

Constant Field Values

CLEAN_CONFIGURATION_KEY

public static final java.lang.String CLEAN_CONFIGURATION_KEY

Controls removal of tools or data with invalid configurations before initialization is finished. The default is false; set to true to turn this feature on.

See Also:

Constant Field Values

USER_OVERWRITE_KEY

public static final java.lang.String USER_OVERWRITE_KEY

Controls whether or not templates can overwrite tool and servlet API variables in the local context. The default is true; set to false to prevent overwriting of any tool variables.

See Also:

Constant Field Values

DEPRECATION_SUPPORT_MODE_KEY

public static final java.lang.String DEPRECATION_SUPPORT_MODE_KEY

Controls support for deprecated tools and configuration. The default is true; set to false to turn off support for deprecated tools and configuration.

See Also:

Constant Field Values

writerPool

private static org.apache.velocity.util.SimplePool writerPool

defaultContentType

private java.lang.String defaultContentType

deprecationSupportMode

private boolean deprecationSupportMode

Constructor Detail

VelocityView

public VelocityView(javax.servlet.ServletConfig config)

VelocityView

public VelocityView(javax.servlet.FilterConfig config)

VelocityView

public VelocityView(javax.servlet.ServletContext context)

VelocityView

public VelocityView(JeeConfig config)

Method Detail

setDeprecationSupportMode

@Deprecated
protected final void setDeprecationSupportMode(boolean support)

Deprecated.

setVelocityEngine

public void setVelocityEngine(org.apache.velocity.app.VelocityEngine engine)

Overrides super class to ensure engine is not set to null.

Overrides:

setVelocityEngine in class ToolManager

getDefaultContentType

public java.lang.String getDefaultContentType()

Returns the configured default Content-Type.

setDefaultContentType

public void setDefaultContentType(java.lang.String type)

Sets the configured default Content-Type.

getProperty

protected java.lang.String getProperty(java.lang.String key,
                                       java.lang.String alternate)

Simplifies process of getting a property from VelocityEngine, because the VelocityEngine interface sucks compared to the singleton's. Use of this method assumes that init(JeeConfig,VelocityEngine) has already been called.

init

protected void init(JeeConfig config)

Initializes ToolboxFactory, VelocityEngine, and sets default encoding for processing requests.

NOTE: If no charset is specified in the default.contentType property (in your velocity.properties) and you have specified an output.encoding property, then that will be used as the charset for the default content-type of pages served by this servlet.

Parameters:

config - servlet configuation

init

protected void init(JeeConfig config,
                    org.apache.velocity.app.VelocityEngine velocity)

Initializes the Velocity runtime, first calling loadConfiguration(JeeConfig) to get a org.apache.commons.collections.ExtendedProperties of configuration information and then calling velocityEngine.init(). Override this to do anything to the environment before the initialization of the singleton takes place, or to initialize the singleton in other ways.

Parameters:

config - servlet configuration parameters

configure

protected void configure(JeeConfig config,
                         org.apache.velocity.app.VelocityEngine velocity)

setProps

private boolean setProps(org.apache.velocity.app.VelocityEngine velocity,
                         java.lang.String path,
                         boolean require)

configure

protected void configure(JeeConfig config,
                         ToolboxFactory factory)

Here's the configuration lookup/loading order:

1. If deprecationSupportMode is true:
   1. Config file optionally specified by org.apache.velocity.toolbox init-param (servlet or servletContext)
   2. If none, config file optionally at /WEB-INF/toolbox.xml (deprecated conventional location)
2. If no old toolbox or loadDefaults is true, ConfigurationUtils.getDefaultTools()
3. ConfigurationUtils.getAutoLoaded()(false)
4. Config file optionally specified by servletContext org.apache.velocity.tools init-param
5. Config file optionally at /WEB-INF/tools.xml (new conventional location)
6. Config file optionally specified by servlet org.apache.velocity.tools init-param

Remember that as these configurations are added on top of each other, the newer values will always override the older ones. Also, once they are all loaded, this method can "clean" your configuration of all invalid tool, toolbox or data configurations if you set the org.apache.velocity.tools.cleanConfiguration init-param to true in either your servlet or servletContext init-params.

getDeprecatedConfig

@Deprecated
protected FactoryConfiguration getDeprecatedConfig(JeeConfig config)

Deprecated.

First tries to find a path to a toolbox under the deprecated org.apache.velocity.toolbox key. If found, it tries to load the configuration there and will blow up if there is no config file there. If not found, it looks for a config file at /WEB-INF/toolbox.xml (the deprecated default location) and tries to load it if found.

setConfig

private boolean setConfig(FactoryConfiguration factory,
                          java.lang.String path,
                          boolean require)

getInputStream

protected java.io.InputStream getInputStream(java.lang.String path,
                                             boolean required)

getProperties

protected org.apache.commons.collections.ExtendedProperties getProperties(java.lang.String path)

getProperties

protected org.apache.commons.collections.ExtendedProperties getProperties(java.lang.String path,
                                                                          boolean required)

getConfiguration

protected FactoryConfiguration getConfiguration(java.lang.String path)

getConfiguration

protected FactoryConfiguration getConfiguration(java.lang.String path,
                                                boolean required)

setEncoding

protected void setEncoding(JeeConfig config)

render

public org.apache.velocity.context.Context render(javax.servlet.http.HttpServletRequest request,
                                                  javax.servlet.http.HttpServletResponse response)
                                           throws java.io.IOException

Parameters:

request - HttpServletRequest object containing client request

response - HttpServletResponse object for the response

Returns:

the Context prepared and used to perform the rendering to allow proper cleanup afterward

Throws:

java.io.IOException

render

public org.apache.velocity.context.Context render(javax.servlet.http.HttpServletRequest request,
                                                  java.io.Writer out)
                                           throws java.io.IOException

Throws:

java.io.IOException

createContext

public ViewToolContext createContext(javax.servlet.http.HttpServletRequest request,
                                     javax.servlet.http.HttpServletResponse response)

Creates and returns an initialized Velocity context.

A new context of class ViewToolContext is created and initialized.

Overrides:

createContext in class ViewToolManager

Parameters:

request - servlet request from client

response - servlet reponse to client

getTemplate

public org.apache.velocity.Template getTemplate(javax.servlet.http.HttpServletRequest request)

Gets the requested template.

Parameters:

request - client request

Returns:

Velocity Template object or null

getTemplate

public org.apache.velocity.Template getTemplate(javax.servlet.http.HttpServletRequest request,
                                                javax.servlet.http.HttpServletResponse response)

getTemplate

public org.apache.velocity.Template getTemplate(java.lang.String name)

Retrieves the requested template.

Parameters:

name - The file name of the template to retrieve relative to the template root.

Returns:

The requested template.

Throws:

org.apache.velocity.exception.ResourceNotFoundException - if template not found from any available source.

ParseErrorException - if template cannot be parsed due to syntax (or other) error.

getTemplate

public org.apache.velocity.Template getTemplate(java.lang.String name,
                                                java.lang.String encoding)

Retrieves the requested template with the specified character encoding.

Parameters:

name - The file name of the template to retrieve relative to the template root.

encoding - the character encoding of the template

Returns:

The requested template.

Throws:

org.apache.velocity.exception.ResourceNotFoundException - if template not found from any available source.

ParseErrorException - if template cannot be parsed due to syntax (or other) error.

merge

public void merge(org.apache.velocity.Template template,
                  org.apache.velocity.context.Context context,
                  java.io.Writer writer)
           throws java.io.IOException

Merges the template with the context. Only override this if you really, really really need to. (And don't call us with questions if it breaks :)

Parameters:

template - template being rendered

context - Context created by the createContext(javax.servlet.http.HttpServletRequest, javax.servlet.http.HttpServletResponse)

writer - into which the content is rendered

Throws:

java.io.IOException

performMerge

protected void performMerge(org.apache.velocity.Template template,
                            org.apache.velocity.context.Context context,
                            java.io.Writer writer)
                     throws java.io.IOException

This is here so developers may override it and gain access to the Writer which the template will be merged into. See VELTOOLS-7 for discussion of this.

Parameters:

template - template object returned by the handleRequest() method

context - Context created by the createContext(javax.servlet.http.HttpServletRequest, javax.servlet.http.HttpServletResponse)

writer - a VelocityWriter that the template is merged into

Throws:

java.io.IOException