org.apache.velocity.texen.ant
Class Texen

java.lang.Object
  |
  +--org.apache.velocity.texen.ant.Texen

public class Texen
extends java.lang.Object

An ant task for generating output by using Velocity

Version:
$Id: Texen.java,v 1.1 2002/03/04 01:52:34 jvanzyl Exp $
Author:
Jason van Zyl, Robert Burrell Donkin

Field Summary
protected  org.apache.commons.collections.ExtendedProperties contextProperties
           These are properties that are fed into the initial context from a properties file.
protected  java.lang.String contextPropertiesFile
          Reference to the context properties that is held until processing in the execute() method.
protected  java.lang.String controlTemplate
          This is the control template that governs the output.
private static java.lang.String ERR_MSG_FRAGMENT
          This message fragment (telling users to consult the log or invoke ant with the -debug flag) is appended to rethrown exception messages.
private  java.lang.String fileSeparator
          Path separator.
protected  java.lang.String inputEncoding
          This is the encoding for the input file(s) (templates).
protected  java.lang.String outputDirectory
          This is where texen will place all the output that is a product of the generation process.
protected  java.lang.String outputEncoding
          This is the encoding for the output file(s).
protected  java.lang.String outputFile
          This is the file where the generated text will be placed.
protected  org.apache.tools.ant.Project project
          Ant project that is populated by the Ant TaskAdapter when this bean is run as an Ant Task.
protected  java.lang.String templatePath
          This is where Velocity will look for templates using the file template loader.
protected  boolean useClasspath
          Property which controls whether the classpath will be used when trying to locate templates.
 
Constructor Summary
Texen()
           
 
Method Summary
protected  void cleanup()
          A hook method called at the end of execute() which can be overridden to perform any necessary cleanup activities (such as the release of database connections, etc.).
 void execute()
          Execute the input script with Velocity
 org.apache.commons.collections.ExtendedProperties getContextProperties()
          Get the context properties that will be fed into the initial context be the generating process starts.
 java.lang.String getControlTemplate()
          Get the control template for the generating process.
 java.lang.String getOutputDirectory()
          Get the output directory.
 java.lang.String getOutputFile()
          Get the output file for the generation process.
 org.apache.tools.ant.Project getProject()
          Get the Ant project which will be non-null if this bean is used as a Task and adapted by the Ant TaskAdapter.
 java.lang.String getTemplatePath()
          Get the path where Velocity will look for templates using the file template loader.
 Context initControlContext()
          Creates a VelocityContext.
private  void log(java.lang.String message)
          Log a message.
protected  void populateInitialContext(Context context)
          Place useful objects into the initial context.
protected  void processContextProperties(java.lang.String file)
          Process the templatePath.
protected  void processTemplatePath(java.lang.String templatePath)
          Process the templatePath.
private  java.io.File resolveFile(java.lang.String file)
          Resolve a file.
 void setContextProperties(java.lang.String file)
          Set the context properties that will be fed into the initial context be the generating process starts.
 void setControlTemplate(java.lang.String controlTemplate)
          [REQUIRED] Set the control template for the generating process.
 void setInputEncoding(java.lang.String inputEncoding)
          Set the input (template) encoding.
 void setOutputDirectory(java.io.File outputDirectory)
          [REQUIRED] Set the output directory.
 void setOutputEncoding(java.lang.String outputEncoding)
          Set the output encoding.
 void setOutputFile(java.lang.String outputFile)
          [REQUIRED] Set the output file for the generation process.
 void setProject(org.apache.tools.ant.Project project)
          Set the Ant project.
 void setTemplatePath(java.lang.String templatePath)
          [REQUIRED] Set the path where Velocity will look for templates using the file template loader.
 void setUseClasspath(boolean useClasspath)
          Set the use of the classpath in locating templates
 
Methods inherited from class java.lang.Object
, clone, equals, finalize, getClass, hashCode, notify, notifyAll, registerNatives, toString, wait, wait, wait
 

Field Detail

ERR_MSG_FRAGMENT

private static final java.lang.String ERR_MSG_FRAGMENT
This message fragment (telling users to consult the log or invoke ant with the -debug flag) is appended to rethrown exception messages.

controlTemplate

protected java.lang.String controlTemplate
This is the control template that governs the output. It may or may not invoke the services of worker templates.

templatePath

protected java.lang.String templatePath
This is where Velocity will look for templates using the file template loader.

outputDirectory

protected java.lang.String outputDirectory
This is where texen will place all the output that is a product of the generation process.

outputFile

protected java.lang.String outputFile
This is the file where the generated text will be placed.

outputEncoding

protected java.lang.String outputEncoding
This is the encoding for the output file(s).

inputEncoding

protected java.lang.String inputEncoding
This is the encoding for the input file(s) (templates).

contextProperties

protected org.apache.commons.collections.ExtendedProperties contextProperties

These are properties that are fed into the initial context from a properties file. This is simply a convenient way to set some values that you wish to make available in the context.

These values are not critical, like the template path or output path, but allow a convenient way to set a value that may be specific to a particular generation task.

For example, if you are generating scripts to allow user to automatically create a database, then you might want the $databaseName to be placed in the initial context so that it is available in a script that might look something like the following:

 #!bin/sh
 
 echo y | mysqladmin create $databaseName
 
The value of $databaseName isn't critical to output, and you obviously don't want to change the ant task to simply take a database name. So initial context values can be set with properties file.

contextPropertiesFile

protected java.lang.String contextPropertiesFile
Reference to the context properties that is held until processing in the execute() method. We do this now so that the Ant TaskAdapter can set the project which is needed for correct path processing when this bean is used as an ant task.

useClasspath

protected boolean useClasspath
Property which controls whether the classpath will be used when trying to locate templates.

fileSeparator

private java.lang.String fileSeparator
Path separator.

project

protected org.apache.tools.ant.Project project
Ant project that is populated by the Ant TaskAdapter when this bean is run as an Ant Task.
Constructor Detail

Texen

public Texen()
Method Detail

setControlTemplate

public void setControlTemplate(java.lang.String controlTemplate)
[REQUIRED] Set the control template for the generating process.

getControlTemplate

public java.lang.String getControlTemplate()
Get the control template for the generating process.

setTemplatePath

public void setTemplatePath(java.lang.String templatePath)
[REQUIRED] Set the path where Velocity will look for templates using the file template loader.

processTemplatePath

protected void processTemplatePath(java.lang.String templatePath)
                            throws java.lang.Exception
Process the templatePath. We hold off processing so that when run as an Ant Task the project will be set, and the project is required for correct path resolving.

getTemplatePath

public java.lang.String getTemplatePath()
Get the path where Velocity will look for templates using the file template loader.

setOutputDirectory

public void setOutputDirectory(java.io.File outputDirectory)
                        throws java.lang.Exception
[REQUIRED] Set the output directory. It will be created if it doesn't exist.

getOutputDirectory

public java.lang.String getOutputDirectory()
Get the output directory.

setOutputFile

public void setOutputFile(java.lang.String outputFile)
[REQUIRED] Set the output file for the generation process.

setOutputEncoding

public void setOutputEncoding(java.lang.String outputEncoding)
Set the output encoding.

setInputEncoding

public void setInputEncoding(java.lang.String inputEncoding)
Set the input (template) encoding.

getOutputFile

public java.lang.String getOutputFile()
Get the output file for the generation process.

setContextProperties

public void setContextProperties(java.lang.String file)
Set the context properties that will be fed into the initial context be the generating process starts.

processContextProperties

protected void processContextProperties(java.lang.String file)
                                 throws java.lang.Exception
Process the templatePath. We hold off processing so that when run as an Ant Task the project will be set, and the project is required for correct path resolving.

getContextProperties

public org.apache.commons.collections.ExtendedProperties getContextProperties()
Get the context properties that will be fed into the initial context be the generating process starts.

setUseClasspath

public void setUseClasspath(boolean useClasspath)
Set the use of the classpath in locating templates
Parameters:
boolean - true means the classpath will be used.

setProject

public void setProject(org.apache.tools.ant.Project project)
Set the Ant project. Used when this bean is adapted by the Ant TaskAdapter.

getProject

public org.apache.tools.ant.Project getProject()
Get the Ant project which will be non-null if this bean is used as a Task and adapted by the Ant TaskAdapter.

initControlContext

public Context initControlContext()
                           throws java.lang.Exception
Creates a VelocityContext.
Returns:
new Context
Throws:
java.lang.Exception - the execute method will catch and rethrow as a BuildException

execute

public void execute()
             throws java.lang.Exception
Execute the input script with Velocity
Throws:
BuildException - BuildExceptions are thrown when required attributes are missing. Exceptions thrown by Velocity are rethrown as BuildExceptions.

populateInitialContext

protected void populateInitialContext(Context context)
                               throws java.lang.Exception

Place useful objects into the initial context.

TexenTask places Date().toString() into the context as $now. Subclasses who want to vary the objects in the context should override this method.

$generator is not put into the context in this method.

Parameters:
context - The context to populate, as retrieved from initControlContext().
Throws:
java.lang.Exception - Error while populating context. The execute() method will catch and rethrow as a BuildException.

cleanup

protected void cleanup()
                throws java.lang.Exception
A hook method called at the end of execute() which can be overridden to perform any necessary cleanup activities (such as the release of database connections, etc.). By default, does nothing.
Throws:
java.lang.Exception - Problem cleaning up.

log

private void log(java.lang.String message)
Log a message. Use the Ant logging system if being used as an Ant Task.

resolveFile

private java.io.File resolveFile(java.lang.String file)
                          throws java.lang.Exception
Resolve a file. Use the baseDir of the project if being run as an Ant Task. A couple methods


Copyright © 2003 Apache Software Foundation. All Rights Reserved.