Apache
/
poi
mirror of https://github.com/apache/poi.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

guess glen didn't add it to the site itself 

git-svn-id: https://svn.apache.org/repos/asf/jakarta/poi/trunk@352176 13f79535-47bb-0310-9956-ffa450edef68
This commit is contained in:
Andrew C. Oliver 2002-03-10 16:16:03 +00:00
parent 67d791280a
commit 07e88461d5
1 changed files with 292 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

292
build/jakarta-poi/docs/hssf/record-generator.html Normal file
View File

@ -0,0 +1,292 @@
<html>
<head>
<META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<title>Record Generator HOWTO</title>
</head>
<body bgcolor="#ffffff" marginheight="4" marginwidth="4" leftmargin="4" topmargin="4" alink="#023264" vlink="#023264" link="#525D76" text="#000000">
<table border="0" cellpadding="0" cellspacing="0" width="100%">
<tr>
<td align="left" valign="top"><a href="http://jakarta.apache.org/index.html"><img src="images/jakarta-logo.gif" border="0" vspace="0" hspace="0"></a></td><td bgcolor="#ffffff" align="left" valign="top" width="100%"><img src="images/header.gif" align="right" border="0" vspace="0" hspace="0"></td>
</tr>
<tr>
<td colspan="2" height="2" width="100%">
<hr size="1" noshade="">
</td>
</tr>
</table>
<table border="0" cellpadding="0" cellspacing="0" width="100%">
<tr>
<td valign="top" width="1%"></td><td nowrap="1" valign="top" width="14%">
<br>
<font face="arial,helvetica,sanserif">
<br>
<font size="+1" color="#000000">Navigation</font><font size="-1">
<ul>
<li>
<a href="../index.html"><font size="-1">Main</font></a>
</li>
</ul>
</font>
<br>
<font size="+1" color="#000000">HSSF</font><font size="-1">
<ul>
<li>
<a href="how-to.html"><font size="-1">HOWTO</font></a>
</li>
<li>
<a href="use-case.html"><font size="-1">Use Case</font></a>
</li>
<li>
<a href="diagrams.html"><font size="-1">Pictorial Docs</font></a>
</li>
</ul>
</font>
<br>
<font size="+1" color="#000000">Contributer's Guide</font><font size="-1">
<ul>
<li>
<a href="record-generator.html"><font size="-1">Record Generator</font></a>
</li>
</ul>
</font>
<br>
<br>
</font></td><td align="left" valign="top" width="*">
<title>Record Generator HOWTO</title>
<center>
<table width="80%">
<tr>
<td bgcolor="#F3DD61"><font face="Arial,sans-serif" size="+1">
<center>
<b>Record Generator HOWTO</b>
</center>
</font></td>
</tr>
</table>
</center>
<font size="-2" color="#000000">
<p>
<a href="mailto:"></a>
</p>
</font>
<br>
<div align="right">
<table cellspacing="0" cellpadding="2" border="0" width="100%">
<tr>
<td bgcolor="#525D76"><font color="#ffffff" size="+1"><font face="Arial,sans-serif"><b>How to Use the Record Generator</b></font></font></td>
</tr>
<tr>
<td>
<br>
<div align="right">
<table cellspacing="0" cellpadding="2" border="0" width="99%">
<tr>
<td bgcolor="#525D76"><font color="#ffffff" size="+0"><font face="Arial,sans-serif"><b>History</b></font></font></td>
</tr>
<tr>
<td>
<br>
<p align="justify">
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 align="justify">
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>
</td>
</tr>
</table>
</div>
<br>
<div align="right">
<table cellspacing="0" cellpadding="2" border="0" width="99%">
<tr>
<td bgcolor="#525D76"><font color="#ffffff" size="+0"><font face="Arial,sans-serif"><b>Capabilities</b></font></font></td>
</tr>
<tr>
<td>
<br>
<p align="justify">
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>
</td>
</tr>
</table>
</div>
<br>
<div align="right">
<table cellspacing="0" cellpadding="2" border="0" width="99%">
<tr>
<td bgcolor="#525D76"><font color="#ffffff" size="+0"><font face="Arial,sans-serif"><b>Usage</b></font></font></td>
</tr>
<tr>
<td>
<br>
<p align="justify">
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 align="justify">
The records themselves have the following general layout:
</p>
<div align="center">
<table cellspacing="2" cellpadding="2" border="1">
<tr>
<td>
<pre>
&lt;record id="0x1032" name="Frame" package="org.apache.poi.hssf.record"&gt;
&lt;description&gt;The frame record indicates whether there is a border
around the displayed text of a chart.&lt;/description&gt;
&lt;author&gt;Glen Stampoultzis (glens at apache.org)&lt;/author&gt;
&lt;fields&gt;
&lt;field type="int" size="2" name="border type"&gt;
&lt;const name="regular" value="0" description="regular rectangle or no border"/&gt;
&lt;const name="shadow" value="1" description="rectangle with shadow"/&gt;
&lt;/field&gt;
&lt;field type="int" size="2" name="options"&gt;
&lt;bit number="0" name="auto size"
description="excel calculates the size automatically if true"/&gt;
&lt;bit number="1" name="auto position"
description="excel calculates the position automatically"/&gt;
&lt;/field&gt;
&lt;/fields&gt;
&lt;/record&gt;
</pre>
</td>
</tr>
</table>
</div>
<p align="justify">
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 align="justify">
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>
</td>
</tr>
</table>
</div>
<br>
<div align="right">
<table cellspacing="0" cellpadding="2" border="0" width="99%">
<tr>
<td bgcolor="#525D76"><font color="#ffffff" size="+0"><font face="Arial,sans-serif"><b>How it Works</b></font></font></td>
</tr>
<tr>
<td>
<br>
<p align="justify">
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 align="justify">
See record.xsl, record_test.xsl, FieldIterator.java,
RecordUtil.java, RecordGenerator.java
</p>
</td>
</tr>
</table>
</div>
<br>
<div align="right">
<table cellspacing="0" cellpadding="2" border="0" width="99%">
<tr>
<td bgcolor="#525D76"><font color="#ffffff" size="+0"><font face="Arial,sans-serif"><b>Limitations</b></font></font></td>
</tr>
<tr>
<td>
<br>
<p align="justify">
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 align="justify">
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 align="justify">
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>
</td>
</tr>
</table>
</div>
<br>
</td>
</tr>
</table>
</div>
<br>
</td>
</tr>
</table>
<br>
<table cellpadding="0" cellspacing="0" border="0" width="100%">
<tr>
<td>
<hr size="1" noshade="">
</td>
</tr>
<tr>
<td align="center"><font color="#525D76" size="-1" face="arial,helvetica,sanserif"><i>
Copyright &copy;2002 Apache Software Foundation
</i></font></td><td width="5%" align="right"><img src="images/cocoon2-small.jpg" align="right" border="0" vspace="0" hspace="0"></td>
</tr>
</table>
</body>
</html>