org.apache.velocity.tools.view
Class VelocityView

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

public class VelocityView
extends ViewToolManager

The class provides the following features:

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


Copyright (c) 2003-2007 Apache Software Foundation