A couple more bug fixes for the changelog, and add documentation on the missing record aware event api code

git-svn-id: https://svn.apache.org/repos/asf/jakarta/poi/trunk@542824 13f79535-47bb-0310-9956-ffa450edef68

src/documentation/content/xdocs/changes.xml

@@ -36,6 +36,8 @@
     </devs>
 
         <release version="3.0.1-FINAL" date="2007-06-08">
+            <action dev="POI-DEVELOPERS" type="fix">42524 - [PATCH] Better HSLF support for problem shape groups</action>
+            <action dev="POI-DEVELOPERS" type="fix">42520 - [PATCH] Better HSLF support for corrupt picture records</action>
             <action dev="POI-DEVELOPERS" type="add">Initial support for a "missing record aware" HSSF event model</action>
             <action dev="POI-DEVELOPERS" type="add">Additional HSLF support for Title and Slide Master Sheets</action>
             <action dev="POI-DEVELOPERS" type="fix">42474 - [PATCH] Improved HSLF note to slide matching, and a NPE</action>

src/documentation/content/xdocs/hssf/how-to.xml

@@ -25,6 +25,7 @@
         <authors>
             <person email="acoliver2@users.sourceforge.net" name="Andrew C. Oliver" id="AO"/>
             <person email="poi-user@jakarta.apache.org" name="Glen Stampoultzis" id="GJS"/>
+            <person email="nick@apache.org" name="Nick Burch" id="NB"/>
             <person email="sergeikozello@mail.ru" name="Sergei Kozello" id="SK"/>
         </authors>
     </header>
@@ -47,9 +48,22 @@
               memory footprint. 
               </p>
         </section>
+        <section><title>Different APIs</title>
+           <p>There are a few different ways to access the HSSF API. These
+              have different characteristics, so you should read up on
+              all to select the best for you.</p>
+           <ul>
+             <li><link href="#user_api">User API</link></li>
+             <li><link href="#event_api">Event API</link></li>
+             <li><link href="#record_aware_event_api">Event API with extensions to be Record Aware</link></li>
+             <li><link href="#low_level_api">Low Level API</link></li>
+           </ul>
+        </section>
+    </section>
     <section><title>General Use</title>
+        <anchor id="user_api" />
         <section><title>User API</title>
-                <section><title>Writing a new one</title>
+                <section><title>Writing a new file</title>
 
                     <p>The high level API (package: org.apache.poi.hssf.usermodel)
                     is what most people should use. Usage is very simple.
@@ -245,7 +259,7 @@ wb.write(out);
 out.close();
         ]]></source>
         </section>
-                <section><title>Reading or modifying an existing file</title>
+        <section><title>Reading or modifying an existing file</title>
 
 <p>Reading in a file is equally simple. To read in a file, create a
 new instance of org.apache.poi.poifs.Filesystem, passing in an open InputStream, such as a FileInputStream
@@ -264,28 +278,38 @@ call workbook.write(outputstream) just as you did above.</p>
 <link href="http://svn.apache.org/repos/asf/jakarta/poi/trunk/src/java/org/apache/poi/hssf/dev/HSSF.java">org.apache.poi.hssf.dev.HSSF</link>.</p>
          </section>
         </section>
-                <section><title>Event API</title>
 
-                    <p>The event API is brand new.  It is intended for intermediate
+        <anchor id="event_api" />
-                    developers who are willing to learn a little bit of the low level API
+        <section><title>Event API</title>
-                    structures.  Its relatively simple to use, but requires a basic
+
-                    understanding of the parts of an Excel file (or willingness to
+          <p>The event API is newer than the User API.  It is intended for intermediate
-                    learn).  The advantage provided is that you can read an XLS with a
+             developers who are willing to learn a little bit of the low level API
-                    relatively small memory footprint.
+             structures.  Its relatively simple to use, but requires a basic
-                    </p>
+             understanding of the parts of an Excel file (or willingness to
-                    <p>To use this API you construct an instance of
+             learn).  The advantage provided is that you can read an XLS with a
-                    org.apache.poi.hssf.eventmodel.HSSFRequest. Register a class you
+             relatively small memory footprint.
-                    create that supports the
+          </p>
-                    org.apache.poi.hssf.eventmodel.HSSFListener interface using the
+          <p>One important thing to note with the basic Event API is that it
-                    HSSFRequest.addListener(yourlistener, recordsid).  The recordsid
+             triggers events only for things actually stored within the file.
-                    should be a static reference number (such as BOFRecord.sid) contained
+             With the XLS file format, it is quite common for things that
-                    in the classes in org.apache.poi.hssf.record.  The trick is you
+             have yet to be edited to simply not exist in the file. This means
-                    have to know what these records are.  Alternatively you can call
+             there may well be apparent "gaps" in the record stream, which
-                    HSSFRequest.addListenerForAllRecords(mylistener).  In order to learn
+             you either need to work around, or use the
-                    about these records you can either read all of the javadoc in the
+             <link href="#record_aware_event_api">Record Aware</link> extension
-                    org.apache.poi.hssf.record package or you can just hack up a
+             to the Event API.</p>
-                    copy of org.apache.poi.hssf.dev.EFHSSF and adapt it to your
+          <p>To use this API you construct an instance of
-                    needs.  TODO: better documentation on records.</p>
+			 org.apache.poi.hssf.eventmodel.HSSFRequest. Register a class you
+ 			 create that supports the
+ 			 org.apache.poi.hssf.eventmodel.HSSFListener interface using the
+ 			 HSSFRequest.addListener(yourlistener, recordsid).  The recordsid
+			 should be a static reference number (such as BOFRecord.sid) contained
+			 in the classes in org.apache.poi.hssf.record.  The trick is you
+			 have to know what these records are.  Alternatively you can call
+			 HSSFRequest.addListenerForAllRecords(mylistener).  In order to learn
+			 about these records you can either read all of the javadoc in the
+			 org.apache.poi.hssf.record package or you can just hack up a
+			 copy of org.apache.poi.hssf.dev.EFHSSF and adapt it to your
+			 needs.  TODO: better documentation on records.</p>
                     <p>Once you've registered your listeners in the HSSFRequest object
                     you can construct an instance of
                     org.apache.poi.poifs.filesystem.FileSystem (see POIFS howto) and
@@ -393,7 +417,51 @@ public class EventExample
 }
 ]]></source>
      </section>
-                <section><title>Low Level APIs</title>
+
+     <anchor id="record_aware_event_api" />
+     <section><title>Record Aware Event API</title>
+<p>
+This is an experimental extension to the normal 
+<link href="#event_api">Event API</link>. With this, your listener
+will be called with extra, dummy records. These dummy records should
+alert you to records which aren't present in the file (eg cells that have
+yet to be edited), and allow you to handle these.
+</p>
+<p>
+There are three dummy records that your HSSFListener will be called with:
+</p>
+<ul>
+ <li>org.apache.poi.hssf.eventusermodel.dummyrecord.MissingRowDummyRecord
+   <br />
+   This is called during the row record phase (which typically occurs before
+   the cell records), and indicates that the row record for the given
+   row is not present in the file.</li>
+ <li>org.apache.poi.hssf.eventusermodel.dummyrecord.MissingCellDummyRecord
+   <br />
+   This is called during the cell record phase. It is called when a cell
+   record is encountered which leaves a gap between it an the previous one.
+   You can get multiple of these, before the real cell record.</li>
+ <li>org.apache.poi.hssf.eventusermodel.dummyrecord.LastCellOfRowDummyRecord
+   <br />
+   This is called after the last cell of a given row. It indicates that there
+   are no more cells for the row, and also tells you how many cells you have
+   had. For a row with no cells, this will be the only record you get.</li>
+</ul>
+<p>
+To use the Record Aware Event API, you should create an
+org.apache.poi.hssf.eventusermodel.MissingRecordAwareHSSFListener, and pass
+it your HSSFListener. Then, register the MissingRecordAwareHSSFListener
+to the event model, and start that as normal.
+</p>
+<p>
+<em>This code is currently in the scratchpad section, so you will either
+ need to include the scratchpad jar on your classpath, or build from a</em>
+ <link href="../subversion.html">subversion checkout</link>.
+</p>
+     </section>
+
+     <anchor id="low_level_api" />
+     <section><title>Low Level APIs</title>
 
 <p>The low level API is not much to look at. It consists of lots of
 &quot;Records&quot; in the org.apache.poi.hssf.record.* package,
@@ -509,8 +577,6 @@ yet. When it does something, we'll document it.</p>
 
      </section>
 
-</section>
-
 </section>
 </body>
 </document>

src/documentation/content/xdocs/status.xml

@@ -33,6 +33,8 @@
 
     <changes>
         <release version="3.0.1-FINAL" date="2007-06-08">
+            <action dev="POI-DEVELOPERS" type="fix">42524 - [PATCH] Better HSLF support for problem shape groups</action>
+            <action dev="POI-DEVELOPERS" type="fix">42520 - [PATCH] Better HSLF support for corrupt picture records</action>
             <action dev="POI-DEVELOPERS" type="add">Initial support for a "missing record aware" HSSF event model</action>
             <action dev="POI-DEVELOPERS" type="add">Additional HSLF support for Title and Slide Master Sheets</action>
             <action dev="POI-DEVELOPERS" type="fix">42474 - [PATCH] Improved HSLF note to slide matching, and a NPE</action>