glens 02/03/08 17:41:01
Modified: src/documentation/xdocs/hssf book.xml
Added: src/documentation/xdocs/hssf record-generator.xml
Log:
Documented (a bit) the record generator.
Revision Changes Path
1.2 +1 -0 jakarta-poi/src/documentation/xdocs/hssf/book.xml
Index: book.xml
===================================================================
RCS file: /home/cvs/jakarta-poi/src/documentation/xdocs/hssf/book.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- book.xml 31 Jan 2002 02:23:39 -0000 1.1
+++ book.xml 9 Mar 2002 01:41:01 -0000 1.2
@@ -12,6 +12,7 @@
<menu label="HSSF">
<menu-item label="HOWTO" href="how-to.html"/>
<menu-item label="Use Case" href="use-case.html"/>
+ <menu-item label="Record Generator" href="record-generator.html"/>
</menu>
</book>
1.1 jakarta-poi/src/documentation/xdocs/hssf/record-generator.xml
Index: record-generator.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="[EMAIL PROTECTED]" 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>
