<?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 V1.1//EN" "../dtd/document-v11.dtd">

<document>
  <header>
   <title>Jakarta POI - Record Generator HOWTO</title>
   <authors>
    <person email="poi-user@jakarta.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 defintition of what a
        record looked like and do all the boring stuff.  Thus the
        record generator was born.
        </p>
    </section>

    <section><title>Capabilities</title>
    <p>
        The record generator takes XML as input and produced the following
        output:
    </p>
    <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>
    </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 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>
            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>
            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>How it Works</title>
        <p>
            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>
            See record.xsl, record_test.xsl, FieldIterator.java, 
            RecordUtil.java, RecordGenerator.java
        </p>
    </section>
    <section><title>Limitations</title>
        <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.  
        </p>
    </section>
</section>
</body>
</document>
