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

Fields
`static String` `CLEAN_CONFIGURATION_KEY` Controls removal of tools or data with invalid configurations before initialization is finished.
`static String` `CONTENT_TYPE_KEY` The HTTP content type context key.
`static String` `DEFAULT_CONTENT_TYPE` The default content type for the response
`static String` `DEFAULT_OUTPUT_ENCODING` Default encoding for the output stream
`static String` `DEFAULT_PROPERTIES_PATH` Default Runtime properties.
`static String` `LOAD_DEFAULTS_KEY` Controls loading of available default tool configurations provided by VelocityTools.
`static String` `OUTPUT_ENCODING_KEY` The HTTP output encoding.
`static String` `PROPERTIES_KEY` This is the string that is looked for when getInitParameter is called ("org.apache.velocity.properties").
`static String` `SERVLET_CONTEXT_KEY` Key used to access the ServletContext in the Velocity application attributes.
`static 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 String` `USER_OVERWRITE_KEY` Controls whether or not templates can overwrite tool and servlet API variables in the local context.
`static String` `USER_PROPERTIES_PATH` Default velocity properties file path.
`static String` `USER_TOOLS_PATH` Default toolbox configuration file path.

### 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, log, velocity`

### Constructor Summary

Constructors
Constructor and Description
`VelocityView(javax.servlet.FilterConfig config)`
`VelocityView(JeeConfig config)`
`VelocityView(javax.servlet.ServletConfig config)`
`VelocityView(javax.servlet.ServletContext context)`

### Method Summary

All Methods Instance Methods Concrete Methods

`protected void`

`configure(JeeConfig config, ToolboxFactory factory)`
Here's the configuration lookup/loading order: If loadDefaults is true, `ConfigurationUtils.getDefaultTools()` Config file optionally specified by servletContext `org.apache.velocity.tools` init-param Config file optionally at `/WEB-INF/tools.xml` (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(String path)`
`protected FactoryConfiguration` `getConfiguration(String path, boolean required)`
`String` `getDefaultContentType()`
`protected FactoryConfiguration` `getDefaultToolsConfiguration()`
`protected InputStream` `getInputStream(String path, boolean required)`
`protected Properties` `getProperties(String path)`
`protected Properties` `getProperties(String path, boolean required)`
`protected String` `getProperty(String key, 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(String name)` Retrieves the requested template.
`org.apache.velocity.Template` `getTemplate(String name, 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 java.util.Properties of configuration information and then calling velocityEngine.init().
`void` `merge(org.apache.velocity.Template template, org.apache.velocity.context.Context context, Writer writer)` Merges the template with the context.
`protected void` `performMerge(org.apache.velocity.Template template, org.apache.velocity.context.Context context, 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, Writer out)`
`void` `setDefaultContentType(String type)` Sets the configured default Content-Type.
`protected void` `setEncoding(JeeConfig config)`
`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, getSessionToolbox, getToolboxKey, hasSessionTools, prepareContext, publishApplicationTools, publishToolboxes, publishToolboxes, setCreateSession, setPublishToolboxes, setToolboxKey, unpublishApplicationTools, updateGlobalProperties`

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

`configure, createContext, createToolbox, getApplicationToolbox, getLog, getRequestToolbox, getToolboxFactory, getUserCanOverwriteTools, getVelocityEngine, hasApplicationTools, hasRequestTools, hasTools, initLog, 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 String CONTENT_TYPE_KEY

The HTTP content type context key.

See Also:
  Constant Field Values

#### OUTPUT_ENCODING_KEY

    public static final String OUTPUT_ENCODING_KEY

The HTTP output encoding.

See Also:
  Constant Field Values

#### SERVLET_CONTEXT_KEY

    public static final String SERVLET_CONTEXT_KEY

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

#### DEFAULT_CONTENT_TYPE

    public static final String DEFAULT_CONTENT_TYPE

The default content type for the response

See Also:
  Constant Field Values

#### DEFAULT_OUTPUT_ENCODING

    public static final String DEFAULT_OUTPUT_ENCODING

Default encoding for the output stream

See Also:
  Constant Field Values

#### TOOLS_KEY

    public static final 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

#### USER_TOOLS_PATH

    public static final 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

#### DEFAULT_PROPERTIES_PATH

    public static final String DEFAULT_PROPERTIES_PATH

Default Runtime properties.

See Also:
  Constant Field Values

#### PROPERTIES_KEY

    public static final 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 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 String LOAD_DEFAULTS_KEY

Controls loading of available default tool configurations provided by VelocityTools. The default is false.

See Also:
  Constant Field Values

#### CLEAN_CONFIGURATION_KEY

    public static final 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 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

### 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

#### 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 String getDefaultContentType()

Returns:
  the configured default Content-Type.

#### setDefaultContentType

    public void setDefaultContentType(String type)

Sets the configured default Content-Type.

Parameters:
  `type` - default content type

#### getProperty

    protected String getProperty(String key,
                                 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.

Parameters:
  `key` - property key
  `alternate` - default value
Returns:
  property value

#### 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 java.util.Properties 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
  `velocity` - VelocityEngine instance

#### configure

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

#### configure

    protected void configure(JeeConfig config,
                             ToolboxFactory factory)

Here's the configuration lookup/loading order:

1. If loadDefaults is true, `ConfigurationUtils.getDefaultTools()`
2. Config file optionally specified by servletContext `org.apache.velocity.tools` init-param
3. Config file optionally at `/WEB-INF/tools.xml` (conventional location)
4. 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.

Parameters:
  `config` - configuration values container
  `factory` - toolbox factory instance

#### getDefaultToolsConfiguration

    protected FactoryConfiguration getDefaultToolsConfiguration()

#### getInputStream

    protected InputStream getInputStream(String path,
                                         boolean required)

#### getProperties

    protected Properties getProperties(String path)

#### getProperties

    protected Properties getProperties(String path,
                                       boolean required)

#### getConfiguration

    protected FactoryConfiguration getConfiguration(String path)

#### getConfiguration

    protected FactoryConfiguration getConfiguration(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 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:
  `IOException` - if thrown by underling code

#### render

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

Throws:
  `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
Returns:
  newly created context

#### 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(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.
  `org.apache.velocity.exception.ParseErrorException` - if template cannot be parsed due to syntax (or other) error.

#### getTemplate

    public org.apache.velocity.Template getTemplate(String name,
                                                    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.
  `org.apache.velocity.exception.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,
                      Writer writer)
               throws 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:
  `IOException` - if thrown by underling code

#### performMerge

    protected void performMerge(org.apache.velocity.Template template,
                                org.apache.velocity.context.Context context,
                                Writer writer)
                         throws 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:
  `IOException` - if thrown by underling code