Using VPP

Basic VPP

VPP uses Ant to drive Velocity-style template preprocessing. In order to use VPP, you should have some familiarity with both Ant and Velocity. VPP supports all legal VTL and by default, includes the Ant project object in all contexts available to your templates. This allows you to access any project properties defined in your build script.

Accessing Ant Properties within a Template

public class HelloWorld {
  public static void main(String[] args) {
    System.out.println("$ant.foo");
  }
}

would become:

public class HelloWorld {
  public static void main(String[] args) {
    System.out.println("bar");
  }
}

Any Ant project property can be accessed by the template, regardless how the project property was defined. This means that you can use properties loaded from the environment, property files, or xml.

Adding VPP To Your Project

VPP is an Extension

In order to use VPP in your projects as an extension, you must include the following definitions:

    <typedef resource="foundrylogic/vpp/typedef.properties" />
    <taskdef resource="foundrylogic/vpp/taskdef.properties" />

Defining a vppInit target like the one below is one way to do organize this and have these definitions executed using a dependency.

  <target name="vppInit">
    <typedef resource="foundrylogic/vpp/typedef.properties" />
    <taskdef resource="foundrylogic/vpp/taskdef.properties" />
  </target>

VPP is an Antlib

In order to use VPP in your projects as an Antlib, you must add the following line to your <project> tag:

	xmlns:vpp="antlib:foundrylogic.vpp"

For example,

  <project 
	name="FoundryLogic VPP: Velocity Pre-Processor Test" 
	default="all" 
	basedir="."
	xmlns:vpp="antlib:foundrylogic.vpp"
  </project>

Note that by using VPP as an Antlib, you do not have to load any VPP typedef or tasksdef resources explicity and so there is generally no need for an vppInit-like target as shown above.

Simple Preprocessing

<vppcopy> is the easiest way to preprocess text files. Use <vppcopy> (extension) or <vpp:copy> (Antlib) just as you would <copy> to preprocess files in addition to copying them. <vppcopy> supports all of <copy>'s parameters and nested parameters.

Note that when using an Antlib, it is best to also specify the default namespace attribute of tasks and filters to avoid naming problems with nested elements. The default namespace for VPP tasks and filters is xmlns="antlib:foundrylogic.vpp"

This example shows how one might use various Ant mechanisms to define project properties and select input sources using a <fileset> and <mapper>:

  <target name="preprocess" depends="vppInit">
    <property name="version" value="1.0.0" >
    <property environment="env" >
    <xmlproperty file="some.xml" >
    <vppcopy todir="output" overwrite="true" >
      <fileset dir="src" includes="*.html.vpp" />
      <mapper type="glob" from="*.html.vpp" to="*.html" />
    </vppcopy>
  </target>

  <target name="preprocess">
    <property name="version" value="1.0.0" >
    <property environment="env" >
    <xmlproperty file="some.xml" >
    <vpp:copy todir="output" overwrite="true" xmlns="antlib:foundrylogic.vpp"> 
      <fileset dir="src" includes="*.html.vpp" />
      <mapper type="glob" from="*.html.vpp" to="*.html" />
    </vpp:copy>
  </target>

Preprocessing Java Code

<vppjavac> (extension) or <vpp:javac> (Antlib) integrates preprocessing with the java compiler to allow you to use Velocity directives within your source code to support conditional compilation, macros, and whatever else your imagination can come up with.

<vppjavac> and <vpp:javac> accepts all of <javac>'s parameters and nested parameters, so you can simply replace any usage of <javac> with <vppjavac>.

  <target name="compile" depends="vppInit">
    <vppjavac srcdir="src" destdir="build/classes">
      <classpath refid="some.classpath" />
    </vppjavac>
  </target>

  <target name="compile">
    <vpp:javac srcdir="src" destdir="build/classes" xmlns:vpp="antlib:foundrylogic.vpp" >
      <classpath refid="some.classpath" />
    </vpp:javac>
  </target>

Preprocessing with Filter Chains

Use the foundrylogic.vpp.vppfilter filter reader in your filter chains to enable Velocity processing in your streams. The following example is essentially identical to the Simple Processing example shown above, but does it using a filter chain instead.

Note that pre-Ant 1.6, external filter readers were accessed via filterreader and as of Ant 1.6, external filter readers can now be used in the same way as built-ins.

  <target name="copychain" depends="vppInit">
    <copy todir="output" overwrite="true">
      <fileset dir="src">
        <include name="**/*.html.vpp" />
      </fileset>
      <filterchain>
        <filterreader classname="foundrylogic.vpp.VPPFilter" />
      </filterchain>
      <mapper type="glob" from="*.html.vpp" to="*.html" />
    </copy>
  </target>

  <target name="copychain">
    <copy todir="output" overwrite="true">
      <fileset dir="src">
        <include name="**/*.html.vpp" />
      </fileset>
      <filterchain>
        <vpp:filter/>
      </filterchain>
      <mapper type="glob" from="*.html.vpp" to="*.html" />
    </copy>
  </target>

Advanced VPP

Configuring VPP

VPP is configured by using adding a <config> nested parameter to any VPP task or filter. This nested parameter allows you to pass properties directly to the Velocity Context and/or Velocity Engine prior to use.

  <target name="preprocess" depends="vppInit">
    <vppcopy todir="output" overwrite="true" >
      <fileset dir="src" includes="*.html.vpp" />
      <mapper type="glob" from="*.html.vpp" to="*.html" />
      <config>
        ...
      </config>
    </vppcopy>
  </target>

  <target name="preprocess" >
    <vpp:copy todir="output" overwrite="true" xmlns:vpp="antlib:foundrylogic.vpp" >
      <fileset dir="src" includes="*.html.vpp" />
      <mapper type="glob" from="*.html.vpp" to="*.html" />
      <config>
        ...
      </config>
    </vpp:copy>
  </target>

You may also configure a Velocity Context and/or Velocity Engine using a standalone <vppconfig> (extension) or <vpp:config> (Antlib) element, which can be reference by its refid.

  <target name="vppInit">
    <typedef resource="foundrylogic/vpp/typedef.properties" />
    <taskdef resource="foundrylogic/vpp/taskdef.properties" />

    <vppconfig id="vppconfig0">
      ...
    </vppconfig>
  </target>

  <target name="preprocess" depends="vppInit">
    <vppcopy todir="output" overwrite="true" >
      <fileset dir="src" includes="*.html.vpp" />
      <mapper type="glob" from="*.html.vpp" to="*.html" />
      <config refid="vppconfig0" />
    </vppcopy>
  </target>

  <target name="vppInit">
    <vpp:config id="vppconfig0">
      ...
    </vpp:config>
  </target>

  <target name="preprocess" depends="vppInit">
    <vpp:copy todir="output" overwrite="true" xmlns:vpp="antlib:foundrylogic.vpp" >
      <vpp:fileset dir="src" includes="*.html.vpp" />
      <vpp:mapper type="glob" from="*.html.vpp" to="*.html" />
      <vpp:config refid="vppconfig0" />
    </vpp:copy>
  </target>

Velocity Context Configuration

This table describes the Velocity Context properties set by default by VPP in addition to any other properties defined by default by Velocity itself. You can of course override these settings and/or any others in your build scripts:

The <context> nested parameter of <vppconfig> allows you to define properties and tools for use by your templates. You can also install an event handler for handling Velocity-related events using the eventHandler attribute (since VPP 2.2.0).

• The <property> nested parameter of <context> is similar to Ant's <property> in that it can be used to define a simple property or to read properties from a file using the extended property file syntax. In addition properties defined in this way are not made Ant project properties and are available in your templates by their simple names, i.e. they do not need to be preceded by ant. to be accessed in your templates.

  Example Velocity Context property definitions

  <vppconfig id="vppconfig0" > <context> <property key="foo" value="bar" /> <property file="some.properties" /> </context> </vppconfig>

• The <tool> nested parameter of <context> is used to load utility objects into the context for use by templates. Your tool simply needs to have a public no-arg constructor so that it can be created dynamically by VPP.

  There are two methods in which to configure tools:

  1. Specify the fully qualified class name of the tool using the className attribute:

     Example of Velocity Context tool configured using the className attribute

     <vppconfig id="vppconfig0" > <context> <tool key="mytool" className="foo.bar.MyTool" /> </context> </vppconfig>

  While simpler than the next method, this method does not support configuration of the tool.

  2. Specify the id of a configured data type using the refid attribute:

     Example of a Velocity Context tool configured using the refid attribute

     <typedef name="mytool" className="foo.bar.MyTool" > <mytool id="mytool0" someProp="someValue" > <vppconfig id="vppconfig0" > <context> <tool key="mytool" refid="mytool0" /> </context> </vppconfig>

     The advantage of this method over the previous method is that you can configure your tool using Ant's configuration conventions. (Note: Ant dynamically supports any class following its configuration conventions, so it is not necessary for your tool to extend org.apache.tools.ant.types.DataType to make this work.)

  Regardless of which method you use, if your tool supports the method

  	public void setVelocityContext(VelocityContext vc)
  

  then that method will be invoked, passing your tool instance a the VelocityContext instance prior to use.

• The eventHandler attribute of <context> is used to install an event handler. Like tools above, your event handler must have a public no-arg constructor, may be configured using either the className or refid attributes, and may optionaly implement the method

  	public void setVelocityContext(VelocityContext vc)
  

  which will be called prior to use.

  Only one event handler may be configured per Velocity Context and each event handler must implement one or more of the org.apache.velocity.app.event.EventHandler sub-interfaces.

  Example of a Velocity Context event handler configuration

  <vppconfig id="vppconfig0" > <context> <!-- The VPPFailOnNullInsertion event handler is included with VPP and causes a BuildException if Velocity attempts to insert a null reference. --> <eventHandler className="foundrylogic.vpp.VPPFailOnNullInsertion" > </context> </vppconfig>

Velocity Engine Configuration

This table describes the Velocity Engine properties set by default by VPP in addition to any properties defined by default by Velocity itself. You can of course override these settings and/or any others in your build scripts:

The <engine> nested parameter of <vppconfig> allows you to configure the Velocity Engine used to process your templates.

The <property> nested parameter is used to define properties for the Velocity Engine. Note that the add attribute may be used for setting multi-valued properties. See the Velocity documentation for a list of supported parameters.

  <config>
    <engine>
      <property key="file.resource.loader.path" add="yes" value="one/more/path" />
      <property key="file.resource.loader.path" add="yes" value="and/another/path" />
    </engine>
  </config>

Copyright ©2002-2004 FoundryLogic, LLC. All rights Reserved.