Google Summer of Code 2007 Proposal


Apache Velocity Macro Improvement


Supun Madhushanka Kamburugamuva



Velocity is a template engine written in Java. A very important feature of the velocity template language (VTL) is the ability to define Velocimacros. Velocimacros enable template writers to easily re-use the code. However, the current macro implementation requires some improvements and fixes.

A common use of Velocimacros would be to define them in separate files and include them with the #parse directive. The other way to include macros defined in separate files would be the Java API.However, both methods are not supported in the current implementation.

Another problem with Velocimacros is the recursive calls. When a Velocimacro calls itself recursively without meeting stopping conditions, the current implementation does not work properly. One way to solve this problem is to introduce a maximum recursion depth for Velocimacros.

If the Velocimacros can be overloaded with different arguments it will be very user friendly. This allows more freedom in writing Velocimacros. This is another improvement to be made.

This project will mainly focus on restructuring and adding new features to the existing Velocity macro handling code, to solve the above issues. This process inevitably involves dependencies to the other aspects of Velocity as well. So the project requires a good in depth understanding of the overall Velocity structure.


1.Improved macro handling capability of Velocity. This will include adding new features and functionality to the macro handling code. The new features will include the following:

Ability to include macros defined in separate files via the #parse directive and through the Java API

Ability to overload macros with different arguments

Adding maximum recursive depths to the macros

Ability to pass expressions to the macros as arguments

2.Complete test suite for macro handling in Velocity, including all the new features and previous features. .

3.Appropriate development documentation for continuation of the project and user documentation.

The above features are those that will be addressed at the moment. Any other requirements or features that arise during the development of the project will also be added.

Project details

Velocity is a template engine written in Java. It has its own template language called Velocity Template Language (VTL). This is a fully fledged language that supports many features like loops, conditional processing, etc. An important area in this language is Velocimacros. Velocimacros provides a mechanism for re-using code.

1. Including Velocimacros written in separate files

With the #parse directive With the current implementation of Velocity, if a user includes a Velocimacro defined in a separate file via the #parse directive, the included macro does not work properly. Most of these issues are due to the way velocity stores macros. Velocimacros have two scopes for macros. They are local and global scopes. This is controlled by the property velocimacro.permissions.allow.inline.local.scope which can be True or False. If the value is True and user includes a macro file via the #parse directive, the macro is local to the file that specifies it and it is not available to the template that imports it.

If the value is False, the macro is available globally to all the templates. This is not supported in the current implementation. Supporting it would not be a wise decision because there is a possibility of another template defining a macro with the same name and loading it to the global space. Both values of this property do not solve the problem. So we have to come up with a new way of executing macros.

Using the Java API Velocity currently allows the users to specify a set of global macros. However, the user may want to specify the macros on a per template file basis. This allows more freedom in writing macros and provides a logical separation between macro files.

2. Argument overloading

The current implementation does not support argument overloading for macros. Argument overloading allows users to define macros with the same name but with different number of arguments. This allows a user to define logically equivalent operations that take different number of arguments in a consistent way.

3. Maximum recursive depths

Velocimacros allow recursive calls and it enables users to write code much easily in some circumstances. Badly written code can lead to stack overflows by not specifying stop conditions. One way to overcome this issue would be to use a property specifying maximum recursive depths. If we can specify the maximum recursive depths in a per macro basis, that would be a better solution. Else, we can combine both these solutions.

4. Defining Velocimacros that take body as a argument This feature allows the user to pass the body of the macro in to the macro as a argument. Below is a simple example.

Macro definition: #macro( takeBody $e ) < "$e">#body</$e> #end

Macro use: #takeBody(‘Sample’) Body #end

Result: <Sample>Body</Sample>

All the improvements to the code should not destroy the backward compatibility of the Velocity engine, and it shouldn’t affect the Velocity engines template cashing mechanism. Another very important issue is that performance of the Velocity engine. All the improvements should not affect the performance as well. These are three challenging issues that need to be addressed with care.

Project Plan

The project will be done according to open source software development practices. All the design decisions and problems will be discussed in the mailing lists.

Initial Period - April 9th May 28th

There is an initial period after accepting the proposals for the GSOC projects. This period will be spent getting familiarized with the project. I have good hands-on experience with Velocity (I have used Velocity for a project at the university). Some areas of the Velocity are not very clear to me at the moment. This period can be used to clarify these issues. Writing sample applications that use Velocity is the best way to do this. At the same time, I would like to get familiarized with the existing code of the Velocity and how it works internally.

Openly discussing the design of the improvements and implementation details in the mailing lists is another important thing to do during this period.

Coding Period

May 28th June 25th

Add the capability to handle Velocimacros defined in separate files.

June 25th July 2nd

Add maximum recursive depths for Velocimacros.

July 2nd July 23rd

Implement the argument overloading for Velocimacros

July 23rd August 6th

Implement the expression passing as arguments to the Velocimacros.

August 6th August 20th

Prepare necessary documentation and finalizing the project.

Finally my objective is to provide a complete solution to the improvements required by Velocimacros


I’m a Computer Science and Engineering undergraduate at the University of Moratuwa, Sri Lanka. I have been actively involved in the Apache Web Services Axis2C project for more than five months now. I received the Apache Axis2 committership for implementing IIS support for Axis2C. I got the chance to work on many aspects of the Axis2C project. Before I started working on Axis2C directly, I wrote a client com application for Axis2c for use in JScript.

I think, during the past few months I have gathered a reasonable amount of experience and knowledge about open source projects. Before I started contributing to open source projects, I have used open source products for my project work- especially ASF products. I have used Apache Velocity for source code generation in my 3rd year software project. The project was to generate starter kits for software projects (including source code) by gathering information about projects.

I would like to continue my contribution to open source projects (especially ASF) in the future, and I consider this as a great opportunity to do so..