S2Velocity

Project Documentation

Built by Maven

Error handling in S2Velocity

Velocity Tools provides two Servlets and there is different in error handling between the Servlets.

  • in VelocityViewServlet , error message is constructed in servlet itself if Servlet caught exception during handling a template.
  • in VelocityLayoutViewServlet , error messages is constructed with another Velocity template specified in Velocity property file. Servlet puts some attributes about an error situation, and template for error message can use those attributes.

Although in simple use-cases, which has no need to have global layout support, VelocityViewServlet is enough, It is problem that error message is hard to realize for (non-developer) end user.

S2Velocity has error handling capability of VelocityLayoutViewServlet and now error message can be shown in desirable format.

How to Use

web.xml settings

Configuration about error-handling template is done in a file velocity.properties , which is located in web.xml .

web.xml 

        <servlet>
                <servlet-name>velocity</servlet-name>
                <servlet-class>org.seasar.velocity.tools.S2VelocityViewServlet</servlet-class>
                .
                .
                .
                <init-param>
                        <param-name>org.apache.velocity.properties</param-name>
                        <param-value>/WEB-INF/velocity.properties</param-value>
                </init-param>
        </servlet>

As an example above, Velocity property file is /WEB-INF/velocity.properties .

velocity.properties settings

Add a line into velocity.properties as below:

tools.view.servlet.error.template=error.vm

In this case, error.vm is error-handling template.

Write error.vm

error.vm is Velocity template as well as other view template files, so it may be written in HTML. Please note that some part of original view template may be done already, when an error caught in a view template and rendering is forwarded to error.vm. In error.vm, it should not able to set any response headers with $response and so on.

In error.vm, some handy attributes are set by servlet.

  • $error_cause having error cause, in Exception object.
  • $stack_trace having stack-trace in String.
  • $invocation_exception If the error caused in MethodInvocationException , this attribute has the exception object itself, and $error_cause will have wrapped (root-cause) Exception object.