moparisthebest/poi
1
0
Fork 0
Code Issues Pull Requests Releases 1 Wiki Activity

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

Browse Source 
git-svn-id: https://svn.apache.org/repos/asf/jakarta/poi/trunk@542824 13f79535-47bb-0310-9956-ffa450edef68
This commit is contained in:
Nick Burch 2007-05-30 14:10:57 +00:00
parent 49a0737b06
commit 7d650aff0a
3 changed files with 96 additions and 26 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
src/documentation/content/xdocs/changes.xml
View File

@ -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>

74
src/documentation/content/xdocs/hssf/how-to.xml
View File

@ -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.
@ -264,15 +278,25 @@ 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>
<anchor id="event_api" />
<section><title>Event API</title>
<p>The event API is brand new. It is intended for intermediate
<p>The event API is newer than the User API. It is intended for intermediate
developers who are willing to learn a little bit of the low level API
structures. Its relatively simple to use, but requires a basic
understanding of the parts of an Excel file (or willingness to
learn). The advantage provided is that you can read an XLS with a
relatively small memory footprint.
</p>
<p>One important thing to note with the basic Event API is that it
triggers events only for things actually stored within the file.
With the XLS file format, it is quite common for things that
have yet to be edited to simply not exist in the file. This means
there may well be apparent "gaps" in the record stream, which
you either need to work around, or use the
<link href="#record_aware_event_api">Record Aware</link> extension
to the Event API.</p>
<p>To use this API you construct an instance of
org.apache.poi.hssf.eventmodel.HSSFRequest. Register a class you
create that supports the
@ -393,6 +417,50 @@ public class EventExample
}
]]></source>
</section>
<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
@ -509,8 +577,6 @@ yet. When it does something, we'll document it.</p>
</section>
</section>
</section>
</body>
</document>

2
src/documentation/content/xdocs/status.xml
View File

@ -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>