blob: 39f328bc7889a492ccc4eea236939e5c0f1ccc1d (
plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
|
<?xml version="1.0" encoding="UTF-8"?>
<!--
====================================================================
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
====================================================================
-->
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN" "document-v20.dtd">
<document>
<header>
<title>Record Generator HOWTO</title>
<authors>
<person email="user@poi.apache.org" name="Glen Stampoultzis" id="glens"/>
<person email="acoliver@apache.org" name="Andrew C. Oliver" id="acoliver"/>
</authors>
</header>
<body>
<section><title>How to Use the Record Generator</title>
<section><title>History</title>
<p>
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>
A utility was needed to take the definition of what a
record looked like and do all the boring and repetitive work.
</p>
</section>
<section><title>Capabilities</title>
<p>
The record generator takes XML as input and produces the following
output:
</p>
<ul>
<li>A Java file capable of decoding and encoding the record.</li>
<li>A test class that provides a fill-in-the-blanks implementation
of a test case for ensuring the record operates as
designed.</li>
</ul>
</section>
<section><title>Usage</title>
<p>
The record generator is invoked as an Ant target
(generate-records). It goes through looking for all files in
<code>src/records/definitions</code> 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"
excel-record-id="FRAME">
<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 following table details the allowable types and sizes for
the fields.
</p>
<table>
<tr>
<th>Type</th>
<th>Size</th>
<th>Java Type</th>
</tr>
<tr>
<td>int</td>
<td>1</td>
<td>byte</td>
</tr>
<tr>
<td>int</td>
<td>2</td>
<td>short</td>
</tr>
<tr>
<td>int</td>
<td>4</td>
<td>int</td>
</tr>
<tr>
<td>int</td>
<td>8</td>
<td>long</td>
</tr>
<tr>
<td>int</td>
<td>varword</td>
<td>array of shorts</td>
</tr>
<tr>
<td>bits</td>
<td>1</td>
<td>A byte comprising of a bits (defined by the bit element)
</td>
</tr>
<tr>
<td>bits</td>
<td>2</td>
<td>An short comprising of a bits</td>
</tr>
<tr>
<td>bits</td>
<td>4</td>
<td>A int comprising of a bits</td>
</tr>
<tr>
<td>float</td>
<td>8</td>
<td>double</td>
</tr>
<tr>
<td>hbstring</td>
<td>java expression</td>
<td>String</td>
</tr>
</table>
<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>
</section>
<section><title>Custom Field Types</title>
<p>
Occasionally the builtin types are not enough. More control
over the encoding and decoding of the streams is required. This
can be achieved using a custom type.
</p>
<p>
A custom type lets you escape to java to define the way in which
the field encodes and decodes. To code a custom type you
declare your field like this:
</p>
<source><![CDATA[
<field type="custom:org.apache.poi.hssf.record.LinkedDataFormulaField"
size="var" name="formula of link" description="formula"/>
]]></source>
<p>
Where the class name specified after <code>custom:</code> is a
class implementing the interface <code>CustomField</code>.
</p>
<p>
You can then implement the encoding yourself.
</p>
</section>
<section><title>How it Works</title>
<p>
The record generation works by taking an XML file and styling it
using XSLT. 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
</p>
<p>
There is a corresponding "type" generator for HWPF.
See the HWPF documentation for details.
</p>
</section>
<section><title>Limitations</title>
<p>
The record generator does not handle all possible record types and
goes not intend to perform this function. When dealing with a
non-standard record sometimes the cost-benefit of coding the
record by hand will be greater than attempting modify the
generator. The main point of the record generator is to save
time, so keep that in mind.
</p>
<p>
Currently the XSL file that generates the record calls out to
Java objects. The Java code for the record generation is
currently quite messy with minimal comments.
</p>
</section>
</section>
</body>
</document>
|
