POI 1.0 Vision Document

Date: Thu, 1 May 2003 23:35:19 +0000 Subject: These should have been removed during the merge. git-svn-id: https://svn.apache.org/repos/asf/jakarta/poi/trunk@353075 13f79535-47bb-0310-9956-ffa450edef68 --- src/documentation/xdocs/plan/POI10Vision.xml | 509 ----------------------- src/documentation/xdocs/plan/POI20Vision.xml | 582 --------------------------- src/documentation/xdocs/plan/book.xml | 20 - src/documentation/xdocs/plan/index.xml | 58 --- src/documentation/xdocs/plan/release.xml | 63 --- 5 files changed, 1232 deletions(-) delete mode 100644 src/documentation/xdocs/plan/POI10Vision.xml delete mode 100644 src/documentation/xdocs/plan/POI20Vision.xml delete mode 100644 src/documentation/xdocs/plan/book.xml delete mode 100644 src/documentation/xdocs/plan/index.xml delete mode 100644 src/documentation/xdocs/plan/release.xml (limited to 'src/documentation/xdocs/plan') diff --git a/src/documentation/xdocs/plan/POI10Vision.xml b/src/documentation/xdocs/plan/POI10Vision.xml deleted file mode 100644 index b2b8c6c3e2..0000000000 --- a/src/documentation/xdocs/plan/POI10Vision.xml +++ /dev/null @@ -1,509 +0,0 @@ - - - - -

- POI 1.0 Vision Document - - - - -

- - - -

- (21-Jan-02) While this document is just full of useful project - introductory information and I do suggest those interested in getting - involved in the project read it, it is woefully out of date. -

- We deliberately allowed this document to run out of date because it - is a good reflection of what the original vision was for POI 1.0. - You'll note that some of the terminology is not used in quite the same - way any longer. I've made some minor corrections where reading this - confused me. An example: in some places this document may refer to - POI API instead of POIFS API. When this vision was written we had - an incomplete understanding of the project. -

- Lastly, the scope of the project expanded dramatically near the end - of the 1.0 cycle. Our vision at the time was to focus merely on the - Excel port (having no idea how the project would grow or be received) - and provide the OLE 2 Compound Document port for others to port later - formats. We now plan to spearhead these ports under the umbrella of - the POI project. So, you've been warned. Read on, but just realize - that we had a fuzzy view of things to come, and hindsight is 20-20. -

- If I recall major holes were: a complete understanding of the format - of OLE 2 Compound Document format, Excel file format, and exactly how - Cocoon 2 Serializers worked. (that just about covers the whole range - huh?) -

- -

- The purpose of this document is to - collect, analyze and define high-level requirements, user needs and - features of the HSSF Serializer for Cocoon 2 and related libraries. - The HSSF Serializer is a java class supporting the Serializer - interface from the Cocoon 2 project and outputting in a compatible - format of that used by the spreadsheet program Microsoft Excel '97. - The HSSF Serializer will be responsible for converting XML - spreadsheet-like documents into Excel-compatible XLS spreadsheets. -

- - -

- Many web apps today hit a brick wall - when it comes to the user request that they be able to easily - manipulate their reports and data extracts in the popular Microsoft - Excel spreadsheet format. This often causes inferior technologies to be - chosen for the project simply because they easily support this - format. This project seeks to extend existing XML, Java and Apache - Cocoon 2 project technologies by: -

- -

- providing an extensible library - (POIFS) which reads/writes in a compatable format to OLE 2 Compound - Document Format (aka Structured Storage Format) for easy - implementation of other document types; -
- providing a library (HSSF) for - manipulating spreadsheet data and outputting it in a compatible - format to Microsoft Excel XLS format; -
- and providing a Cocoon 2 - Serializer (HSSFSerializer) for serializing XML documents as - Excel-compatible spreadsheets. -

- -

- There are a number of enthusiastic - users of XML, UNIX and Java technology. Secondly, 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 handling one document at a time. -

- Our intended audience for the HSSF - Serializer portion of this project are developers writing reports or - data extracts in XML format. -
- Our intended audience for the HSSF - library portion of this project is ourselves as we are developing - the Serializer and anyone who needs to write to Excel spreadsheets - in a non-XML Java environment or who has specific needs not - addressed by the Serializer. -
- Our intended audience for the - "POIFS" OLE 2 Compound Document format reader/writer is - ourselves as we are writing the HSSF library and secondly, anyone - wishing to provide other libraries for reading/writing OLE 2 - Compound Document Format in Java. -

- 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 OLE 2 Compound Document format is - undocumented for all practical purposes and cryptic for all - impractical purposes. Developer needs in this area include - documentation and an easy to use library for reading and writing in - this format without requiring the developer to have intimate - knowledge of the format. -

- There is currently no good way to write - to Microsoft Excel documents from Java or from a non-Microsoft - Windows based platform for that matter. Developers need an easy to - use library that supports a reasonable feature set and allows - seperation of data from formatting/stylistic concerns. -

- There is currently no good way to - transform XML data to Microsoft Excel. Apache's Cocoon 2 project - supplies a complete framework for XML, but nothing for outputting in - Excel's XLS format. Developers and power users alike need a simple - method to output XML documents to Excel through server-side - processing. -

- - -

- 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 and maintained on - a project page until such time as the Cocoon 2 developers accept it - as a donation (at which time the copyright will be turned 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's file format and the tools for writing to - that file format 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 -

- - - - - - - - - - - - - - - - - - - - - -

- Benefit -	- Supporting Features -
- Standard XML tag language for sheet data -	- Serializer will transform documents utilizing a defined tag - language -
- Utilize XML to output in Excel -	- Serializer will output in Excel -
- Java API to output in Excel on any platform -	- The project will develop an API that outputs in Excel using - pure Java. -
- Make it easy for developers to port other OLE 2 Compound - Document-based formats to Java. -	- The POIFS library will contain both a high-level abstraction - along with low-level constructs. The project will fully document - the OLE 2 Compound Document Format. -

- The HSSF Serializer will run on - any Java 2 supporting platform with Apache Cocoon 2 installed along - with the HSSF and POIFS APIs. -
- The HSSF API requires a Java 2 - implementation and the POI API. -
- The POIFS API requires a Java 2 - implementation. -

- The POIFS API will include: -

- Low level structures representing - the structures in a POI filesystems. -
- A low-level API for - creating/manipulating POI filesystems. -
- A set of high level interfaces - abstracting the user from the POI filesystem constructs and - representing it as a standard filesystem (Files, directories, etc) -

- The HSSF API will include: -

- Low level structures representing - the structures in an Excel file. -
- A low-level API for creating and - manipulating Excel files and writing them into POI filesystems. -
- A high level model and style - interface for manipulating spreadsheet data without knowing anything - about the Excel format itself. -

- The POI Filesystem API includes: -

An implementation of Big Blocks
An implementation of Small Blocks
An implementation of Header Blocks
An implementation of Block Allocation Tables
An implementation of Property Sets
An implementation of the POI - filesystem including functions to get and set the above constructs; - compound functions for reading/writing files/directories. -
An abstraction of the POI - filesystem providing interfaces representing Files, Directories, - FileSystems in normal terminology and encapulating the above - constructs. -
Full documentation of the POI file - format. -
Full documentation of the APIs and - interfaces provided through Javadoc, user documentation (aimed at - developers using the APIs) -
Examples aimed at teaching the - user to write code using POI. (titled: recipes for POI) -
Performance specifications. - (Example POI filesystems rated by some measure of complexity along - with system specifications and execution times for given operations) -

- The HSSF API includes: -

An implementation of Record - (binary 2 byte type followed by 2 byte size (n) followed by n bytes)
Implementations of many standard - record types mapping the data bytes to fields along with methods to - reserialize those fields
An implementation of the HSSF File - including functions to get/set the above constructs, create a blank - file with the minimum required record types and mappings between - getting/setting data and style in a workbook to the creation of - record types, and read HSSF files.
An abstraction of the HSSF file - format providing interfaces representing the HSSF File, HSSF - Workbook, HSSF Sheet, HSSF Column, HSSF Formulas in a manner - seperating the data from the styling and encapsulating the above - constructs.
Full documentation of the HSSF - file format (which will be a subset of the Excel '97 File format). - This must be done with care for legal reasons.
Full documentation of the APIs and - interfaces provided through Javadoc, user documentation (aimed at - developers using the apis).
Examples aimed at teaching - developers to use the APIs. -
Performance specifications. - (Example files rated by some measure of complexity along with system - specifications and execution times for given operations - possibly - the same files used for POI's tests)

- The HSSF Serializer subproject: -

A class supporting the Cocoon 2 - Serializer Interface.
An interface between the SAX - events and the HSSF APIs.
A specified tag language for using - with the Serializer.
Documentation on the tag language - for the HSSF Serializer
Normal javadocs.
Example XML files
Performance specifications. - (Example XML docs and stylesheets rated by some measure of - complexity along with system specifications and execution times)

- All Java code will be 100% pure Java. -

- The minimum system requirements for POIFS are: -

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

- The minimum system requirements for HSSF 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 - 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". -

- 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 HSSF Serializer 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. -

- - diff --git a/src/documentation/xdocs/plan/POI20Vision.xml b/src/documentation/xdocs/plan/POI20Vision.xml deleted file mode 100644 index 000fe8baa8..0000000000 --- a/src/documentation/xdocs/plan/POI20Vision.xml +++ /dev/null @@ -1,582 +0,0 @@ - - - - -

- POI 2.0 Vision Document - - - - - - -

- - - -

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

- This document was created before the POI components for - Apache Cocoon - 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. -

- -

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

- Our intended audience for the HSSF - Serializer portion of this project are developers writing reports or - data extracts in XML format. -
- 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 -
- 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. -
- Our intended audience for the HSSF - generator are developers who need to export Excel spreadsheets to - XML in a non-proprietary environment. -
- 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 -

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

- Benefit -	- Supporting Features -
- Ability to serialize styles from XML spreadsheets. -	- HSSFSerialzier will support styles. -
- Ability to read and write formulas in XLS files. -	- HSSF will support reading/writing formulas. -
- Ability to output in MS Word on any platform using Java. -	- The project will develop an API that outputs in Word format - using pure Java. -
- Enhance performance for reading and writing XLS files. -	- 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. -
- Ability to generate XML from XLS files -	- The project will develop an HSSF Generator. -
- The ability to generate charts -	- 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. -

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

- Enhancements to the POIFS API will - include: -

- An event driven API for reading - POIFS Filesystems. -
- A low-level API for - creating/manipulating POI filesystems. -
- Code improvements supporting - greater separation between read and write structures. -

- Enhancements to the HSSF API will - include: -

- An event driven API for reading - XLS files. -
- Performance improvements. -
- Formula support (read/write) -
- Support for user-defined data - formats -
- Better documentation of the file - format and structure. -
- An API for creation of charts. -

- The HSSF Generator will include: -

- A set of classes supporting the - Cocoon 2 Generator interfaces providing a method for reading XLS - files and outputting SAX events. -
- The same tag format used by the - HSSFSerializer in any given release. -

- The HDF API will include: -

- An event driven API for reading - DOC files. -
- A set of high and low level APIs - for reading and writing DOC files. -
- Documentation of the DOC file - format or enhancements to existing documentation. -

- 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 filesystem as read and written by - POI shall be fully documented and explained so that the average Java - developer can understand it. -

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

- - diff --git a/src/documentation/xdocs/plan/book.xml b/src/documentation/xdocs/plan/book.xml deleted file mode 100644 index 12857f774f..0000000000 --- a/src/documentation/xdocs/plan/book.xml +++ /dev/null @@ -1,20 +0,0 @@ - - - - - - - - - - - - - - - - - - diff --git a/src/documentation/xdocs/plan/index.xml b/src/documentation/xdocs/plan/index.xml deleted file mode 100644 index 74e44e3ada..0000000000 --- a/src/documentation/xdocs/plan/index.xml +++ /dev/null @@ -1,58 +0,0 @@ - - - - -

- Planning Documentation - Overview - - - - -

- - -

- -

This is a collection of notes to assist with long-term planning and - development. -

- -

There is much discussion of issues and research topics (RT) threads on - the dev mailing list (and elsewhere). However, details - get lost in the sheer volume. This is the place to document the summary of - discussions on some key topics. Some new and complex capabilities will take - lots of design and specification before they can be implemented. -

- -

Another use for this collection of notes is as a place to quickly store - a snippet from an email discussion or even a link to a discussion thread. - The concepts can then be fleshed-out over time. -

- -

Anyone can participate in this process. Please get involved in discussion - on dev and contribute patches for these summary planning - documents via the normal contribution - process. -

- -

These planning documents are intended to be concise notes only. They are - also ever-evolving, because as issues are addressed these notes will be - revised. -

- -

Release Plan - - major things to do before the 2.0 release
Documentation - - revisions and additions are required
See the general To Do list - and the dev email archives for other issues

- - - diff --git a/src/documentation/xdocs/plan/release.xml b/src/documentation/xdocs/plan/release.xml deleted file mode 100644 index 0c660e0859..0000000000 --- a/src/documentation/xdocs/plan/release.xml +++ /dev/null @@ -1,63 +0,0 @@ - - - - -

- Release Plan 2.0 - Planning Documentation - - - - -

- - -

Todo

- -

- - - -- cgit v1.2.3