The purpose of this document is to collect, analyze and define high-level requirements, user needs, and features of the second release of the POI project software. The POI project currently consists of the following components: the HSSF Serializer, the HSSF library and the POIFS library.

• The HSSF Serializer is a set of Java classes whose main class supports the Serializer interface from the Cocoon 2 project and outputs the serialized data in a format compatible with the spreadsheet program Microsoft Excel '97.
• The HSSF library is a set of classes for reading and writing Microsoft Excel 97 file format using pure Java.
• The POIFS library is a set of classes for reading and writing Microsoft's OLE 2 Compound Document format using pure Java.

By the completion of this release cycle the POI project will also include the HSSF Generator and the HDF library.

• The HSSF Generator will be responsible for using HSSF to read in the XLS (Excel 97) file format and create SAX events. The HSSF Generator will support the applicable interfaces specified by the Apache Cocoon 2 project.
• The HDF library will provide a set of high level interfaces for reading and writing Microsoft Word 97 file format using pure Java.

The first release of the POI project was an astounding success. This release seeks to build on that success by:

• Refactoring POIFS into imput and output classes as well as an event-driven API for reading.
• Refactor HSSF for greater performance as well as an event-driven API for reading
• Extend HSSF by adding the ability to read and write formulas.
• Extend HSSF by adding the ability to read and write user-defined styles.
• Create a Cocoon 2 Generator for HSSF using the same tags as the HSSF Serializer.
• Create a new library (HDF) for reading and writing Microsoft Word DOC format.
• Refactor the HSSFSerializer into a separate extensible POIFSSerializer and HSSFSerializer
• Providing the create excel charts. (write only)

There are a number of enthusiastic users of XML, UNIX and Java technology. Furthermore, the Microsoft solution for outputting Office Document formats often involves actually manipulating the software as an OLE Server. This method provides extremely low performance, extremely high overhead and is only capable of handing one document at a time.

1. Our intended audience for the HSSF Serializer portion of this project are developers writing reports or data extracts in XML format.
2. Our intended audience for the HSSF library portion of this project is ourselves as we are developing the HSSF serializer and anyone who needs to read and write Excel spreadsheets in a non-XML Java environment, or who has specific needs not addressed by the Serializer
3. Our intended audience for the POIFS library is ourselves as we are developing the HSSF and HDF libraries and anyone wishing to provide other libraries for reading/writing other file formats utilizing the OLE 2 Compound Document Format in Java.
4. Our intended audience for the HSSF generator are developers who need to export Excel spreadsheets to XML in a non-proprietary environment.
5. Our intended audience for the HDF library is ourselves, as we will be developing a HDF Serializer in a later release, and anyone wishing to add .DOC file processing and creation to their projects.

The users of this software shall be developers in a Java environment on any operating system, or power users who are capable of XML document generation/deployment.

The HSSF library currently requires a full object representation to be created before reading values. This results in very high memory utilization. We need to reduce this substantially for reading. It would be preferable to do this for writing, but it may not be possible due to the constraints imposed by the file format itself. Memory utilization during read is our top user complaint.

The POIFS library currently requires a full object representation to be created before reading values. This results in very high memory utilization. We need to reduce this substantially for reading.

The HSSF library currently ignores formula cells and identifies them as "UnknownRecord" at the lower level of the API. We must provide a way to read and write formulas. This is now the top requested feature.

The HSSF library currently does not support charts. This is a key requirement of some users who wish to use HSSF in a reporting engine.

The HSSF Serializer currently does not provide serialization for cell styling. User's will want stylish spreadsheets to result from their XML.

There is currently no way to generate the XML from an XLS that is consistent with the format used by the HSSF Serializer.

There should be a way to read and write the DOC file format using pure Java.

Originally there weren't any decent alternatives for reading or writing to Excel. This has changed somewhat.

The produced code shall be licensed by the Apache License as used by the Cocoon 2 project (APL 1.1) and maintained on at http://poi.sourceforge.net and http://sourcefoge.net/projects/poi. It is our hope to at some point integrate with the various Apache projects (xml.apache.org and jakarta.apache.org), at which point we'd turn the copyright over to them.

For developers on a Java and/or XML environment this project will provide all the tools necessary for outputting XML data in the Microsoft Excel format. This project seeks to make the use of Microsoft Windows based servers unnecessary for file format considerations and to fully document the OLE 2 Compound Document format. The project aims not only to provide the tools for serializing XML to Excel and Word file formats and the tools for writing to those file formats from Java, but also to provide the tools for later projects to convert other OLE 2 Compound Document formats to pure Java APIs.

HSSF Serializer for Apache Cocoon 2

• The HSSF Serializer and Generator will support the Gnumeric 1.0 XML tag language.
• The HSSF Generator and HSSF Serializer will be mutually validating. It should be possible to have an XLS file created by the Serializer run through the Generator and the output back through the Serializer (via the Cocoon pipeline) and get the same file or a reasonable facimille (no one cares if it differs by the order of the binary records in some minor but non-visually recognizable manner).
• The HSSF Generator will run on any Java 2 supporting platform with Apache Cocoon 2 installed along with the HSSF and POIFS APIs.
• The HSSF Serializer will run on any Java 2 supporting platform with Apache Cocoon 2 installed along with the HSSF and POIFS APIs.
• The HDF API requires a Java 2 implementation and the POIFS API.
• The HSSF API requires a Java 2 implementation and the POIFS API.
• The POIFS API requires a Java 2 implementation.

All Java code will be 100% pure Java.

The minimum system requirements for the POIFS API are:

• 64 Mbytes memory
• Java 2 environment
• Pentium or better processor (or equivalent on other platforms)

The minimum system requirements for the the HSSF API are:

• 64 Mbytes memory
• Java 2 environment
• Pentium or better processor (or equivalent on other platforms)
• POIFS API

The minimum system requirements for the the HDF API are:

• 64 Mbytes memory
• Java 2 environment
• Pentium or better processor (or equivalent on other platforms)
• POIFS API

The minimum system requirements for the HSSF Serializer are:

• 64 Mbytes memory
• Java 2 environment
• Pentium or better processor (or equivalent on other platforms)
• Cocoon 2
• HSSF API
• POI API

All components must perform well enough to be practical for use in a webserver environment (especially the "killer trio": Cocoon2/Tomcat/Apache combo)

The software will run primarily in developer environments. We should make some allowances for not-highly-technical users to write XML documents for the HSSF Serializer. All other components will assume intermediate Java 2 knowledge. No XML knowledge will be required except for using the HSSF Serializer. As much documentation as is practical shall be required for all components as XML is relatively new, and the concepts introduced for writing spreadsheets and to POI filesystems will be brand new to Java and many Java developers.

The filesystem as read and written by POI shall be fully documented and explained so that the average Java developer can understand it.

The POI API will be fully documented through Javadoc. A walkthrough of using the high level POI API shall be provided. No documentation outside of the Javadoc shall be provided for the low-level POI APIs.

The HSSF File Format as implemented by the HSSF API will be fully documented. No documentation will be provided for features that are not supported by HSSF API that are supported by the Excel 97 File Format. Care will be taken not to infringe on any "legal stuff". Additionally, we are collaborating with the fine folks at OpenOffice.org on *free* documentation of the format.

The HSSF API will be documented by javadoc. A walkthrough of using the high level HSSF API shall be provided. No documentation outside of the Javadoc shall be provided for the low level HSSF APIs.

The HDF API will be documented by javadoc. A walkthrough of using the high level HDF API shall be provided. No documentation outside of the Javadoc shall be provided for the low level HDF APIs.

The HSSF Serializer will be documented by javadoc.

The HSSF Generator will be documented by javadoc.

The XML tag language along with function and usage shall be fully documented. Examples will be provided as well.

filesystem shall refer only to the POI formatted archive.

file shall refer to the embedded data stream within a POI filesystem. This will be the actual embedded document.