Record Generator HOWTO

+ + + + + + + +

How to Use the Record Generator

+
+ + +

+ + + + + + + +

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 defintition of what a + record looked like and do all the boring stuff. Thus the + record generator was born. +

+ +

+
+ + +

+ + + + + + + +

Capabilities

+
+ +

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

A Java file capabile of decoding and encoding the record.
A test class with 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/defintitions 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: +

+ +

+ + + + +

+<record id="0x1032" name="Frame" package="org.apache.poi.hssf.record">
+    <description>The frame record indicates whether there is a border 
+                 around the displayed text of a chart.</description>
+    <author>Glen Stampoultzis (glens at apache.org)</author>
+    <fields>
+        <field type="int" size="2" name="border type">
+            <const name="regular" value="0" description="regular rectangle or no border"/>
+            <const name="shadow" value="1" description="rectangle with shadow"/>
+        </field>
+        <field type="int" size="2" name="options">
+            <bit number="0" name="auto size" 
+               description="excel calculates the size automatically if true"/>
+            <bit number="1" name="auto position" 
+               description="excel calculates the position automatically"/>
+        </field>
+    </fields>
+</record>
+

+ +

+ Currently the type can be of type int, float or string. The 'int' + type covers bytes, shorts and integers which is selected using a + size of 1, 2 or 4. An additional type called varword is used to + represent a array of word values where the first short is the length + of the array. The string type generation is only partially + implemented. If choosing string you must select a size of 'var'. +

+ +

+ 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. +

+ +

+
+ +

+ + + + + + + +

How it Works

+
+ +

+ The record generation works by taking an XML file and styling it + using XLST. 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 +

+ +

+
+ +

+ + + + + + + +

Limitations

+
+ +

+ The record generator does not handle all possible record types and + is not ment to. Sometimes it's going to make more sense to generate + the records manually. The main point of this thing is to make the + easy stuff simple. +

+ +

+ Currently the record generator is optimized to create Excel records. + It could be adapted to create Word records with a little poking + around. +

+ +

+ Currently the the XSL file that generates the record calls out to + Java objects. This would have been better done as Javascript inside + the XSL file itself. The Java code for the record generation is + currently quite messy with minimal comments. +

+ +

+
+ +

+ +
+ Copyright ©2002 Apache Software Foundation +