VelocityServlet (Velocity 1.4 API)
Keywords: org.apache.velocity.servlet.VelocityServlet class

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## org.apache.velocity.servlet
Class VelocityServlet

    java.lang.Object
      javax.servlet.GenericServlet
          javax.servlet.http.HttpServlet
              org.apache.velocity.servlet.VelocityServlet

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

Direct Known Subclasses:
  VelocityServletTest.MockVelocityServlet

public abstract class VelocityServlet
extends javax.servlet.http.HttpServlet

Base class which simplifies the use of Velocity with Servlets. Extend this class, implement the `handleRequest()` method, and add your data to the context. Then call `getTemplate("myTemplate.wm")`. This class puts some things into the context object that you should be aware of:

     "req" - The HttpServletRequest object
     "res" - The HttpServletResponse object

There are other methods you can override to access, alter or control any part of the request processing chain. Please see the javadocs for more information on :

- loadConfiguration() : for setting up the Velocity runtime
- createContext() : for creating and loading the Context
- setContentType() : for changing the content type on a request by request basis
- handleRequest() : you must implement this
- mergeTemplate() : the template rendering process
- requestCleanup() : post rendering resource or other cleanup
- error() : error handling

If you put a contentType object into the context within either your serlvet or within your template, then that will be used to override the default content type specified in the properties file. "contentType" - The value for the Content-Type: header

Author:
  Dave Bryson, Jon S. Stevens, Geir Magnusson Jr., Kent Johnson, Daniel Rall $Id: VelocityServlet.java,v 1.52.4.1 2004/03/03 23:23:03 geirm Exp $
See Also:
  Serialized Form

Field Summary
`static java.lang.String` | `CONTENT_TYPE` 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` Encoding for the output stream
`private static java.lang.String` | `defaultContentType` The default content type, itself defaulting to `DEFAULT_CONTENT_TYPE` if not configured.
`protected static java.lang.String` | `INIT_PROPS_KEY` This is the string that is looked for when getInitParameter is called (`org.apache.velocity.properties`).
`private static java.lang.String` | `OLD_INIT_PROPS_KEY` Use of this properties key has been deprecated, and will be removed in Velocity version 1.5.
`static java.lang.String` | `REQUEST` The context key for the HTTP request object.
`static java.lang.String` | `RESPONSE` The context key for the HTTP response object.
`private static SimplePool` | `writerPool` Cache of writers

Fields inherited from class javax.servlet.http.HttpServlet
``

Fields inherited from class javax.servlet.GenericServlet
``

Constructor Summary
`VelocityServlet()`

Method Summary
`protected java.lang.String` | `chooseCharacterEncoding(javax.servlet.http.HttpServletRequest request)` Chooses the output character encoding to be used as the value for the "charset=" portion of the HTTP Content-Type header (and thus returned by `response.getCharacterEncoding()`).
`protected Context` | `createContext(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response)` Returns a context suitable to pass to the handleRequest() method Default implementation will create a VelocityContext object, put the HttpServletRequest and HttpServletResponse into the context accessable via the keys VelocityServlet.REQUEST and VelocityServlet.RESPONSE, respectively.
`void` | `doGet(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response)` Handles HTTP `GET` requests by calling `#doRequest()`.
`void` | `doPost(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response)` Handles HTTP `POST` requests by calling `#doRequest()`.
`protected void` | `doRequest(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response)` Handles all requests (by default).
`protected void` | `error(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response, java.lang.Exception cause)` Invoked when there is an error thrown in any part of doRequest() processing.
`Template` | `getTemplate(java.lang.String name)` Retrieves the requested template.
`Template` | `getTemplate(java.lang.String name, java.lang.String encoding)` Retrieves the requested template with the specified character encoding.
`protected Template` | `handleRequest(Context ctx)` Deprecated. Use `handleRequest( HttpServletRequest request, HttpServletResponse response, Context ctx )`
`protected Template` | `handleRequest(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response, Context ctx)` Implement this method to add your application data to the context, calling the `getTemplate()` method to produce your return value.
`void` | `init(javax.servlet.ServletConfig config)` Performs initialization of this servlet.
`protected void` | `initVelocity(javax.servlet.ServletConfig config)` Initializes the Velocity runtime, first calling loadConfiguration(ServletConvig) to get a java.util.Properties of configuration information and then calling Velocity.init().
`protected java.util.Properties` | `loadConfiguration(javax.servlet.ServletConfig config)` Loads the configuration information and returns that information as a Properties, which will be used to initialize the Velocity runtime.
`protected void` | `mergeTemplate(Template template, Context context, javax.servlet.http.HttpServletResponse response)` merges the template with the context.
`protected void` | `requestCleanup(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response, Context context)` A cleanup routine which is called at the end of the `doRequest(HttpServletRequest, HttpServletResponse)` processing sequence, allowing 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, defaulting to `defaultContentType` if not overriden.

Methods inherited from class javax.servlet.http.HttpServlet
`doDelete, 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

### REQUEST

    public static final java.lang.String REQUEST

  The context key for the HTTP request object.

  See Also:
    Constant Field Values

### RESPONSE

    public static final java.lang.String RESPONSE

  The context key for the HTTP response object.

  See Also:
    Constant Field Values

### CONTENT_TYPE

    public static final java.lang.String CONTENT_TYPE

  The HTTP content type context key.

  See Also:
    Constant Field Values

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

  Encoding for the output stream

  See Also:
    Constant Field Values

### defaultContentType

    private static java.lang.String defaultContentType

  The default content type, itself defaulting to `DEFAULT_CONTENT_TYPE` if not configured.

### INIT_PROPS_KEY

    protected static final java.lang.String INIT_PROPS_KEY

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

  See Also:
    Constant Field Values

### OLD_INIT_PROPS_KEY

    private static final java.lang.String OLD_INIT_PROPS_KEY

  Use of this properties key has been deprecated, and will be removed in Velocity version 1.5.

  See Also:
    Constant Field Values

### writerPool

    private static SimplePool writerPool

  Cache of writers

Constructor Detail

### VelocityServlet

    public VelocityServlet()

Method Detail

### init

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

  Performs initialization of this servlet. Called by the servlet container on loading.

  Parameters:
    `config` - The servlet configuration to apply.
  Throws:
    `javax.servlet.ServletException`

### initVelocity

    protected void initVelocity(javax.servlet.ServletConfig config)
                         throws javax.servlet.ServletException

  Initializes the Velocity runtime, first calling loadConfiguration(ServletConvig) to get a java.util.Properties of configuration information and then calling Velocity.init(). Override this to do anything to the environment before the initialization of the singelton takes place, or to initialize the singleton in other ways.

  Throws:
    `javax.servlet.ServletException`

### loadConfiguration

    protected java.util.Properties loadConfiguration(javax.servlet.ServletConfig config)
                                              throws java.io.IOException,
                                                     java.io.FileNotFoundException

  Loads the configuration information and returns that information as a Properties, which will be used to initialize the Velocity runtime.
  Currently, this method gets the initialization parameter VelocityServlet.INIT_PROPS_KEY, which should be a file containing the configuration information.
  To configure your Servlet Spec 2.2 compliant servlet runner to pass this to you, put the following in your WEB-INF/web.xml file

          <servlet>
            <servlet-name> YourServlet </servlet-name>
            <servlet-class> your.package.YourServlet </servlet-class>
            <init-param>
               <param-name> org.apache.velocity.properties </param-name>
               <param-value> velocity.properties </param-value>
            </init-param>
          </servlet>

  Alternately, if you wish to configure an entire context in this fashion, you may use the following:

          <context-param>
             <param-name> org.apache.velocity.properties </param-name>
             <param-value> velocity.properties </param-value>
             <description> Path to Velocity configuration </description>
          </context-param>

  Derived classes may do the same, or take advantage of this code to do the loading for them via :

            Properties p = super.loadConfiguration( config );

  and then add or modify the configuration values from the file.

  Parameters:
    `config` - ServletConfig passed to the servlets init() function Can be used to access the real path via ServletContext (hint)
  Returns:
    java.util.Properties loaded with configuration values to be used to initialize the Velocity runtime.
  Throws:
    `java.io.FileNotFoundException` - if a specified file is not found.
    `java.io.IOException` - I/O problem accessing the specified file, if specified.

### doGet

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

  Handles HTTP `GET` requests by calling `#doRequest()`.

  Throws:
    `javax.servlet.ServletException`
    `java.io.IOException`

### doPost

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

  Handles HTTP `POST` requests by calling `#doRequest()`.

  Throws:
    `javax.servlet.ServletException`
    `java.io.IOException`

### doRequest

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

  Handles all requests (by default).

  Parameters:
    `request` - HttpServletRequest object containing client request
    `response` - HttpServletResponse object for the response
  Throws:
    `javax.servlet.ServletException`
    `java.io.IOException`

### requestCleanup

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

  A cleanup routine which is called at the end of the `doRequest(HttpServletRequest, HttpServletResponse)` processing sequence, allowing a derived class to do resource cleanup or other end of process cycle tasks.

  Parameters:
    `request` - servlet request from client
    `response` - servlet reponse
    `context` - context created by the createContext() method

### mergeTemplate

    protected void mergeTemplate(Template template,
                                 Context context,
                                 javax.servlet.http.HttpServletResponse response)
                          throws ResourceNotFoundException,
                                 ParseErrorException,
                                 MethodInvocationException,
                                 java.io.IOException,
                                 java.io.UnsupportedEncodingException,
                                 java.lang.Exception

  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 object returned by the handleRequest() method
    `context` - context created by the createContext() method
    `response` - servlet reponse (use this to get the output stream or Writer
  Throws:
    `ResourceNotFoundException`
    `ParseErrorException`
    `MethodInvocationException`
    `java.io.IOException`
    `java.io.UnsupportedEncodingException`
    `java.lang.Exception`

### setContentType

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

  Sets the content type of the response, defaulting to `defaultContentType` if not overriden. Delegates to `chooseCharacterEncoding(HttpServletRequest)` to select the appropriate character encoding.

  Parameters:
    `request` - The servlet request from the client.
    `response` - The servlet reponse to the client.

### chooseCharacterEncoding

    protected java.lang.String chooseCharacterEncoding(javax.servlet.http.HttpServletRequest request)

  Chooses the output character encoding to be used as the value for the "charset=" portion of the HTTP Content-Type header (and thus returned by `response.getCharacterEncoding()`). Called by `setContentType(HttpServletRequest, HttpServletResponse)` if an encoding isn't already specified by Content-Type. By default, chooses the value of RuntimeSingleton's `output.encoding` property.

  Parameters:
    `request` - The servlet request from the client.

### createContext

    protected Context createContext(javax.servlet.http.HttpServletRequest request,
                                    javax.servlet.http.HttpServletResponse response)

  Returns a context suitable to pass to the handleRequest() method
  Default implementation will create a VelocityContext object, put the HttpServletRequest and HttpServletResponse into the context accessable via the keys VelocityServlet.REQUEST and VelocityServlet.RESPONSE, respectively.

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

### getTemplate

    public Template getTemplate(java.lang.String name)
                         throws ResourceNotFoundException,
                                ParseErrorException,
                                java.lang.Exception

  Retrieves the requested template.

  Parameters:
    `name` - The file name of the template to retrieve relative to the template root.
  Returns:
    The requested template.
  Throws:
    `ResourceNotFoundException` - if template not found from any available source.
    `ParseErrorException` - if template cannot be parsed due to syntax (or other) error.
    `java.lang.Exception` - if an error occurs in template initialization

### getTemplate

    public Template getTemplate(java.lang.String name,
                                java.lang.String encoding)
                         throws ResourceNotFoundException,
                                ParseErrorException,
                                java.lang.Exception

  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:
    `ResourceNotFoundException` - if template not found from any available source.
    `ParseErrorException` - if template cannot be parsed due to syntax (or other) error.
    `java.lang.Exception` - if an error occurs in template initialization
  Since:
    Velocity v1.1

### handleRequest

    protected Template handleRequest(javax.servlet.http.HttpServletRequest request,
                                     javax.servlet.http.HttpServletResponse response,
                                     Context ctx)
                              throws java.lang.Exception

  Implement this method to add your application data to the context, calling the `getTemplate()` method to produce your return value.
  In the event of a problem, you may handle the request directly and return `null` or throw a more meaningful exception for the error handler to catch.

  Parameters:
    `request` - servlet request from client
    `response` - servlet reponse
    `ctx` - The context to add your data to.
  Returns:
    The template to merge with your context or null, indicating that you handled the processing.
  Throws:
    `java.lang.Exception`
  Since:
    Velocity v1.1

### handleRequest

    protected Template handleRequest(Context ctx)
                              throws java.lang.Exception

  Deprecated. Use `handleRequest( HttpServletRequest request, HttpServletResponse response, Context ctx )`

  Implement this method to add your application data to the context, calling the `getTemplate()` method to produce your return value.
  In the event of a problem, you may simple return `null` or throw a more meaningful exception.

  Parameters:
    `ctx` - The context to add your data to.
  Returns:
    The template to merge with your context.
  Throws:
    `java.lang.Exception`

### error

    protected void error(javax.servlet.http.HttpServletRequest request,
                         javax.servlet.http.HttpServletResponse response,
                         java.lang.Exception cause)
                  throws javax.servlet.ServletException,
                         java.io.IOException

  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.
    `cause` - Exception that was thrown by some other part of process.
  Throws:
    `javax.servlet.ServletException`
    `java.io.IOException`

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright © 2002 Apache Software Foundation. All Rights Reserved.