Home

HashInclude is an ANT task that embeds blocks of text from external files into your Java source files, optionally performing replacements as it does so. The text is re-embedded whenever the external file changes.

In essence, it is similar to C/C++'s #include directive, except that the text is physically inserted into your source files.

I first encountered this need when I developed a set of Swing components all based on the standard set of components. I wanted to add similar functionality to each, but since I could not add anything to the standard ancestor components, I was forced to add the same code to each new class, and every time I altered something, I had to go through all classes to make the same modifications to each of dozens of classes. HashInclude is the result.

Samples

Here is a sample of an include file, and of a Java class that includes it.

Instructions

Ant task

Add the hashinclude task to your Ant build.xml file, and call the task before compiling the Java sources. In this code sample, replace the folder name and version to the actual full filename of the HashInclude jar file you downloaded.

<target name="hashinclude">
    <taskdef classpath="XXX/hashinclude-X.X.jar" classname="mt.rcasha.ant.Include" name="hashinclude" />
    <hashinclude srcdir="src" includes="**/*.java" />
</target>

Included file.

The file to be included is a simple text file. If you wish to use parameter replacement, add them as the first line, as this example shows:

!~!(replace=(TYPE=String,EVENT=fireValueChanged))

This example shows two parameters, TYPE and EVENT. The values given are the default values. HashInclude will replace every instance of those exact words with the replacements. If the replacement text contains a close-bracket or comma, this must be escaped by preceding it with a backslash. Note that this line must start at exactly line 1, column 1.

Java source file

This is an ordinary Java source file, with the following two comments. Any text after the #include line and before the #end line will be replaced.

//#include(filename=../validatable.inc,replace=(TYPE=T))
//#end

HashInclude will not proceed if the file is not readable, or if the end-comment is not found.
Filename identifies the file to be included, relative to the file being processed. Note that there are no quotes.
Replace contains parameter replacements. These override the default values given in the source file itself.

Notes

HashInclude is not recursive. Included files are not processed for further hashinclude comments.

Any changes made to the text within the included block will be replaced the next time that HashInclude is run. It is advisable to include comments such as "DO NOT EDIT THIS SECTION" throughout the included file to avoid lost modifications.

NetBeans users: You can place a code-folding comment on the same line AFTER the hashinclude comment, as follows. This will fold the entire included block.

//#include(filename=../value-holder.inc) <editor-fold defaultstate="collapsed" desc="#include value-holder.inc">
//#end </editor-fold>