9.4 Regenerating Files That Have Changed

9.4.1 Problem

You want to control when files are regenerated.

9.4.2 Solution

Add the force attribute to any Ant Doclet task.

9.4.3 Discussion

Ant XDoclet tasks, by default, perform dependency-checking on generated files. These checks only regenerate files that are out of date with respect to their corresponding template files. There are times, though, that you may wish to force all generated files to be regenerated. For example, you may wish to do this if you are performing a clean build of the project from scratch, or you have upgraded to a newer version of XDoclet.

All XDoclet tasks, such as ejbdoclet, define an attribute called force. This attribute tells the XDoclet task whether to perform dependency-checking before generating a file. A value of "true" tells the XDoclet task to force generation of all files. A value other than "true" tells the XDoclet task to perform dependency-checking before generating a file. A dependency check simply looks at the timestamp of a source or template file and compares it with the timestamp of its generated files. If a source or template file has a timestamp that is greater than its generated files, then the files are regenerated. Example 9-1 shows how to add the force attribute to any XDoclet task.

Example 9-1. Using the force attribute to control dependency-checking

<target name="generate.ejb">
  <ejbdoclet
      ejbspec="2.0"
      destdir="${dir.generated.src}"      
      force="${force.ejb}">

  <!-- subtasks left out for brevity --> 

  </ejbdoclet>
</target>

The force attribute is added to the XDoclet task's list of attributes and its value is defined by the property force.generation. You could set up a property in the buildfile that specifies the force attribute value like this:

<property name="force.generation" value="true"/>

It's not necessary, though. Remember that any value other than "true" turns on dependency-checking. So we can rely on the fact that if Ant cannot find the property ${force.generation}, then the text "${force.generation}" is simply passed as the value, which is definitely not equal to "true". Therefore, dependency-checking is turned on.

Here is how to force all files to be regenerated:

ant generate.ejb -Dforce.generation=true

And here is how to use dependency-checking (we do nothing special):

ant generate.ejb

9.4.4 See Also

Recipe 9.2 discusses where generated source files should go in a development environment.