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