<title>Record Generator HOWTO</title>
<authors>
<person email="glens@apache.org" name="Glen Stampoultzis" id="glens"/>
+ <person email="acoliver@apache.org" name="Andrew C. Oliver" id="acoliver"/>
</authors>
</header>
<body>
<s2 title="History">
<p>
- The record generator was born from my frustration with translating
+ 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.
</p>
<p>
- I wanted something that would take the defintition of what a
- record looked like and do all the boring stuff for me. Thus the
+ 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.
</p>
</s2>
The record generator takes XML as input and produced the following
output:
<ul>
- <li>A java file capabile of decoding and encoding the record.</li>
+ <li>A Java file capabile of decoding and encoding the record.</li>
<li>A test class with provides a fill-in-the-blanks implementation of a test case
for ensuring the record operates as designed.</li>
</ul>
The records themselves have the following general layout:
</p>
<source><![CDATA[
- <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>
+<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>
]]></source>
<p>
- 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'.
+ 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'.
</p>
<p>
- 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.
+ 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.
</p>
</s2>
<s2 title="How it Works">
<p>
- 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.
- This would probably have been better off done as javascript and may well be migrated in the
- near future. Since the current Java code was written as a proof of concept it's a little
- lacking in commenting and structure. Since this is converted to Javascript this should no
- longer be a problem.
+ 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.
</p>
<p>
- See record.xsl, record_test.xsl, FieldIterator.java, RecordUtil.java, RecordGenerator.java
+ See record.xsl, record_test.xsl, FieldIterator.java,
+ RecordUtil.java, RecordGenerator.java
</p>
</s2>
<s2 title="Limitations">
<p>
- 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.
+ 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.
</p>
<p>
- 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 record generator is optimized to create Excel records.
+ It could be adapted to create Word records with a little poking
+ around.
</p>
<p>
- 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. Sorry, I wrote it as a proof-of-concept and just went
- too far.
+ 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.
</p>
</s2>
</s1>
projects / poi.git / commitdiff