WE05 Hacking Velocity

Hacking Velocity – ApacheCon 2004

• What is Velocity • Velocity Tools • Custom Directives • Custom Resourceloaders • Custom Introspector • Adding Event Handlers • Modifying Velocity Syntax

Presenter Contact Info:

Will Glass-Husain Menlo Park, California USA

[email protected] + 1 415 440-7500

• A templating engine that can generate any type of text output, including HTML, email, SQL, or Java source code. • Based on a "pull" approach in which a text file includes "References" to data objects that are pulled from a provided "Context".

$Date Date Order Dear $Contact.FirstName $Contact.LastName, Contact Thank you for your recent purchase of $Order.ProductName. The cost of the item was $Order.TotalCost#if($Order.Tax > 0) including a tax of $Order.TaxRate%#end.

Sincerely, November 17, 2004 Biggest and Best Book Merchants, Inc. Dear Jennifer Glass,

Thank you for your recent purchase of Alice in Wonderland, Annotated Edition. The cost of the item was $29.95.

Sincerely, Biggest and Best Book Merchants, Inc.

• References – References objects from the Velocity context. Starts with a "$". – Can have Properties or Methods – Common practice is to provide two types: data objects (with properties) and "tools" (with methods). – Examples: • $contact.FirstName • $format("$#,##0.00",$order.price)

• Directives – Control statements. Starts with a "#" – Example block directive: • #if ($columncount > 0) display a table #end – Example line directive: • #include('header.vm')

Load a Template From a File VelocityEngine ve = new VelocityEngine(); ve.setProperty("file.resource.loader.path","templates"); ve.init();

Context c = new VelocityContext(); c.add("order",order); c.add("contact",contact);

Template t1 = ve.getTemplate("inputfile.vm"); StringWriter writer = new StringWriter(); t1.merge(c,writer); String result = writer.toString();

Evaluate a Template stored as a String VelocityEngine ve = new VelocityEngine(); ve.init();

Context c = new VelocityContext(). c.add("order",order); c.add("contact",contact);

StringWriter writer = new StringWriter(); ve.evaluate(c,writer,"velocity",inputstring); String result = writer.toString()

November 17, 2004 (c) 2004 Will Glass-Husain. Non-commercial redistribution permitted freely. 4 Improve Productivity with Velocity-Tools from the web site: http://jakarta.apache.org/velocity/tools/index.html

VelocityTools is a collection of Velocity subprojects with a common goal of creating tools and infrastructure for building both web and non-web applications using the Velocity template engine.

• GenericTools – GenericTools is a group of reuseable and documented tools that can be added to a Velocity context. A tool is simply a class which can perform various tasks when made available to the Velocity engine. Most tools are optimized for use with an automatically managed toolbox (see VelocityViewServlet).

• VelocityView – VelocityView contains a standalone servlet (VelocityViewServlet) which can render templates for web applications. – Also included is a Toolbox Manager which can automatically make "view tools" and data available to the templates. Any class with public methods can be used as a tool in the template. – VelocityLayoutServlet is an extension of the basic VelocityViewServlet that can render screen content into common layout templates.

• VelocityStruts – VelocityStruts is a set of tools for using the Velocity template engine as the view layer for a web application built upon the Jakarta Struts framework. – This work leverages the VelocityViewServlet and additional tools which make it easy to integrate the Velocity with Struts. Several example hybrid applications are included.

Generic Tools VelocityView (web) Tools • DateTool • AbstractSearchTool • IteratorTool • CookieTool • MathTool • ImportTool • NumberTool • LinkTool • RenderTool • ParameterParser • ViewRenderTool

Using a Tool

Context c = new VelocityContext(); c.add("date",new DateTool());

Template t1 = ve.getTemplate("inputfile.vm"); StringWriter writer = new StringWriter(); t1.merge(c,writer); String result = writer.toString();

• Quick and easy way to build a web app. • Serves Velocity pages just like HTM or JSP files. • Tools are automatically placed in the Velocity context according to "toolbox.xml" config file. Excerpt:

math application org.apache.velocity.tools.generic.MathTool

• Any tool that has a scope of session or request is passed session and/or request info when it is initialized. (if the tool implements ViewContext). • VelocityViewServlet can be subclassed to add additional functionality. Example (in distribution): VelocityLayoutServlet, which uses a 2 pass render in order to apply a common layout to all web pages.

Note: VelocityViewServlet replaces deprecated VelocityServlet distributed with Velocity project

WEB-INF/web.xml

Example application

velocity org.apache.velocity.tools.view.servlet.VelocityViewServlet org.apache.velocity.toolbox /WEB-INF/toolbox.xml org.apache.velocity.properties /WEB-INF/velocity.properties

velocity *.vm

WEB-INF/toolbox.xml

date application org.apache.velocity.tools.generic.DateTool params request org.apache.velocity.tools.view.tools.ParameterParser cookie request org.apache.velocity.tools.view.tools.CookieTool app_version 1.5 app_name A Carroll Compendium

WEB-INF/velocity.properties

# all optional velocimacro.library = /WEB-INF/VM_global_library.vm velocimacro.permissions.allow.inline = true velocimacro.permissions.allow.inline.to.replace.global = false velocimacro.permissions.allow.inline.local.scope = false velocimacro.context.localscope = false

VelocityStruts Tools • ActionMessagesTool • StrutsLinkTool • ErrorsTool • SecureLinkTool • FormTool • TilesTool • MessageTool • ValidatorTool

• Consider – can the problem you are trying to solve be done more simply with a Tool or VelocityMacro?

• If not, Velocity allows you to code your own custom directives by doing the following: – Create a class that extends org.apache.velocity.runtime.directive.Directive – Add the following to velocity.properties userdirective = yourdirectiveclass

• Review the directives in the velocity source code for good examples. For example, review org.apache.velocity.runtime.directive.ForEach

Usage: #endNotes All in the golden afternoon (*1:In these prefatory verses Carroll recalls that "golden afternoon" in 1862 when he and his friend the Reverend Robinson Duckworth (then a fellow of Trinity College, Oxford, later canon of Westminster) took the three charming Liddell sisters on a rowing expedition up the Thames. *) Full leisurely we glide; For both our oars, with little skill, By little arms are plied, While little hands make vain pretence Our wanderings to guide. (* 2:Note how this stanza puns three times with the word "little." "Liddle" was pronounced to rhyme with "fiddle." *) #end

Results: All in the golden afternoon Full leisurely we glide; For both our oars, with little skill, By little arms are plied, While little hands make vain pretence Our wanderings to guide.

NOTES 1: In these prefatory verses Carroll recalls that "golden afternoon" in 1862 when he and his friend the Reverend Robinson Duckworth (then a fellow of Trinity College, Oxford, later canon of Westminster) took the three charming Liddell sisters on a rowing expedition up the Thames.

2:Note how this stanza puns three times with the word "little." "Liddle" was pronounced to rhyme with "fiddle."

Full code listings available at: http://jlamp.com/apachecon2004/ public class EndNoteDirective extends Directive { public String getName() { return "endNotes"; }

public int getType() { return BLOCK; }

public boolean render(InternalContextAdapter context, java.io.Writer writer,Node node) throws ResourceNotFoundException,ParseErrorException,MethodInvocationException { // first, parse the entire block and retrieve the content StringWriter internalwriter = new StringWriter();

// the node's children are the arguments and the body. // here there should be only one child, since there are no arguments node.jjtGetChild(0).render(context, internalwriter);

String sourcecontent = internalwriter.toString(); internalwriter.close();

// missing code creates new "finalcontent" based on "sourcecontent"

writer.write(finalcontent.toString()); return true; } }

Complete sample app available at: http://jlamp.com/apachecon2004/

## Load templates from classpath resource.loader = class class.resource.loader.class = org.apache.velocity.runtime.resource.loader.ClasspathResourceLoader

## Specify the user directive userdirective=com.jlamp.directive.EndNoteDirective

## Log messages displayed with log4j runtime.log.logsystem.class = org.apache.velocity.runtime.log.SimpleLog4JLogSystem runtime.log.logsystem.log4j.category = com.jlamp.velocity

• A ResourceLoader is a mechanism to load a template. Velocity provides these built in ResourceLoaders: – ClasspathResourceLoader – DataSourceResourceLoader – FileResourceLoader – JarResourceLoader

• To implement your own resource loader, extend org.apache.velocity.runtime.resource.loader.ResourceLoader

Complete sample app available at: http://jlamp.com/apachecon2004/ public class FtpResourceLoader extends ResourceLoader { String username; String password; String hostname; String rootDirectory;

public void init (ExtendedProperties configuration) { username = configuration.getString("username"); password = configuration.getString("password"); hostname = configuration.getString("host"); rootDirectory = configuration.getString("root"); }

public long getLastModified (Resource resource) { String name = resource.getName(); if (name.startsWith("/")) name = name.substring(1); return getFileModificationDate(username,password,hostname,rootDirectory + name).getTime(); }

public boolean isSourceModified (Resource resource) { long date = getLastModified(resource); return (date == 0) || (date != resource.getLastModified()); }

public InputStream getResourceStream (String source) throws ResourceNotFoundException { if (source.startsWith("/")) source = source.substring(1); InputStream i = getFileStream(username,password,hostname,rootDirectory + source); if (i == null) throw new ResourceNotFoundException(source); else return i; } }

Complete sample app available at: http://jlamp.com/apachecon2004/

## Load templates from FTP site resource.loader = ftp ftp.resource.loader.class = com.jlamp.resourceloader.FtpResourceLoader ftp.resource.loader.username = templateuser ftp.resource.loader.password = apricots ftp.resource.loader.host = www.jlamp.com ftp.resource.loader.root = /app/templates

## Log messages displayed with log4j runtime.log.logsystem.class = org.apache.velocity.runtime.log.SimpleLog4JLogSystem runtime.log.logsystem.log4j.category = com.jlamp.velocity

• Velocity provides a mechanism to intercept and modify parsing operation.

• Currently, three event handlers available: – ReferenceInsertionEventHandler: Modify the text that gets inserted from a reference (e.g. $date) – NullSetEventHandler: Prevents logging of null #set operations – MethodExceptionEventHandler: Intercept a method thrown by a tool in the context.

• Event handlers are instantiated for each page that is parsed, and are "attached" to the context before the template is merged:

EventCartridge ec = new EventCartridge(); ec.addEventHandler(new CustomReferenceInsertionHandler()); ec.attachToContext( context );

// now merge the template

Complete sample app available at: http://jlamp.com/apachecon2004/

/** * Escape all XML Entities in the reference insertion. Specifically, the following * conversions are performed: *

&: &
<: <
>: >
": "

*/ public class EscapeXMLEntities implements ReferenceInsertionEventHandler {

/** * Escape the XML entities for all inserted references. */ public Object referenceInsert(String reference, Object value) { String val = value.toString(); return escapeText(val); } }

• The introspector is used to discover and execute reference properties and method calls. • The build in introspector calls get/set methods when accessing properties, and does all method calls. • Possible custom introspectors: – Access public fields directly instead of calling get/set methods – Prevent access of "dangerous" methods by untrusted template designer such as getClassLoader() and newInstance. (dirty little secret – any class can be instantiated in a Velocity Template). • A custom introspector is fairly complex to implement. The built-in introspector includes 9 classes in two packages. • Introspector needs to implement org.apache.velocity.util.introspection.Uberspect

Please! Use this knowledge to further the cause of the good, not of those with evil intent.

Today's date: $today Date class: $today.Class

## Let's do some mischief and instantiate an arbitrary class #set ($fileclass = $today.Class.forName("java.io.File")) #set ($stringclass = $today.Class.forName("java.lang.String")) #set ($paramlist = [".."]) #set ($paramarray = $paramlist.toArray()) #set ($constructors = $fileclass.Constructors)

## Call the constructor java.io.File(String) #foreach ($c in $constructors) #if ($c.toString() == "public java.io.File(java.lang.String)") #set ($file = $c.newInstance($paramarray)) $file #end #end

## Now, get the File list. Think about what else you could do! ## Bad, Bad, Bad!

#set ($files = $file.list()) App Directory contents: #foreach ($f in $files) $f #end

Today's date: Mon Oct 18 01:26:06 PDT 2004 Date class: class java.util.Date

App Directory contents: bin build classes_src java lib results

Today's date: Mon Oct 18 01:33:35 PDT 2004 Date class: class java.util.Date

App Directory contents:

Complete sample app available at: http://jlamp.com/apachecon2004/

/** * Property getter */ public VelPropertyGet getPropertyGet(Object obj, String identifier, Info i) throws Exception {

if (!checkObjectExecutePermission(obj,null)) { rlog.warn ("Cannot retrieve get method from object of class " + obj.getClass().getName() + " due to execute security restrictions. [" + i.getLine() + "," + i.getColumn() + "]" + " in template " + i.getTemplateName() + "."); return null;

}

Complete sample app available at: http://jlamp.com/apachecon2004/

## Custom introspector runtime.introspector.uberspect = com.jlamp.introspection.CustomIntrospector

## Load templates from classpath resource.loader = class class.resource.loader.class = org.apache.velocity.runtime.resource.loader.ClasspathResourceLoader

## Log messages displayed with log4j runtime.log.logsystem.class = org.apache.velocity.runtime.log.SimpleLog4JLogSystem runtime.log.logsystem.log4j.category = com.jlamp.velocity

• Velocity Template Language (VTL) is specified in a grammar file designed to be used with JavaCC (javacc.dev.java.net).

• Change the language syntax by editing Parser.jjt.

• Run jjtree and javacc to generate new Parser.java files

• Add new capabilities by creating new Node files and copying into the package org.apache.velocity.runtime.parser.node

• Problem: Adding text without a space in #if statement is difficult.

• Bad syntax: #if($condition)text1#elsetext2#end

• Use block comments #* *# to split #else and text (unreadable) #if($condition)text1#else#**#text2#end

• Proposed syntax – use optional brackets around directive #if($condition)text1#{else}text2#end

Full modification available as patch: http://nagoya.apache.org/bugzilla/show_bug.cgi?id=7189

TOKEN : { { inDirective = false; stateStackPop(); }

| { SwitchTo(DIRECTIVE); }

| { inDirective = false; stateStackPop(); }

| { matchedToken.kind = EOF; fileDepth = 0; } }

Complete sample app available at: http://jlamp.com/apachecon2004/

TOKEN : { { inDirective = false; stateStackPop(); }

| { SwitchTo(DIRECTIVE); }

| { inDirective = false; stateStackPop(); }

| { matchedToken.kind = EOF; fileDepth = 0; } }

1. Download project "jakarta-velocity" from Jakarta CVS

2. Modify "Parser.jjt"

3. Execute shell script "build":

#!/bin/sh

echo "Running JJTree ..." jjtree Parser.jjt

echo "Running JavaCC ..." javacc Parser.jj

# Remove the generated nodes as they are now # in a package of their own. rm -f AST* rm -f Node.java rm -f SimpleNode.java rm -f ParserVisitor.java

4. If necessary (new functionality added), add new node files to package org.apache.velocity.runtime.parser.node.