Record Generator HOWTO

History

The record generator was born from frustration with translating the Excel records to Java classes. Doing this manually is a time consuming process. It's also very easy to make mistakes.

A utility was needed to take the definition of what a record looked like and do all the boring and repetitive work.

Capabilities

The record generator takes XML as input and produces the following output:

• A Java file capable of decoding and encoding the record.
• A test class that provides a fill-in-the-blanks implementation of a test case for ensuring the record operates as designed.

Usage

The record generator is invoked as an Ant target (generate-records). It goes through looking for all files in src/records/definitions ending with _record.xml. It then creates two files; the Java record definition and the Java test case template.

The records themselves have the following general layout:

The following table details the allowable types and sizes for the fields.

The Java records are regenerated each time the record generator is run, however the test stubs are only created if the test stub does not already exist. What this means is that you may change test stubs but not the generated records.

Custom Field Types

Occasionally the builtin types are not enough. More control over the encoding and decoding of the streams is required. This can be achieved using a custom type.

A custom type lets you escape to java to define the way in which the field encodes and decodes. To code a custom type you declare your field like this:

Where the class name specified after custom: is a class implementing the interface CustomField.

You can then implement the encoding yourself.

How it Works

The record generation works by taking an XML file and styling it using XSLT. Given that XSLT is a little limited in some ways it was necessary to add a little Java code to the mix.

See record.xsl, record_test.xsl, FieldIterator.java, RecordUtil.java, RecordGenerator.java

There is a corresponding "type" generator for HWPF. See the HWPF documentation for details.

Limitations

The record generator does not handle all possible record types and goes not intend to perform this function. When dealing with a non-standard record sometimes the cost-benefit of coding the record by hand will be greater than attempting modify the generator. The main point of the record generator is to save time, so keep that in mind.

Currently the the XSL file that generates the record calls out to Java objects. The Java code for the record generation is currently quite messy with minimal comments.