--- /dev/null
+<?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>
projects / poi.git / commitdiff