diff --git a/src/documentation/content/xdocs/spreadsheet/book.xml b/src/documentation/content/xdocs/spreadsheet/book.xml index 483b46e2f..7e8a59d7d 100644 --- a/src/documentation/content/xdocs/spreadsheet/book.xml +++ b/src/documentation/content/xdocs/spreadsheet/book.xml @@ -31,6 +31,7 @@ + diff --git a/src/documentation/content/xdocs/spreadsheet/converting.xml b/src/documentation/content/xdocs/spreadsheet/converting.xml new file mode 100644 index 000000000..98e2909c4 --- /dev/null +++ b/src/documentation/content/xdocs/spreadsheet/converting.xml @@ -0,0 +1,199 @@ + + + + + +
+ Converting existing HSSF Usermodel code to SS Usermodel (for XSSF and HSSF) + + + +
+ +
Converting existing HSSF Usermodel code to SS Usermodel (for XSSF and HSSF) + +
Why change? +

If you have existing HSSF usermodel code that works just + fine, and you don't want to use the new OOXML XSSF support, + then you probably don't need to. Your existing HSSF only code + will continue to work just fine.

+

However, if you want to be able to work with both HSSF for + your .xls files, and also XSSF for .xslx files, then you will + need to make some slight tweaks to your code.

+
+
org.apache.poi.ss.usermodel +

The new SS usermodel (org.apache.poi.ss.usermodel) is very + heavily based on the old HSSF usermodel + (org.apache.poi.hssf.usermodel). The main difference is that + the package name and class names have been tweaked to remove + HSSF from them. Otherwise, the new SS Usermodel interfaces + should provide the same functionality.

+
+
Constructors +

Calling the empty HSSFWorkbook remains as the way to + create a new, empty Workbook object. To open an existing + Worbook, you should now call WorkbookFactory.create(inp).

+

For all other cases when you would have called a + Usermodel constructor, such as 'new HSSFRichTextString()' or + 'new HSSFDataFormat', you should instead use a CreationHelper. + There's a method on the Workbook to get a CreationHelper, and + the CreationHelper will then handle constructing new objects + for you.

+
+
Other Code +

For all other code, generally change a reference from + org.apache.poi.hssf.usermodel.HSSFFoo to a reference to + org.apache.poi.ss.usermodel.Foo. Method signatures should + otherwise remain the same, and it should all then work for + both XSSF and HSSF.

+
+
+
Worked Examples +
Old HSSF Code + +
+
New, generic SS Usermodel Code + +
+
+ + diff --git a/src/documentation/content/xdocs/spreadsheet/index.xml b/src/documentation/content/xdocs/spreadsheet/index.xml index 4560d82d8..bddd79c6b 100644 --- a/src/documentation/content/xdocs/spreadsheet/index.xml +++ b/src/documentation/content/xdocs/spreadsheet/index.xml @@ -45,20 +45,26 @@
  • an eventmodel api for efficient read-only access
  • a full usermodel api for creating, reading and modifying XLS files
    • +

    For people converting from pure HSSF usermodel, who wish + to use the joint SS Usermodel for HSSF and XSSF support, then + see the ss usermodel converting + guide. +

    An alternate way of generating a spreadsheet is via the Cocoon serializer (yet you'll still be using HSSF indirectly). With Cocoon you can serialize any XML datasource (which might be a ESQL page outputting in SQL for instance) by simply applying the stylesheet and designating the serializer.

    - If you're merely reading spreadsheet data, then use the eventmodel api - in the org.apache.poi.hssf.eventusermodel package. + If you're merely reading spreadsheet data, then use the + eventmodel api in either the org.apache.poi.hssf.eventusermodel + package, or the org.apache.poi.xssf.eventusermodel package, depending + on your file format.

    If you're modifying spreadsheet data then use the usermodel api. You can also generate spreadsheets this way.

    -