protected String chooseCharacterEncoding(HttpServletRequest request) 
{
        return RuntimeSingleton.getString(RuntimeConstants.OUTPUT_ENCODING,
                                          DEFAULT_OUTPUT_ENCODING);
}

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.

 protected Context createContext(HttpServletRequest request,
    HttpServletResponse response) 
{
        /*
         *   create a new context
         */
        VelocityContext context = new VelocityContext();
        /*
         *   put the request/response objects into the context
         *   wrap the HttpServletRequest to solve the introspection
         *   problems
         */
        context.put( REQUEST,  request );
        context.put( RESPONSE, response );
        return context;
}

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.

 public  void doGet(HttpServletRequest request,
    HttpServletResponse response) throws IOException, ServletException 
{
        doRequest(request, response);
}

Handles HTTP GET requests by calling #doRequest(HttpServletRequest, HttpServletResponse) .

 public  void doPost(HttpServletRequest request,
    HttpServletResponse response) throws IOException, ServletException 
{
        doRequest(request, response);
}

Handles HTTP POST requests by calling #doRequest(HttpServletRequest, HttpServletResponse) .

 protected  void doRequest(HttpServletRequest request,
    HttpServletResponse response) throws IOException, ServletException 
{
        Context context = null;
        try
        {
            /*
             *  first, get a context
             */
            context = createContext( request, response );
            /*
             *   set the content type
             */
            setContentType( request, response );
            /*
             *  let someone handle the request
             */
            Template template = handleRequest( request, response, context );
            /*
             *  bail if we can't find the template
             */
            if ( template == null )
            {
                return;
            }
            /*
             *  now merge it
             */
            mergeTemplate( template, context, response );
        }
        catch (Exception e)
        {
            /*
             *  call the error handler to let the derived class
             *  do something useful with this failure.
             */
            error( request, response, e);
        }
        finally
        {
            /*
             *  call cleanup routine to let a derived class do some cleanup
             */
            requestCleanup( request, response, context );
        }
}

Handles all requests (by default).

 protected  void error(HttpServletRequest request,
    HttpServletResponse response,
    Exception cause) throws IOException, ServletException 
{
        StringBuffer html = new StringBuffer();
        html.append("< html >");
        html.append("< title >Error< /title >");
        html.append("< body bgcolor=\"#ffffff\" >");
        html.append("< h2 >VelocityServlet: Error processing the template< /h2 >");
        html.append("< pre >");
        String why = cause.getMessage();
        if (why != null && why.trim().length()  > 0)
        {
            html.append(why);
            html.append("< br >");
        }
        StringWriter sw = new StringWriter();
        cause.printStackTrace( new PrintWriter( sw ) );
        html.append( sw.toString()  );
        html.append("< /pre >");
        html.append("< /body >");
        html.append("< /html >");
        response.getOutputStream().print( html.toString() );
}

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.

 public Template getTemplate(String name) throws Exception, ResourceNotFoundException, ParseErrorException 
{
        return RuntimeSingleton.getTemplate(name);
}

Retrieves the requested template.

 public Template getTemplate(String name,
    String encoding) throws Exception, ResourceNotFoundException, ParseErrorException 
{
        return RuntimeSingleton.getTemplate( name, encoding );
}

Retrieves the requested template with the specified character encoding.

 protected Template handleRequest(Context ctx) throws Exception 
{
        throw new Exception ("You must override VelocityServlet.handleRequest( Context) "
                             + " or VelocityServlet.handleRequest( HttpServletRequest, "
                             + " HttpServletResponse, Context)" );
}

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.

 protected Template handleRequest(HttpServletRequest request,
    HttpServletResponse response,
    Context ctx) throws Exception 
{
        /*
         * invoke handleRequest
         */
        Template t =  handleRequest( ctx );
        /*
         *  if it returns null, this is the 'old' deprecated
         *  way, and we want to mimic the behavior for a little
         *  while anyway
         */
        if (t == null)
        {
            throw new Exception ("handleRequest(Context) returned null - no template selected!" );
        }
        return t;
}

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.

 public  void init(ServletConfig config) throws ServletException 
{
                               
        super.init( config );
        /*
         *  do whatever we have to do to init Velocity
         */
        initVelocity( config );
        /*
         *  Now that Velocity is initialized, cache some config.
         */
        VelocityServlet.defaultContentType =
                RuntimeSingleton.getString(CONTENT_TYPE, DEFAULT_CONTENT_TYPE);
}

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

 protected  void initVelocity(ServletConfig config) throws ServletException 
{
        try
        {
            /*
             *  call the overridable method to allow the
             *  derived classes a shot at altering the configuration
             *  before initializing Runtime
             */
            Properties props = loadConfiguration( config );
            Velocity.init( props );
        }
        catch( Exception e )
        {
            throw new ServletException("Error initializing Velocity: " + e, e);
        }
}

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.

 protected Properties loadConfiguration(ServletConfig config) throws IOException, FileNotFoundException 
{
        // This is a little overly complex because of legacy support
        // for the initialization properties key "properties".
        // References to OLD_INIT_PROPS_KEY should be removed at
        // Velocity version 1.5.
        String propsFile = config.getInitParameter(INIT_PROPS_KEY);
        if (propsFile == null || propsFile.length() == 0)
        {
            ServletContext sc = config.getServletContext();
            propsFile = config.getInitParameter(OLD_INIT_PROPS_KEY);
            if (propsFile == null || propsFile.length() == 0)
            {
                propsFile = sc.getInitParameter(INIT_PROPS_KEY);
                if (propsFile == null || propsFile.length() == 0)
                {
                    propsFile = sc.getInitParameter(OLD_INIT_PROPS_KEY);
                    if (propsFile != null && propsFile.length()  > 0)
                    {
                        sc.log("Use of the properties initialization " +
                               "parameter '" + OLD_INIT_PROPS_KEY + "' has " +
                               "been deprecated by '" + INIT_PROPS_KEY + '\'");
                    }
                }
            }
            else
            {
                sc.log("Use of the properties initialization parameter '" +
                       OLD_INIT_PROPS_KEY + "' has been deprecated by '" +
                       INIT_PROPS_KEY + '\'");
            }
        }
        /*
         * This will attempt to find the location of the properties
         * file from the relative path to the WAR archive (ie:
         * docroot). Since JServ returns null for getRealPath()
         * because it was never implemented correctly, then we know we
         * will not have an issue with using it this way. I don't know
         * if this will break other servlet engines, but it probably
         * shouldn't since WAR files are the future anyways.
         */
        Properties p = new Properties();
        if ( propsFile != null )
        {
            p.load(getServletContext().getResourceAsStream(propsFile));
        }
        return p;
}

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.

 protected  void mergeTemplate(Template template,
    Context context,
    HttpServletResponse response) throws Exception, IOException, MethodInvocationException, ResourceNotFoundException, UnsupportedEncodingException, ParseErrorException 
{
        ServletOutputStream output = response.getOutputStream();
        VelocityWriter vw = null;
        // ASSUMPTION: response.setContentType() has been called.
        String encoding = response.getCharacterEncoding();
        try
        {
            vw = (VelocityWriter) writerPool.get();
            if (vw == null)
            {
                vw = new VelocityWriter(new OutputStreamWriter(output,
                                                               encoding),
                                        4 * 1024, true);
            }
            else
            {
                vw.recycle(new OutputStreamWriter(output, encoding));
            }
            template.merge(context, vw);
        }
        finally
        {
            if (vw != null)
            {
                try
                {
                    /*
                     *  flush and put back into the pool
                     *  don't close to allow us to play
                     *  nicely with others.
                     */
                    vw.flush();
                }
                catch (IOException e)
                {
                    // do nothing
                }
                /*
                 * Clear the VelocityWriter's reference to its
                 * internal OutputStreamWriter to allow the latter
                 * to be GC'd while vw is pooled.
                 */
                vw.recycle(null);
                writerPool.put(vw);
            }
        }
}

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 :)

 protected  void requestCleanup(HttpServletRequest request,
    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(HttpServletRequest request,
    HttpServletResponse response) 
{
        String contentType = VelocityServlet.defaultContentType;
        int index = contentType.lastIndexOf(';") + 1;
        if (index < = 0 || (index <  contentType.length() &&
                           contentType.indexOf("charset", index) == -1))
        {
            // Append the character encoding which we'd like to use.
            String encoding = chooseCharacterEncoding(request);
            //RuntimeSingleton.debug("Chose output encoding of '" +
            //                       encoding + '\'');
            if (!DEFAULT_OUTPUT_ENCODING.equalsIgnoreCase(encoding))
            {
                contentType += "; charset=" + encoding;
            }
        }
        response.setContentType(contentType);
        //RuntimeSingleton.debug("Response Content-Type set to '" +
        //                       contentType + '\'');
}

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