Integrating Spring, Velocity and Tiles

I like Tiles and I heard a lot about Velocity. They seem to serve different purpose and reportedly are easily married together, so I decided to give it a shot and use them both in Spring web app. The integration actually took many hours and was a real rollercoaster during which I learned a lot about all three technologies. Hopefully this post can spare someone this fun and let them focus on business.


When I use tiles, I don’t like the default (?) approach of tiles.xml. I don’t want to put imports of JS & CSS, page title, navigation, body etc. each in its own file like in the snippet below, because that makes me switch between editor windows.

<definition name="hello" template="/WEB-INF/templates/main.jsp">
	<put-attribute name="title" value="Hello" type="string" />
	<put-attribute name="head" value="/WEB-INF/templates/hello-js-and-css.jsp" />
	<put-attribute name="nav" value="/WEB-INF/templates/hello-nav.jsp" />
	<put-attribute name="body" value="/WEB-INF/templates/hello.jsp" />

Obviously I don’t want to put too much detail in tiles.xml, either.

What I really like is having one file per page, assembling the template in one place, such as this piece of JSP:

<tiles:insertTemplate template="template.jsp">
	<tiles:putAttribute name="title" value="Hello" />
	<tiles:putAttribute name="head">
		<script type="text/javascript" src="/js/jQuery.js" />
		<script type="text/javascript" src="/js/hello.js" />
	<tiles:putAttribute name="body">
		<div>Hello, world!</div>

In Velocity, it’s supposed to look like this:

#tiles_insertTemplate({"template": "template.vm"})
	#tiles_putAttribute({"name":"title", "value": "Hello"})#end
		<script type="text/javascript" src="/js/jQuery.js" />
		<script type="text/javascript" src="/js/hello.js" />	
		<div>Hello, world!</div>

However, the docs on integration are really intended for adding some Velocity support to your Tiles-based app, while I wanted quite the opposite: Use Tiles in my rich Velocity app, with full support for spring context, macros etc.


In short, what we’re going to do is:

  1. Use VelocityViewResolver to resolve and render pages
  2. Add support for Tiles macros to this Velocity rendering engine
  3. Extend the Tiles renderer with full support for Velocity, including Spring context, macros etc. Ultimately we’re going to make it use the original Velocity engine created by Spring.

Full source code in form of a minimal, complete web app are at github. For details see below.

Spring & Velocity -> Tiles

For the first step, we define viewResolver and velocityConfig like this:

public VelocityConfig velocityConfig() {
	VelocityConfigurer cfg = new VelocityConfigurer();
	return cfg;

public ViewResolver viewResolver() {
	VelocityViewResolver resolver = new VelocityViewResolver();
	return resolver;

It’s important that we use VelocityToolboxView there, otherwise the tiles directives won’t work.

We also need to put the following in


This adds basic support for Tiles directives to Velocity, but it’s still useless because once Velocity hands rendering over to Tiles, Tiles is unable to render Velocity and would simply ignore it (rendering syntax of #directives to browser.

Tiles -> Velocity

We need to teach Tiles to use Velocity. For this we’re going to need a custom TilesInitializer:

public TilesConfigurer tilesConfigurer() {
	TilesConfigurer cfg = new TilesConfigurer();
	cfg.setTilesInitializer(new VelocityTilesInitializer(velocityConfig()));
	return cfg;
public class VelocityTilesInitializer extends DefaultTilesInitializer {
	private VelocityConfig velocityConfig;

	public VelocityTilesInitializer(VelocityConfig velocityConfig) {
		this.velocityConfig = velocityConfig;

	protected AbstractTilesContainerFactory createContainerFactory(
			TilesApplicationContext context) {
		return new BasicTilesContainerFactory() {

			protected List<TilesRequestContextFactory> getTilesRequestContextFactoriesToBeChained(
					ChainedTilesRequestContextFactory parent) {
				List<TilesRequestContextFactory> factories = super
						factories, parent);
				return factories;

			protected AttributeRenderer createTemplateAttributeRenderer(
					BasicRendererFactory rendererFactory,
					TilesApplicationContext applicationContext,
					TilesRequestContextFactory contextFactory,
					TilesContainer container,
					AttributeEvaluatorFactory attributeEvaluatorFactory) {
				ContextPassingVelocityAttributeRenderer var = new ContextPassingVelocityAttributeRenderer(
				return var;

We’re almost there, but here’s a tricky bit. Normally in lines 31-32 you would put velocityAttributeRenderer. However, this renderer completely ignores the Spring-augmented Velocity context & engine that Tiles received from Velocity. It creates its own VelocityEngine and lets it do the rendering, throwing away all the Spring and tiles directives and context objects.

There is no way to change this behavior in Tiles (which otherwise seems to be an interesting study in design patterns and extensibility). I even created two JIRA issues for it: 541 for forwarding context and 542 for injecting VelocityEngine.

Meanwhile, we have to make do with this workaround (see github for full source):

public class ContextPassingVelocityAttributeRenderer extends
		AbstractTypeDetectingAttributeRenderer {
	// ...

	private VelocityEngine engine;

	public ContextPassingVelocityAttributeRenderer(VelocityEngine engine) {
		this.engine = engine;
	// ...

	public void commit() {
		velocityView = new VelocityView(new TilesApplicationContextJeeConfig());

	public void write(Object value, Attribute attribute,
			TilesRequestContext request) throws IOException {
		if (value != null) {
			if (value instanceof String) {
				InternalContextAdapter adapter = (InternalContextAdapter) ((VelocityTilesRequestContext) request)
				Context context = adapter.getInternalUserContext();
				Template template = velocityView.getTemplate((String) value);
				velocityView.merge(template, context, request.getWriter());
			} else {
				throw new InvalidTemplateException(
						"Cannot render a template that is not a string: "
								+ value.toString());
		} else {
			throw new InvalidTemplateException("Cannot render a null template");
	// ...

It works arounds both of the JIRA issues and lets us accomplish the ultimate goal:

  1. The VelocityEngine injected to VelocityView here is the original VelocityEngine from Spring. Among other things, it supports Spring directives and context-dependent tools.
  2. The TilesRequestContext in write method still contains the original Velocity context created from Spring scaffolding. Standard implementation of VelocityAttributeRenderer simply throws it away. This workaround above extracts the original context and uses it for rendering.


This journey took much more time than I thought. Documentation on such cases is nonexistent, so I spent hours debugging, reading source code, experimenting, praying and cursing. It was even more fun as I had close to zero knowledge of internals of Spring view resolution and rendering engine, as well as Tiles and Velocity.

It’s quite satisfying since I learned a ton about all those technologies and eventually was able to resolve it in a fairly elegant way. But it was also a frustrating and time-consuming riddle and I hope this post spares someone some trouble.

Update – Velocity Tools

A while later I discovered this solution does not support Velocity Tools property. Here’s how to add it: Spring & Velocity Tools.

2 thoughts on “Integrating Spring, Velocity and Tiles

  1. This post was very helpful. Thanks. I am facing issue where request is being forwarded instead of getting included. So after lot of debugging found out that ServletTilesRequestContext is being used instead of VelocityTilesRequestContext and ServletTilesRequestContext does forward instead of include. When request is forwarded spring says cant find mapping for path – /abc.vm.

    Here is my configuration –
    public ViewResolver viewResolver() {
    UrlBasedViewResolver resolver = new UrlBasedViewResolver();
    return resolver;
    //velocity + tiles initializer
    public VelocityTilesInitializer velocityTilesInitializer(){
    VelocityTilesInitializer initializer = new VelocityTilesInitializer();
    List defs = new ArrayList();

    return initializer;

    public TilesConfigurer tilesConfigurer(){
    TilesConfigurer tilesConfigurer = new TilesConfigurer();
    return tilesConfigurer;

  2. Hi,

    I am trying to use Spring tiles with Velocity. but i got some parse Exception. when i run our app it look like below…
    org.springframework.core.NestedIOException: Could not load Velocity template for URL [hello_velocity.vm]; nested exception is org.apache.velocity.exception.ParseErrorException: Encountered “#end\r\n” at line 2, column 64 of hello_velocity.vm
    Was expecting one of:
    “(” …

    “##” …
    “\\\\” …
    “\\” …

    “*#” …
    “*#” …

    “{” …
    “}” …

    at org.springframework.web.servlet.view.velocity.VelocityView.checkResource(
    at org.springframework.web.servlet.view.UrlBasedViewResolver.loadView(
    at org.springframework.web.servlet.view.AbstractCachingViewResolver.createView(
    at org.springframework.web.servlet.view.UrlBasedViewResolver.createView(
    at org.springframework.web.servlet.view.AbstractCachingViewResolver.resolveViewName(
    at org.springframework.web.servlet.DispatcherServlet.resolveViewName(
    at org.springframework.web.servlet.DispatcherServlet.render(
    at org.springframework.web.servlet.DispatcherServlet.doDispatch(
    at org.springframework.web.servlet.DispatcherServlet.doService(
    at org.springframework.web.servlet.FrameworkServlet.processRequest(
    at org.springframework.web.servlet.FrameworkServlet.doGet(
    at javax.servlet.http.HttpServlet.service(
    at javax.servlet.http.HttpServlet.service(
    at org.apache.catalina.core.ApplicationFilterChain.internalDoFilter(
    at org.apache.catalina.core.ApplicationFilterChain.doFilter(
    at org.apache.catalina.core.StandardWrapperValve.invoke(
    at org.apache.catalina.core.StandardContextValve.invoke(
    at org.apache.catalina.core.StandardHostValve.invoke(
    at org.apache.catalina.valves.ErrorReportValve.invoke(
    at org.apache.catalina.core.StandardEngineValve.invoke(
    at org.apache.catalina.connector.CoyoteAdapter.service(
    at org.apache.coyote.http11.Http11AprProcessor.process(
    at org.apache.coyote.http11.Http11AprProtocol$Http11ConnectionHandler.process(
    at Source)
    Caused by: org.apache.velocity.exception.ParseErrorException: Encountered “#end\r\n” at line 2, column 64 of hello_velocity.vm
    Was expecting one of:
    “(” …

    “##” …
    “\\\\” …
    “\\” …

    “*#” …
    “*#” …

    “{” …
    “}” …

    at org.apache.velocity.Template.process(
    at org.apache.velocity.runtime.resource.ResourceManagerImpl.loadResource(
    at org.apache.velocity.runtime.resource.ResourceManagerImpl.getResource(
    at org.apache.velocity.runtime.RuntimeInstance.getTemplate(
    at org.apache.velocity.runtime.RuntimeInstance.getTemplate(
    at org.springframework.web.servlet.view.velocity.VelocityView.getTemplate(
    at org.springframework.web.servlet.view.velocity.VelocityView.checkResource(
    … 24 more

    So any body tell me where is problem in my application

Leave a Reply

Your email address will not be published. Required fields are marked *

Spam protection by WP Captcha-Free