org.apache.velocity.texen.ant.TexenTask.execute() currently deals with
exceptions thrown during the generation process by printing a standard
stack trace. IMHO this is not the best way to handle them. exceptions
should be rethrown as org.apache.tools.ant.BuildException's for the
following reasons:
1. ant understands that when a BuildException is thrown, an error has
prevented the task from completing. processing of the build then stops.
this is very useful when you have a single ant build file containing
both code generation tasks and compilation tasks - if a code generation
task fails, then compilation does not proceed.
2. ant BuildExceptions can contain a causal exception. this means that
more useful messages can be given to the user rather than a simple stack
trace. ant does quite a good job of formatting BuildExceptions - texen
should take advantage.
3. (as far as i can see) catching and rethrowing seems to be the ant way
to do these things.
this patch catchs exceptions and rethrows them as BuildExceptions for
Ant to deal with. known velocity exceptions are caught and rethrown with
additional messages.
this patch also contains some small improvements to the (javadoc)
documentation.
- robert
Index: src/java/org/apache/velocity/texen/ant/TexenTask.java
===================================================================
RCS file:
/home/cvs/jakarta-velocity/src/java/org/apache/velocity/texen/ant/TexenTask.java,v
retrieving revision 1.21
diff -u -r1.21 TexenTask.java
--- src/java/org/apache/velocity/texen/ant/TexenTask.java 2001/03/23 18:10:03
1.21
+++ src/java/org/apache/velocity/texen/ant/TexenTask.java 2001/04/23 19:02:15
@@ -73,6 +73,9 @@
import org.apache.velocity.runtime.configuration.Configuration;
import org.apache.velocity.texen.Generator;
import org.apache.velocity.util.StringUtils;
+import org.apache.velocity.exception.MethodInvocationException;
+import org.apache.velocity.exception.ParseErrorException;
+import org.apache.velocity.exception.ResourceNotFoundException;
/**
* An ant task for generating output by using Velocity
@@ -84,6 +87,12 @@
public class TexenTask extends Task
{
/**
+ * This field contains a message.
+ * This message (telling users to consult the log) is appended to rethrown
+exception messages.
+ */
+ private final static String MSG_CONSULT_LOG= ". For more information consult the
+velocity log.";
+
+ /**
* This is the control template that governs the output.
* It may or may not invoke the services of worker
* templates.
@@ -109,28 +118,29 @@
protected String outputFile;
/**
+ * <p>
* 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
+ * 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.
- *
+ * </p><p>
* For example, if you are generating scripts to allow
* user to automatically create a database, then
- * you might want the $databaseName to be placed
+ * you might want the <code>$databaseName</code> to be placed
* in the initial context so that it is available
* in a script that might look something like the
* following:
- *
+ * <code><pre>
* #!bin/sh
*
* echo y | mysqladmin create $databaseName
- *
- * The value of $databaseName isn't critical to
+ * </pre></code>
+ * The value of <code>$databaseName</code> 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
@@ -139,7 +149,7 @@
protected Configuration contextProperties;
/**
- * Get the control template for the
+ * [REQUIRED] Set the control template for the
* generating process.
*/
public void setControlTemplate (String controlTemplate)
@@ -157,7 +167,7 @@
}
/**
- * Set the path where Velocity will look
+ * [REQUIRED] Set the path where Velocity will look
* for templates using the file template
* loader.
*/
@@ -185,7 +195,7 @@
}
/**
- * Set the output directory. It will be
+ * [REQUIRED] Set the output directory. It will be
* created if it doesn't exist.
*/
public void setOutputDirectory(File outputDirectory)
@@ -209,7 +219,7 @@
}
/**
- * Set the output file for the
+ * [REQUIRED] Set the output file for the
* generation process.
*/
public void setOutputFile(String outputFile)
@@ -246,7 +256,7 @@
}
/**
- * Set the context properties that will be
+ * Get the context properties that will be
* fed into the initial context be the
* generating process starts.
*/
@@ -262,6 +272,10 @@
/**
* Execute the input script with WM
+ *
+ * @throws BuildException
+ * BuildExceptions are thrown when required attributes are missing.
+ * Exceptions thrown by Velocity are rethrown as BuildExceptions.
*/
public void execute () throws BuildException
{
@@ -427,9 +441,34 @@
writer.close();
generator.shutdown();
}
+
+ /*
+ * Catch exceptions and rethrow them as ant BuildExceptions.
+ * This prevents ant continuing in the case of failure.
+ */
+
+ // Write better messages for velocity exception.
+ catch (org.apache.velocity.exception.MethodInvocationException e)
+ {
+ throw new org.apache.tools.ant.BuildException(
+ "Exception thrown by '" + e.getReferenceName() + "." +
+e.getMethodName() +"'" + MSG_CONSULT_LOG
+ ,e.getWrappedThrowable());
+ }
+
+ catch (org.apache.velocity.exception.ParseErrorException e)
+ {
+ throw new org.apache.tools.ant.BuildException("Velocity syntax error" +
+MSG_CONSULT_LOG ,e);
+ }
+
+ catch (org.apache.velocity.exception.ResourceNotFoundException e)
+ {
+ throw new org.apache.tools.ant.BuildException("Resource not found" +
+MSG_CONSULT_LOG,e);
+ }
+
+ // Other exceptions
catch (Exception e)
{
- e.printStackTrace();
+ throw new org.apache.tools.ant.BuildException("Generation failed" +
+MSG_CONSULT_LOG ,e);
}
}
