The Audience: Java Developers
Rule number one of writing anything is to know your audience. You should cater your XML schema validation code and documentation to the people who will support and enhance your code going forward. For this exercise, assume the audience is competent Java developers with at least a year of programming experience, but not seasoned veterans.
Next, determine how familiar the target audience will be with the tasks required to execute your program. This example works with the following Java programming tasks:
- Creating a Java EE WAR file
- Writing a start-up servlet
- Finding files in a directory; reading and moving them
- Loading a properties file with configuration information
- Running a JAXP XSD schema validation
- Executing schema validations on a thread pool
- Polling for files on a background thread
For the target audience, items 1, 3, and 4 should be no problem. These are all typical activities for a Java developer. The code download includes a FileUtil.java class (see Listing 3) and PropertiesUtil.java class (see Listing 4) to help fulfill these familiar tasks. The FileUtil.java class provides two highly reusable methods that enable you to work with it as a pure utility classa class that contains only static member functions and that cannot be instantiated. The PropertiesUtil.java class is not a pure utility class because it caches properties in an instance variable. A pure utility class would need to read properties from the file system each time a property is accessed, which causes performance issues.
Items 2 (writing a start-up servlet) and 5 (running a JAXP XSD schema validation) may be new to your target audience, so you should document them in your code with Javadoc to ensure not only that the audience reads them but also that the documentation is correct and up to date. In particular, devote some extra time to introducing item 2 in your code and documentation. The StartupValidator.java class (see Listing 5) in the code download includes additional Javadoc documentation that tells developers where the servlet is initialized and provides a sample XML extract of how to initialize it properly. (The source code for StartupValidator.java looks a bit strange because you need to convert the greater-than and less-than signs in the sample XML-to-XML entity references. It will look much better after the Javadoc processor produces HTML from the source code.)
You should write a detailed explanation of Item 5 in your Javadoc comments as well, but that won't be enough. This task involves some complexity inside the run method, and you cannot use Javadoc to document tricky concepts from within a method. So you need to add plain old Java comments as well. In fact, the ValidatorRunnable.java file (see Listing 6) not only completes item 5, but it also has a few comments to explain the complexity in the run method. The ValidationErrorHandler.java file (see Listing 7) contains a more-detailed-than-normal Javadoc explanation as well. Additionally, the two files cross reference each other using the Javadoc @see tag, enabling someone who is viewing the Javadoc to click on a hyperlink and quickly view the documentation for the associated class.
As for Items 6 and 7 (executing schema validations on a thread pool and polling for files on a background thread, respectively), these are tricky concepts even for seasoned developers. You will need to apply responsibility-driven design (RDD) to help others understand your code in this area. RDD, a combination of techniques used by seasoned object-oriented programmers, is beyond the scope of this article. Click here for more information.