From 0fe419cb151953a5cf40ac6d3ad60a28cb44a557 Mon Sep 17 00:00:00 2001 From: Glen Stampoultzis Date: Wed, 9 Oct 2002 00:05:55 +0000 Subject: Some changes to record generation git-svn-id: https://svn.apache.org/repos/asf/jakarta/poi/trunk@352885 13f79535-47bb-0310-9956-ffa450edef68 --- src/documentation/xdocs/hssf/record-generator.xml | 140 +++++++++++++++++----- 1 file changed, 110 insertions(+), 30 deletions(-) (limited to 'src/documentation') diff --git a/src/documentation/xdocs/hssf/record-generator.xml b/src/documentation/xdocs/hssf/record-generator.xml index 503a1599c1..df5b95f6b6 100644 --- a/src/documentation/xdocs/hssf/record-generator.xml +++ b/src/documentation/xdocs/hssf/record-generator.xml @@ -1,5 +1,5 @@ - +
@@ -20,34 +20,37 @@

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. + record looked like and do all the boring and repetitive work.

- The record generator takes XML as input and produced the following + The record generator takes XML as input and produces the following output:

  • A Java file capabile of decoding and encoding the record.
    • -
  • A test class with provides a fill-in-the-blanks implementation of a test case - for ensuring the record operates as designed.
    • +
  • A test class that provides a fill-in-the-blanks implementation + of a test case for ensuring the record operates as + designed.

- 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. + 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.

The records themselves have the following general layout:

- The frame record indicates whether there is a border + + The frame record indicates whether there is a border around the displayed text of a chart. Glen Stampoultzis (glens at apache.org) @@ -56,22 +59,76 @@ - - ]]>

- 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'. + The following table details the allowable types and sizes for + the fields.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TypeSizeJava Type
int1byte
int2short
int4int
int8long
intvarwordarray of shorts
bits1A byte comprising of a bits (defined by the bit element) +
bits2An short comprising of a bits
bits4A int comprising of a bits
float8double
hbstringjava expressionString

The Java records are regenerated each time the record generator is run, however the test stubs are only created if the test stub does @@ -79,6 +136,29 @@ stubs but not the generated records.

+
+

+ Occationally 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. +

+

+ 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: +

+ + ]]> +

+ Where the class name specified after custom: is a + class implementing the interface CustomField. +

+

+ You can then implement the encoding yourself. +

+

The record generation works by taking an XML file and styling it @@ -89,23 +169,23 @@ See record.xsl, record_test.xsl, FieldIterator.java, RecordUtil.java, RecordGenerator.java

-
-

- 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. + There is a corresponding "type" generator for HDF. + See the HDF documentation for details.

+
+

- Currently the record generator is optimized to create Excel records. - It could be adapted to create Word records with a little poking - around. + 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-benifit 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.

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 + Java objects. The Java code for the record generation is currently quite messy with minimal comments.

-- cgit v1.2.3