diff --git a/build/jakarta-poi/docs/hssf/record-generator.html b/build/jakarta-poi/docs/hssf/record-generator.html new file mode 100644 index 000000000..500fe3a84 --- /dev/null +++ b/build/jakarta-poi/docs/hssf/record-generator.html @@ -0,0 +1,292 @@ + + + +Record Generator HOWTO + + + + + + + + + +
+
+
+ + + + +
+
+ +
+Navigation + + +
+HSSF + + +
+Contributer's Guide + + +
+
+		 +Record Generator HOWTO +
+ + + + +
+
+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 +
+ +