This article will describe some of the development tools that are available from the Java Open Source community and explore how they can help you create high-quality software in a predictable and reproducible fashion, saving you precious time and money. It is taken from chapter three of the book Enterprise Java Development on a Budget, written by Brian Sam-Bodden and Christopher M. Judd (Apress, 2004; ISBN: 1590591259).
Development and Build System with ANT - JavaDoc Generation (Page 8 of 11 )
For proper team communication and for enabling code reuse you must have a consistent up-to-date set of API documentation. The Javadoc tool has existed for as long as Java has been around and all developers are well acquainted with it. The problem has been that developers feel that they can run Javadoc only after they’re finished with the code (which might be never). Running Javadoc at the end of a project provides very little help to others in the team and moves documentation to the end of process, when it isn’t as helpful (waterfall).
With Ant you can ensure that Javadoc is generated as part of the daily build and that you don’t hide the documentation process until the “end” of the development phase. The Ant Javadoc task provides a convenient way to generate Javadoc from within Ant, as shown here:
Notice that the doctitle and the bottom nested elements make use of the XML character data (CDATA) section in order to be able to use HTML markup and not have it interfere with the markup of the buildfile.
Formatting Source Code with Jalopy
Code format and style is a subject that is sometimes discussed with religious fervor and it’s one of places where developers feel they shouldn’t be forced to follow a standard. Yet determining how clean a piece of code is seems to be a subjective task, and a code base that is in disarray will prevent teamwork and the XP ideal of collective code ownership. We suggest that instead of forcing programmers to code a certain way, you should simply automate the process of formatting the code to a known standard that has been agreed on. For the TCMS system you format all source code as part of the build process. To do so you rely on a handy utility called Jalopy. Jalopy is a Java source-code formatter that reads an XML configuration file that determines the style to apply to the code. By default it’s configured to follow the Sun code conventions for the Java programming language (seehttp://java.sun.com/docs/codeconv/). Jalopy can format brace style, spacing, indentation, code separation (blank lines), as well as control the generation of missing Javadoc comments, and Java file headers and footers.
Jalopy provides an Ant plug-in that is distributed as a single ZIP file (for Ant 1.4 or higher) that can be downloaded fromhttp://jalopy.sourceforge.net/.Unzip the file to a suitable directory. You should have a bin, docs, and a lib directory. The first step is to run the Jalopy GUI configuration utility to fine-tune the settings for the purposes of the application. To do so, change directories to the Jalopy distribution bin directory and execute the preferences script (in this case preferences.bat) as follows:
The Jalopy GUI configuration utility should now be up and running as shown in Figure 3-6.
The GUI utility allows you to modify the settings for a given code convention. The application is a simple tree-driven GUI. As you can see from the General node, the default loaded is the Sun Java Coding Convention (simply named “Sun”). Jalopy allows you to save your settings on a “per-project” basis or by modifying the configuration via the GUI and exporting the configuration to an XML file using the export utility in the General node. You can then use the resulting XML file from within Ant with the Jalopy task.
Figure 3-6.The Jalopy GUI configuration utility
The only customization needed for the TCMS system is to add an appropriate header that will be placed on all source files in the application. To accomplish this, switch to Printer --> Header (all formatting options are under the Printer node). The Header pane has two tabs, Options and Text. Select the Text tab and enter the header text as shown in Figure 3-7.
Figure 3-7.Configuring Java Headers in Jalopy.
The Jalopy preview window should display a sample of what the header will look like after it has been applied to a Java file, as shown in Figure 3-8.
Figure 3-8.Jalopy Header preview
Next, you need to make sure that Jalopy doesn’t add the header to a file that already contains it. To accomplish this you need to give Jalopy a sequence of characters that it can use to determine whether the file has a header or not. In this case, the string selected is “Copyright (c) 2003 Brian Sam-Bodden, Christopher M. Judd,” as shown in Figure 3-9.
You’re now ready to export the configuration to an XML file that you can use from within Ant. Switch to the General pane and click the Export button. Save the file as jalopy-sun-convention.xml under the lib/development/jalopy directory under the TCMS project root.
For the purposes of the TCMS application you’ll place the files under the Jalopy distribution’s lib directory in a directory under the TCMS project root directory named lib/development/jalopy.
Now it’s time to modify the Ant buildfile to format the source code as part of the build. The first step is to load the Jalopy task so that it can be used in the context of the build. To load an external task you use one of Ant’s built-in tasks, the taskdef task, which is specially designed to load other tasks. Notice that you’ve set two properties and a pathelement to simplify the format target. The jalopy-lib property points to the location of the Jalopy JAR files. The jalopy-convention-file property points to the XML file that you previously saved with your modified source-code conventions. Finally, the jalopy taskdef loads the Task class by specifying the classname and the classpath to search for the specified class, as shown here:
You can now define the format target. The format target is dependent on the compile target. You don’t want to try to format code that doesn’t compile. The jalopy task takes the name of the convention file to use and a fileset that contains all the Java source files that will be formatted. Notice the use of a nested patternset to filter out unwanted files. The target definition looks like this: