diff --git a/src/documentation/content/xdocs/changes.xml b/src/documentation/content/xdocs/changes.xml index 71dd43437..2ad37953b 100644 --- a/src/documentation/content/xdocs/changes.xml +++ b/src/documentation/content/xdocs/changes.xml @@ -36,6 +36,8 @@ + 42524 - [PATCH] Better HSLF support for problem shape groups + 42520 - [PATCH] Better HSLF support for corrupt picture records Initial support for a "missing record aware" HSSF event model Additional HSLF support for Title and Slide Master Sheets 42474 - [PATCH] Improved HSLF note to slide matching, and a NPE diff --git a/src/documentation/content/xdocs/hssf/how-to.xml b/src/documentation/content/xdocs/hssf/how-to.xml index e2a5a133a..b77e01751 100644 --- a/src/documentation/content/xdocs/hssf/how-to.xml +++ b/src/documentation/content/xdocs/hssf/how-to.xml @@ -25,6 +25,7 @@ + @@ -47,9 +48,22 @@ memory footprint.

+
Different APIs +

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.

+ +
+
General Use +
User API -
Writing a new one +
Writing a new file

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(); ]]>

-
Reading or modifying an existing file +
Reading or modifying an existing file

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.

org.apache.poi.hssf.dev.HSSF.

-
Event API -

The event API is brand new. 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. -

-

To use this API you construct an instance of - 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.

+ +
Event API + +

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

+

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 + Record Aware extension + to the Event API.

+

To use this API you construct an instance of + 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.

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 } ]]>

-
Low Level APIs + + +
Record Aware Event API +

+This is an experimental extension to the normal +Event API. 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. +

+

+There are three dummy records that your HSSFListener will be called with: +

+
    +
  • org.apache.poi.hssf.eventusermodel.dummyrecord.MissingRowDummyRecord +
    + 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.
    • +
  • org.apache.poi.hssf.eventusermodel.dummyrecord.MissingCellDummyRecord +
    + 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.
    • +
  • org.apache.poi.hssf.eventusermodel.dummyrecord.LastCellOfRowDummyRecord +
    + 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.
    • +
+

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

+

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

+
+ + +
Low Level APIs

The low level API is not much to look at. It consists of lots of "Records" in the org.apache.poi.hssf.record.* package, @@ -509,8 +577,6 @@ yet. When it does something, we'll document it.

-
-
diff --git a/src/documentation/content/xdocs/status.xml b/src/documentation/content/xdocs/status.xml index bba78a3f1..893038dcb 100644 --- a/src/documentation/content/xdocs/status.xml +++ b/src/documentation/content/xdocs/status.xml @@ -33,6 +33,8 @@ + 42524 - [PATCH] Better HSLF support for problem shape groups + 42520 - [PATCH] Better HSLF support for corrupt picture records Initial support for a "missing record aware" HSSF event model Additional HSLF support for Title and Slide Master Sheets 42474 - [PATCH] Improved HSLF note to slide matching, and a NPE