583 lines
21 KiB
XML
583 lines
21 KiB
XML
<?xml version="1.0" encoding="UTF-8"?>
|
|
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "document-v11.dtd">
|
|
|
|
<document>
|
|
<header>
|
|
<title>POI 2.0 Vision Document</title>
|
|
<authors>
|
|
<person name="Andrew C. Oliver" email="acoliver2@users.sourceforge.net"/>
|
|
<person name="Marcus W. Johnson" email="mjohnson@apache.org"/>
|
|
<person name="Glen Stampoultzis" email="gstamp@iprimus.com.au"/>
|
|
<person name="Nicola Ken Barozzi" email="barozzi@nicolaken.com"/>
|
|
</authors>
|
|
</header>
|
|
|
|
<body>
|
|
|
|
<section><title>Preface</title>
|
|
<p>
|
|
This is the POI 2.0 cycle vision document. Although the vision
|
|
has not changed and this document is certainly not out of date and
|
|
the vision has not changed, the structure of the project has
|
|
changed a bit. We're not going to change the vision document to
|
|
reflect this (however proper that may be) because it would only
|
|
involve deletion. There is no purpose in providing less
|
|
information provided we give clarification.
|
|
</p>
|
|
<p>
|
|
This document was created before the POI components for
|
|
<link href="http://xml.apache.org/cocoon">Apache Cocoon</link>
|
|
were accepted into the Cocoon project itself. It was also
|
|
written before POI was accepted into Jakarta. So while the
|
|
vision hasn't changed some of the components are actually now
|
|
part of other projects. We'll still be working on them on the
|
|
same timeline roughly (minus the overhead of coordination with
|
|
other groups), but they are no longer technically part of the
|
|
POI project itself.
|
|
</p>
|
|
</section>
|
|
|
|
<section><title>1. Introduction</title>
|
|
<section><title>1.1 Purpose of this document</title>
|
|
<p>
|
|
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.
|
|
</p>
|
|
<ul>
|
|
<li>
|
|
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.
|
|
</li>
|
|
<li>
|
|
The HSSF library is a set of classes for reading and
|
|
writing Microsoft Excel 97 file format using pure Java.
|
|
</li>
|
|
<li>
|
|
The POIFS library is a set of classes for reading and
|
|
writing Microsoft's OLE 2 Compound Document format using
|
|
pure Java.
|
|
</li>
|
|
</ul>
|
|
<p>By the completion of this release cycle the POI project will also
|
|
include the HSSF Generator and the HDF library.
|
|
</p>
|
|
<ul>
|
|
<li>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.
|
|
</li>
|
|
<li>The HDF library will provide a set of high level interfaces
|
|
for reading and writing Microsoft Word 97 file format using pure
|
|
Java.</li>
|
|
</ul>
|
|
|
|
</section>
|
|
|
|
|
|
<section><title>1.2 Project Overview</title>
|
|
<p>
|
|
The first release of the POI project
|
|
was an astounding success. This release seeks to build on that
|
|
success by:
|
|
</p>
|
|
<ul>
|
|
<li>
|
|
Refactoring POIFS into imput and
|
|
output classes as well as an event-driven API for reading.
|
|
</li>
|
|
<li>
|
|
Refactor HSSF for greater
|
|
performance as well as an event-driven API for reading
|
|
</li>
|
|
<li>
|
|
Extend HSSF by adding the ability to read and write formulas.
|
|
</li>
|
|
<li>
|
|
Extend HSSF by adding the ability to read and write
|
|
user-defined styles.
|
|
</li>
|
|
<li>
|
|
Create a Cocoon 2 Generator for HSSF using the same tags
|
|
as the HSSF Serializer.
|
|
</li>
|
|
<li>
|
|
Create a new library (HDF) for reading and writing
|
|
Microsoft Word DOC format.
|
|
</li>
|
|
<li>
|
|
Refactor the HSSFSerializer into a separate extensible
|
|
POIFSSerializer and HSSFSerializer
|
|
</li>
|
|
<li>
|
|
Providing the create excel charts. (write only)
|
|
</li>
|
|
</ul>
|
|
</section>
|
|
</section>
|
|
<section><title>2. User Description</title>
|
|
<section><title>2.1 User/Market Demographics</title>
|
|
<p>
|
|
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.
|
|
</p>
|
|
<ol>
|
|
<li>
|
|
Our intended audience for the HSSF
|
|
Serializer portion of this project are developers writing reports or
|
|
data extracts in XML format.
|
|
</li>
|
|
<li>
|
|
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
|
|
</li>
|
|
<li>
|
|
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.
|
|
</li>
|
|
<li>
|
|
Our intended audience for the HSSF
|
|
generator are developers who need to export Excel spreadsheets to
|
|
XML in a non-proprietary environment.
|
|
</li>
|
|
<li>
|
|
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.
|
|
</li>
|
|
</ol>
|
|
</section>
|
|
<section><title>2.2. User environment</title>
|
|
<p>
|
|
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.
|
|
</p>
|
|
</section>
|
|
<section><title>2.3. Key User Needs</title>
|
|
<p>
|
|
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.
|
|
</p>
|
|
<p>
|
|
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.
|
|
</p>
|
|
<p>
|
|
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.
|
|
</p>
|
|
<p>
|
|
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.
|
|
</p>
|
|
<p>
|
|
The HSSF Serializer currently does not
|
|
provide serialization for cell styling. User's will want stylish
|
|
spreadsheets to result from their XML.
|
|
</p>
|
|
<p>
|
|
There is currently no way to generate
|
|
the XML from an XLS that is consistent with the format used by the
|
|
HSSF Serializer.
|
|
</p>
|
|
<p>
|
|
There should be a way to read and write
|
|
the DOC file format using pure Java.
|
|
</p>
|
|
|
|
</section>
|
|
<section><title>2.4. Alternatives and Competition</title>
|
|
<p>
|
|
Originally there weren't any decent <link href="../hssf/alternatives.html">alternatives</link> for reading or writing
|
|
to Excel. This has changed somewhat.
|
|
</p>
|
|
</section>
|
|
</section>
|
|
<section><title>3. Project Overview</title>
|
|
<section><title>3.1. Project Perspective</title>
|
|
<p>
|
|
The produced code shall be licensed by
|
|
the Apache License as used by the Cocoon 2 project (APL 1.1) and
|
|
maintained on at <link href="http://poi.sourceforge.net/">http://poi.sourceforge.net</link>
|
|
and <link href="http://sourcefoge.net/projects/poi">http://sourcefoge.net/projects/poi</link>.
|
|
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.
|
|
</p>
|
|
</section>
|
|
<section><title>3.2. Project Position Statement</title>
|
|
<p>
|
|
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.
|
|
</p>
|
|
</section>
|
|
<section><title>3.3. Summary of Capabilities</title>
|
|
<p>
|
|
HSSF Serializer for Apache Cocoon 2
|
|
</p>
|
|
<table>
|
|
<tr>
|
|
<th>
|
|
Benefit
|
|
</th>
|
|
<th>
|
|
Supporting Features
|
|
</th>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
Ability to serialize styles from XML spreadsheets.
|
|
</td>
|
|
<td>
|
|
HSSFSerialzier will support styles.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
Ability to read and write formulas in XLS files.
|
|
</td>
|
|
<td>
|
|
HSSF will support reading/writing formulas.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
Ability to output in MS Word on any platform using Java.
|
|
</td>
|
|
<td>
|
|
The project will develop an API that outputs in Word format
|
|
using pure Java.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
Enhance performance for reading and writing XLS files.
|
|
</td>
|
|
<td>
|
|
HSSF will undergo a number of performance enhancements. HSSF
|
|
will include a new event-based API for reading XLS files. POIFS
|
|
will support a new event-based API for reading OLE2 CDF files.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
Ability to generate XML from XLS files
|
|
</td>
|
|
<td>
|
|
The project will develop an HSSF Generator.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
The ability to generate charts
|
|
</td>
|
|
<td>
|
|
HSSF will provide low level support for chart records as well
|
|
as high level API support for generating charts. The ability
|
|
to read chart information will not initially be provided.
|
|
</td>
|
|
</tr>
|
|
|
|
</table>
|
|
</section>
|
|
<section><title>3.4. Assumptions and Dependencies</title>
|
|
<ul>
|
|
<li>
|
|
The HSSF Serializer and Generator
|
|
will support the Gnumeric 1.0 XML tag language.
|
|
</li>
|
|
<li>
|
|
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).
|
|
</li>
|
|
<li>
|
|
The HSSF Generator will run on any
|
|
Java 2 supporting platform with Apache Cocoon 2 installed along with
|
|
the HSSF and POIFS APIs.
|
|
</li>
|
|
<li>
|
|
The HSSF Serializer will run on
|
|
any Java 2 supporting platform with Apache Cocoon 2 installed along
|
|
with the HSSF and POIFS APIs.
|
|
</li>
|
|
<li>
|
|
The HDF API requires a Java 2
|
|
implementation and the POIFS API.
|
|
</li>
|
|
<li>
|
|
The HSSF API requires a Java 2
|
|
implementation and the POIFS API.
|
|
</li>
|
|
<li>
|
|
The POIFS API requires a Java 2
|
|
implementation.
|
|
</li>
|
|
|
|
</ul>
|
|
</section>
|
|
</section>
|
|
<section><title>4. Project Features</title>
|
|
<p>
|
|
Enhancements to the POIFS API will
|
|
include:
|
|
</p>
|
|
<ul>
|
|
<li>
|
|
An event driven API for reading
|
|
POIFS Filesystems.
|
|
</li>
|
|
<li>
|
|
A low-level API for
|
|
creating/manipulating POI filesystems.
|
|
</li>
|
|
<li>
|
|
Code improvements supporting
|
|
greater separation between read and write structures.
|
|
</li>
|
|
</ul>
|
|
<p>
|
|
Enhancements to the HSSF API will
|
|
include:
|
|
</p>
|
|
<ul>
|
|
<li>
|
|
An event driven API for reading
|
|
XLS files.
|
|
</li>
|
|
<li>
|
|
Performance improvements.
|
|
</li>
|
|
<li>
|
|
Formula support (read/write)
|
|
</li>
|
|
<li>
|
|
Support for user-defined data
|
|
formats
|
|
</li>
|
|
<li>
|
|
Better documentation of the file
|
|
format and structure.
|
|
</li>
|
|
<li>
|
|
An API for creation of charts.
|
|
</li>
|
|
</ul>
|
|
<p>
|
|
The HSSF Generator will include:
|
|
</p>
|
|
<ul>
|
|
<li>
|
|
A set of classes supporting the
|
|
Cocoon 2 Generator interfaces providing a method for reading XLS
|
|
files and outputting SAX events.
|
|
</li>
|
|
<li>
|
|
The same tag format used by the
|
|
HSSFSerializer in any given release.
|
|
</li>
|
|
</ul>
|
|
<p>
|
|
The HDF API will include:
|
|
</p>
|
|
<ul>
|
|
<li>
|
|
An event driven API for reading
|
|
DOC files.
|
|
</li>
|
|
<li>
|
|
A set of high and low level APIs
|
|
for reading and writing DOC files.
|
|
</li>
|
|
<li>
|
|
Documentation of the DOC file
|
|
format or enhancements to existing documentation.
|
|
</li>
|
|
</ul>
|
|
</section>
|
|
<section><title>5. Other Product Requirements</title>
|
|
<section><title>5.1. Applicable Standards</title>
|
|
<p>
|
|
All Java code will be 100% pure Java.
|
|
</p>
|
|
</section>
|
|
<section><title>5.2. System Requirements</title>
|
|
<p>
|
|
The minimum system requirements for the POIFS API are:
|
|
</p>
|
|
<ul>
|
|
<li>64 Mbytes memory</li>
|
|
<li>Java 2 environment</li>
|
|
<li>Pentium or better processor (or equivalent on other platforms)</li>
|
|
</ul>
|
|
<p>
|
|
The minimum system requirements for the the HSSF API are:
|
|
</p>
|
|
<ul>
|
|
<li>64 Mbytes memory</li>
|
|
<li>Java 2 environment</li>
|
|
<li>Pentium or better processor (or equivalent on other platforms)</li>
|
|
<li>POIFS API</li>
|
|
</ul>
|
|
<p>
|
|
The minimum system requirements for the the HDF API are:
|
|
</p>
|
|
<ul>
|
|
<li>64 Mbytes memory</li>
|
|
<li>Java 2 environment</li>
|
|
<li>Pentium or better processor (or equivalent on other platforms)</li>
|
|
<li>POIFS API</li>
|
|
</ul>
|
|
|
|
<p>
|
|
The minimum system requirements for the HSSF Serializer are:
|
|
</p>
|
|
<ul>
|
|
<li>64 Mbytes memory</li>
|
|
<li>Java 2 environment</li>
|
|
<li>Pentium or better processor (or equivalent on other platforms)</li>
|
|
<li>Cocoon 2</li>
|
|
<li>HSSF API</li>
|
|
<li>POI API</li>
|
|
</ul>
|
|
</section>
|
|
<section><title>5.3. Performance Requirements</title>
|
|
<p>
|
|
All components must perform well enough
|
|
to be practical for use in a webserver environment (especially
|
|
the "killer trio": Cocoon2/Tomcat/Apache combo)
|
|
</p>
|
|
</section>
|
|
<section><title>5.4. Environmental Requirements</title>
|
|
<p>
|
|
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.
|
|
</p>
|
|
</section>
|
|
</section>
|
|
<section><title>6. Documentation Requirements</title>
|
|
<section><title>6.1 POI Filesystem</title>
|
|
<p>
|
|
The filesystem as read and written by
|
|
POI shall be fully documented and explained so that the average Java
|
|
developer can understand it.
|
|
</p>
|
|
</section>
|
|
<section><title>6.2. POI API</title>
|
|
<p>
|
|
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.
|
|
</p>
|
|
</section>
|
|
<section><title>6.3. HSSF File Format</title>
|
|
<p>
|
|
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.
|
|
</p>
|
|
</section>
|
|
<section><title>6.4. HSSF API</title>
|
|
<p>
|
|
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.
|
|
</p>
|
|
</section>
|
|
<section><title>6.5 HDF API</title>
|
|
<p>
|
|
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.
|
|
</p>
|
|
</section>
|
|
<section><title>6.6 HSSF Serializer</title>
|
|
<p>
|
|
The HSSF Serializer will be documented
|
|
by javadoc.
|
|
</p>
|
|
</section>
|
|
<section><title>6.7 HSSF Generator</title>
|
|
<p>
|
|
The HSSF Generator will be documented
|
|
by javadoc.
|
|
</p>
|
|
</section>
|
|
<section><title>6.8 HSSF Serializer Tag language</title>
|
|
<p>
|
|
The XML tag language along with
|
|
function and usage shall be fully documented. Examples will be
|
|
provided as well.
|
|
</p>
|
|
</section>
|
|
</section>
|
|
<section><title>7. Terminology</title>
|
|
<section><title>7.1 Filesystem</title>
|
|
<p>
|
|
filesystem shall refer only to the POI formatted archive.
|
|
</p>
|
|
</section>
|
|
<section><title>7.2 File</title>
|
|
<p>
|
|
file shall refer to the embedded data stream within a
|
|
POI filesystem. This will be the actual embedded document.
|
|
</p>
|
|
</section>
|
|
</section>
|
|
</body>
|
|
</document>
|