org.apache.velocity.tools.view

## Class VelocityViewServlet

- java.lang.Object
- - javax.servlet.GenericServlet
  - - javax.servlet.http.HttpServlet
    - - org.apache.velocity.tools.view.VelocityViewServlet

All Implemented Interfaces:
  Serializable, javax.servlet.Servlet, javax.servlet.ServletConfig

Direct Known Subclasses:
  VelocityLayoutServlet

    public class VelocityViewServlet
    extends javax.servlet.http.HttpServlet

A servlet to process Velocity templates. This is comparable to the the JspServlet for JSP-based applications.

The servlet 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

VelocityViewServlet 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'.
org.apache.velocity.tools.shared.config
  By default, this is `true`. If set to `false`, then the `VelocityView` used by this servlet will not be shared with `VelocityViewFilter`s, other VelocityViewServlets or org.apache.velocity.tools.view.jsp.VelocityViewTag's in the application.
org.apache.velocity.tools.loadDefaults
  By default, this is `true`. If set to `false`, then the default toolbox configuration will not be added to your (if any) custom configuration.
org.apache.velocity.tools.cleanConfiguration
  By default, this is `false`. If set to `true`, then then the final toolbox configuration (the combination of any custom one(s) provided by yourself and/or the default configuration(s)) will have all invalid tools, properties, and/or data removed prior to configuring the ToolboxFactory for this servlet by a `ConfigurationCleaner`
org.apache.velocity.tools.bufferOutput
  By default, the processed templates are merged directly into the `HttpServletResponse`'s writer. If this parameter is set to `true`, then the output of the merge process will be buffered before being fed to the response. This allows the `error(javax.servlet.http.HttpServletRequest, javax.servlet.http.HttpServletResponse, java.lang.Throwable)` method to be overridden to return a "500 Internal Server Error" or at least not return any of the failed request content. Essentially, setting this to `true` degrades performance in order to enable a more "correct" error response"
org.apache.velocity.tools.view.class
  Allows to specify a custom class (inheriting from VelocityView) as the View class.

Version:
  $Id$
See Also:
  Serialized Form

### Field Summary

Fields
`static String` `BUFFER_OUTPUT_PARAM`

### Constructor Summary

Constructors
Constructor and Description
`VelocityViewServlet()`

### Method Summary

All Methods Instance Methods Concrete Methods Deprecated Methods
`protected org.apache.velocity.context.Context` `createContext(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response)` Get a configured Velocity context for the current request and response
`void` `doGet(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response)` Handles GET - calls doRequest()
`void` `doPost(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response)` Handle a POST request - calls doRequest()
`protected void` `doRequest(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response)` Handles with both GET and POST requests
`protected void` `error(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response, Throwable e)` Invoked when there is an error thrown in any part of doRequest() processing.
`protected void` `fillContext(org.apache.velocity.context.Context context, javax.servlet.http.HttpServletRequest request)` Standard extension point to populate the context with additional entries
`protected String` `findInitParameter(javax.servlet.ServletConfig config, String key)` Looks up an init parameter with the specified key in either the ServletConfig or, failing that, in the ServletContext.
`protected org.slf4j.Logger` `getLog()`
`protected Writer` `getOutputWriter(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response)` Get the output stream writer to use.
`protected org.apache.velocity.Template` `getTemplate(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response)` Get a template by client request and response
`protected org.apache.velocity.Template` `getTemplate(String name)` Get a template by name
`protected String` `getVelocityProperty(String name, String alternate)`
`protected VelocityView` `getVelocityView()`

`protected org.apache.velocity.Template`

`handleRequest(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response, org.apache.velocity.context.Context ctx)`
This was a common extension point, but now it is usually simpler to override `fillContext(org.apache.velocity.context.Context, javax.servlet.http.HttpServletRequest)` to add custom things to the `Context` or override a `getTemplate(javax.servlet.http.HttpServletRequest, javax.servlet.http.HttpServletResponse)` method to change how `Template`s are retrieved.

`void` `init(javax.servlet.ServletConfig config)` Initializes servlet and VelocityView used to process requests.
`protected void` `initRequest(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response)` Request and response initialization.
`protected void` `manageResourceNotFound(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response, org.apache.velocity.exception.ResourceNotFoundException e)` Manages the `ResourceNotFoundException` to send an HTTP 404 result when needed.
`protected void` `mergeTemplate(org.apache.velocity.Template template, org.apache.velocity.context.Context context, javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response)` Merge template
`protected void` `mergeTemplate(org.apache.velocity.Template template, org.apache.velocity.context.Context context, javax.servlet.http.HttpServletResponse response)` Deprecated. see {`mergeTemplate(Template, Context, HttpServletRequest, HttpServletResponse)`}
`protected void` `requestCleanup(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response, org.apache.velocity.context.Context context)` Cleanup routine called at the end of the request processing sequence allows a derived class to do resource cleanup or other end of process cycle tasks.
`protected void` `setContentType(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response)` Sets the content type of the response.
`protected void` `setVelocityView(VelocityView view)`

### Methods inherited from class javax.servlet.http.HttpServlet

`doDelete, doHead, doOptions, doPut, doTrace, getLastModified, service, service`

### Methods inherited from class javax.servlet.GenericServlet

`destroy, getInitParameter, getInitParameterNames, getServletConfig, getServletContext, getServletInfo, getServletName, init, log, log`

### Methods inherited from class java.lang.Object

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

### Field Detail

#### BUFFER_OUTPUT_PARAM

    public static final String BUFFER_OUTPUT_PARAM

See Also:
  Constant Field Values

### Constructor Detail

#### VelocityViewServlet

    public VelocityViewServlet()

### Method Detail

#### init

    public void init(javax.servlet.ServletConfig config)
              throws javax.servlet.ServletException

Initializes servlet and VelocityView used to process requests. Called by the servlet container on loading.

Specified by:
  `init` in interface `javax.servlet.Servlet`
Overrides:
  `init` in class `javax.servlet.GenericServlet`
Parameters:
  `config` - servlet configuation
Throws:
  `javax.servlet.ServletException`

#### findInitParameter

    protected String findInitParameter(javax.servlet.ServletConfig config,
                                       String key)

Looks up an init parameter with the specified key in either the ServletConfig or, failing that, in the ServletContext.

Parameters:
  `config` - servlet config
  `key` - parameter key
Returns:
  parameter value or null

#### getVelocityView

    protected VelocityView getVelocityView()

#### setVelocityView

    protected void setVelocityView(VelocityView view)

#### getVelocityProperty

    protected String getVelocityProperty(String name,
                                         String alternate)

#### getLog

    protected org.slf4j.Logger getLog()

#### doGet

    public void doGet(javax.servlet.http.HttpServletRequest request,
                      javax.servlet.http.HttpServletResponse response)
               throws javax.servlet.ServletException,
                      IOException

Handles GET - calls doRequest()

Overrides:
  `doGet` in class `javax.servlet.http.HttpServlet`
Parameters:
  `request` - servlet request
  `response` - servlet response
Throws:
  `javax.servlet.ServletException` - from underlying call
  `IOException` - from underlying call

#### doPost

    public void doPost(javax.servlet.http.HttpServletRequest request,
                       javax.servlet.http.HttpServletResponse response)
                throws javax.servlet.ServletException,
                       IOException

Handle a POST request - calls doRequest()

Overrides:
  `doPost` in class `javax.servlet.http.HttpServlet`
Parameters:
  `request` - servlet request
  `response` - servlet response
Throws:
  `javax.servlet.ServletException` - from underlying call
  `IOException` - from underlying call

#### doRequest

    protected void doRequest(javax.servlet.http.HttpServletRequest request,
                             javax.servlet.http.HttpServletResponse response)
                      throws IOException

Handles with both GET and POST requests

Parameters:
  `request` - HttpServletRequest object containing client request
  `response` - HttpServletResponse object for the response
Throws:
  `IOException` - from underlying processing

#### initRequest

    protected void initRequest(javax.servlet.http.HttpServletRequest request,
                               javax.servlet.http.HttpServletResponse response)
                        throws IOException

Request and response initialization. Default version does only one thing: set request POST parameters encoding to Velocity input encoding.

Parameters:
  `request` - HttpServletRequest object containing client request
  `response` - HttpServletResponse object for the response
Throws:
  `IOException` - if thrown by underlying handling

#### handleRequest

    protected org.apache.velocity.Template handleRequest(javax.servlet.http.HttpServletRequest request,
                                                         javax.servlet.http.HttpServletResponse response,
                                                         org.apache.velocity.context.Context ctx)

This was a common extension point, but now it is usually simpler to override `fillContext(org.apache.velocity.context.Context, javax.servlet.http.HttpServletRequest)` to add custom things to the `Context` or override a `getTemplate(javax.servlet.http.HttpServletRequest, javax.servlet.http.HttpServletResponse)` method to change how `Template`s are retrieved. This is only recommended for more complicated use-cases.

Parameters:
  `request` - client request
  `response` - client response
  `ctx` - VelocityContext to fill
Returns:
  Velocity Template object or null

#### createContext

    protected org.apache.velocity.context.Context createContext(javax.servlet.http.HttpServletRequest request,
                                                                javax.servlet.http.HttpServletResponse response)

Get a configured Velocity context for the current request and response

Parameters:
  `request` - client request
  `response` - client response
Returns:
  configured context

#### fillContext

    protected void fillContext(org.apache.velocity.context.Context context,
                               javax.servlet.http.HttpServletRequest request)

Standard extension point to populate the context with additional entries

Parameters:
  `context` - target context
  `request` - client request

#### setContentType

    protected void setContentType(javax.servlet.http.HttpServletRequest request,
                                  javax.servlet.http.HttpServletResponse response)

Sets the content type of the response. This is available to be overriden by a derived class.

The default implementation is : `response.setContentType(getVelocityView().getDefaultContentType());` where defaultContentType is set to the value of the default.contentType property, or "text/html" if that was not set for the `VelocityView`.

Parameters:
  `request` - servlet request from client
  `response` - servlet reponse to client

#### getTemplate

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

Get a template by client request and response

Parameters:
  `request` - client request
  `response` - client response
Returns:
  found template

#### getTemplate

    protected org.apache.velocity.Template getTemplate(String name)

Get a template by name

Parameters:
  `name` - template name
Returns:
  found template

#### mergeTemplate

    protected void mergeTemplate(org.apache.velocity.Template template,
                                 org.apache.velocity.context.Context context,
                                 javax.servlet.http.HttpServletRequest request,
                                 javax.servlet.http.HttpServletResponse response)
                          throws IOException

Merge template

Parameters:
  `template` - input template
  `context` - Velocity context
  `request` - client request
  `response` - client response
Throws:
  `IOException`

#### getOutputWriter

    protected Writer getOutputWriter(javax.servlet.http.HttpServletRequest request,
                                     javax.servlet.http.HttpServletResponse response)
                              throws IOException

Get the output stream writer to use. If the writer is to be written afterwards to the response writer (as when `org.apache.velocity.tools.bufferOutput` is true), this method must set the `org.apache.velocity.tools.bufferOutput` request attribute to true.

Parameters:
  `request` -
  `response` -
Returns:
Throws:
  `IOException`

#### mergeTemplate

    @Deprecated
    protected void mergeTemplate(org.apache.velocity.Template template,
                                             org.apache.velocity.context.Context context,
                                             javax.servlet.http.HttpServletResponse response)
                                      throws IOException

Deprecated. see {`mergeTemplate(Template, Context, HttpServletRequest, HttpServletResponse)`}
Merge template

Parameters:
  `template` - target template
  `context` - client request
  `response` - client response
Throws:
  `IOException`

#### error

    protected void error(javax.servlet.http.HttpServletRequest request,
                         javax.servlet.http.HttpServletResponse response,
                         Throwable e)

Invoked when there is an error thrown in any part of doRequest() processing.
Default will send a simple HTML response indicating there was a problem.

Parameters:
  `request` - original HttpServletRequest from servlet container.
  `response` - HttpServletResponse object from servlet container.
  `e` - Exception that was thrown by some other part of process.

#### manageResourceNotFound

    protected void manageResourceNotFound(javax.servlet.http.HttpServletRequest request,
                                          javax.servlet.http.HttpServletResponse response,
                                          org.apache.velocity.exception.ResourceNotFoundException e)
                                   throws IOException

Manages the `ResourceNotFoundException` to send an HTTP 404 result when needed.

Parameters:
  `request` - The request object.
  `response` - The response object.
  `e` - The exception to check.
Throws:
  `IOException` - If something goes wrong when sending the HTTP error.

#### requestCleanup

    protected void requestCleanup(javax.servlet.http.HttpServletRequest request,
                                  javax.servlet.http.HttpServletResponse response,
                                  org.apache.velocity.context.Context context)

Cleanup routine called at the end of the request processing sequence allows a derived class to do resource cleanup or other end of process cycle tasks. This default implementation does nothing.

Parameters:
  `request` - servlet request from client
  `response` - servlet response
  `context` - Context that was merged with the requested template