99 lines
4.0 KiB
XML
99 lines
4.0 KiB
XML
<?xml version="1.0" encoding="UTF-8"?>
|
|
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN" "../dtd/document-v10.dtd">
|
|
|
|
<document>
|
|
<header>
|
|
<title>Record Generator HOWTO</title>
|
|
<authors>
|
|
<person email="glens@apache.org" name="Glen Stampoultzis" id="glens"/>
|
|
</authors>
|
|
</header>
|
|
<body>
|
|
<s1 title="How to Use the Record Generator">
|
|
|
|
<s2 title="History">
|
|
<p>
|
|
The record generator was born from my 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
|
|
record generator was born.
|
|
</p>
|
|
</s2>
|
|
|
|
<s2 title="Capabilities">
|
|
<p>
|
|
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 test class with provides a fill-in-the-blanks implementation of a test case
|
|
for ensuring the record operates as designed.</li>
|
|
</ul>
|
|
</p>
|
|
</s2>
|
|
<s2 title="Usage">
|
|
<p>
|
|
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.
|
|
</p>
|
|
<p>
|
|
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>
|
|
]]></source>
|
|
<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.
|
|
</p>
|
|
</s2>
|
|
<s2 title="How it Works">
|
|
<p>
|
|
TODO: Fill this out more
|
|
</p>
|
|
<p>
|
|
See record.xsl, record_test.xsl, FieldIterator.java, RecordUtil.java, RecordGenerator.java
|
|
</p>
|
|
<p>
|
|
</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.
|
|
</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.
|
|
</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.
|
|
</p>
|
|
</s2>
|
|
</s1>
|
|
</body>
|
|
</document>
|