org.apache.velocity.servlet

Class VelocityServlet

public abstract class VelocityServlet extends 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 :
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 $

Field Summary
static StringCONTENT_TYPE
The HTTP content type context key.
static StringdefaultContentType
The default content type, itself defaulting to DEFAULT_CONTENT_TYPE if not configured.
static StringDEFAULT_CONTENT_TYPE
The default content type for the response
static StringDEFAULT_OUTPUT_ENCODING
Encoding for the output stream
protected static StringINIT_PROPS_KEY
This is the string that is looked for when getInitParameter is called (org.apache.velocity.properties).
static StringOLD_INIT_PROPS_KEY
Use of this properties key has been deprecated, and will be removed in Velocity version 1.5.
static StringREQUEST
The context key for the HTTP request object.
static StringRESPONSE
The context key for the HTTP response object.
static SimplePoolwriterPool
Cache of writers
Method Summary
protected StringchooseCharacterEncoding(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 ContextcreateContext(HttpServletRequest request, 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.
voiddoGet(HttpServletRequest request, HttpServletResponse response)
Handles HTTP GET requests by calling VelocityServlet.
voiddoPost(HttpServletRequest request, HttpServletResponse response)
Handles HTTP POST requests by calling VelocityServlet.
protected voiddoRequest(HttpServletRequest request, HttpServletResponse response)
Handles all requests (by default).
protected voiderror(HttpServletRequest request, HttpServletResponse response, Exception cause)
Invoked when there is an error thrown in any part of doRequest() processing.
TemplategetTemplate(String name)
Retrieves the requested template.
TemplategetTemplate(String name, String encoding)
Retrieves the requested template with the specified character encoding.
protected TemplatehandleRequest(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.
protected TemplatehandleRequest(Context ctx)
Implement this method to add your application data to the context, calling the getTemplate() method to produce your return value.
voidinit(ServletConfig config)
Performs initialization of this servlet.
protected voidinitVelocity(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 PropertiesloadConfiguration(ServletConfig config)
Loads the configuration information and returns that information as a Properties, which will be used to initialize the Velocity runtime.
protected voidmergeTemplate(Template template, Context context, HttpServletResponse response)
merges the template with the context.
protected voidrequestCleanup(HttpServletRequest request, HttpServletResponse response, Context context)
A cleanup routine which is called at the end of the VelocityServlet processing sequence, allowing a derived class to do resource cleanup or other end of process cycle tasks.
protected voidsetContentType(HttpServletRequest request, HttpServletResponse response)
Sets the content type of the response, defaulting to defaultContentType if not overriden.

Field Detail

CONTENT_TYPE

public static final String CONTENT_TYPE
The HTTP content type context key.

defaultContentType

private static String defaultContentType
The default content type, itself defaulting to DEFAULT_CONTENT_TYPE if not configured.

DEFAULT_CONTENT_TYPE

public static final String DEFAULT_CONTENT_TYPE
The default content type for the response

DEFAULT_OUTPUT_ENCODING

public static final String DEFAULT_OUTPUT_ENCODING
Encoding for the output stream

INIT_PROPS_KEY

protected static final String INIT_PROPS_KEY
This is the string that is looked for when getInitParameter is called (org.apache.velocity.properties).

OLD_INIT_PROPS_KEY

private static final String OLD_INIT_PROPS_KEY
Use of this properties key has been deprecated, and will be removed in Velocity version 1.5.

REQUEST

public static final String REQUEST
The context key for the HTTP request object.

RESPONSE

public static final String RESPONSE
The context key for the HTTP response object.

writerPool

private static SimplePool writerPool
Cache of writers

Method Detail

chooseCharacterEncoding

protected String chooseCharacterEncoding(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 VelocityServlet 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(HttpServletRequest request, 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

doGet

public void doGet(HttpServletRequest request, HttpServletResponse response)
Handles HTTP GET requests by calling VelocityServlet.

doPost

public void doPost(HttpServletRequest request, HttpServletResponse response)
Handles HTTP POST requests by calling VelocityServlet.

doRequest

protected void doRequest(HttpServletRequest request, HttpServletResponse response)
Handles all requests (by default).

Parameters: request HttpServletRequest object containing client request response HttpServletResponse object for the response

error

protected void error(HttpServletRequest request, HttpServletResponse response, Exception cause)
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.

getTemplate

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

getTemplate

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

Since: Velocity v1.1

handleRequest

protected Template 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 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.

Since: Velocity v1.1

handleRequest

protected Template handleRequest(Context ctx)

Deprecated: Use VelocityServlet

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.

init

public void init(ServletConfig config)
Performs initialization of this servlet. Called by the servlet container on loading.

Parameters: config The servlet configuration to apply.

Throws: ServletException

initVelocity

protected void initVelocity(ServletConfig config)
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.

loadConfiguration

protected Properties loadConfiguration(ServletConfig config)
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: FileNotFoundException if a specified file is not found. IOException I/O problem accessing the specified file, if specified.

mergeTemplate

protected void mergeTemplate(Template template, Context context, HttpServletResponse response)
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

requestCleanup

protected void requestCleanup(HttpServletRequest request, HttpServletResponse response, Context context)
A cleanup routine which is called at the end of the VelocityServlet 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

setContentType

protected void setContentType(HttpServletRequest request, HttpServletResponse response)
Sets the content type of the response, defaulting to defaultContentType if not overriden. Delegates to chooseCharacterEncoding to select the appropriate character encoding.

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

Copyright B) 2002 Apache Software Foundation. All Rights Reserved.