From 313ba122ba9abeb30ff847c103de6b70bfba7e46 Mon Sep 17 00:00:00 2001
From: Nicola Ken Barozzi
Date: Sat, 6 Apr 2002 13:36:06 +0000
Subject: [PATCH] Corrected the files to conform to the new DTD. tags
s1,s2,s3,s4 become simply section.
git-svn-id: https://svn.apache.org/repos/asf/jakarta/poi/trunk@352341 13f79535-47bb-0310-9956-ffa450edef68
---
src/documentation/xdocs/3rdparty.xml | 17 ++-
src/documentation/xdocs/contrib.xml | 24 ++--
src/documentation/xdocs/faq.xml | 3 +-
src/documentation/xdocs/hdf/index.xml | 6 +-
src/documentation/xdocs/historyandfuture.xml | 8 +-
src/documentation/xdocs/hpsf/how-to.xml | 22 +--
src/documentation/xdocs/hpsf/index.xml | 6 +-
src/documentation/xdocs/hpsf/internals.xml | 50 +++----
src/documentation/xdocs/hpsf/todo.xml | 4 +-
src/documentation/xdocs/hssf/alternatives.xml | 6 +-
src/documentation/xdocs/hssf/diagram1.xml | 6 +-
src/documentation/xdocs/hssf/diagrams.xml | 6 +-
src/documentation/xdocs/hssf/how-to.xml | 48 +++----
src/documentation/xdocs/hssf/index.xml | 6 +-
src/documentation/xdocs/hssf/limitations.xml | 6 +-
src/documentation/xdocs/hssf/quick-guide.xml | 58 ++++----
.../xdocs/hssf/record-generator.xml | 26 ++--
src/documentation/xdocs/hssf/use-case.xml | 26 ++--
src/documentation/xdocs/index.xml | 48 +++----
src/documentation/xdocs/inthenews.xml | 28 ++--
src/documentation/xdocs/livesites.xml | 6 +-
src/documentation/xdocs/mail-archives.xml | 4 +-
src/documentation/xdocs/mail-lists.xml | 16 +--
src/documentation/xdocs/news/logocontest.xml | 20 +--
src/documentation/xdocs/overview.xml | 28 ++--
src/documentation/xdocs/patches.xml | 6 +-
src/documentation/xdocs/plan/POI10Vision.xml | 132 +++++++++---------
src/documentation/xdocs/plan/POI20Vision.xml | 128 ++++++++---------
src/documentation/xdocs/plan/index.xml | 8 +-
src/documentation/xdocs/plan/release.xml | 4 +-
src/documentation/xdocs/poifs/fileformat.xml | 74 +++++-----
src/documentation/xdocs/poifs/how-to.xml | 106 +++++++-------
src/documentation/xdocs/poifs/index.xml | 4 +-
src/documentation/xdocs/poifs/usecases.xml | 46 +++---
src/documentation/xdocs/resolutions/index.xml | 6 +-
.../xdocs/resolutions/res001.xml | 22 +--
src/documentation/xdocs/utils/index.xml | 6 +-
src/documentation/xdocs/who.xml | 16 +--
38 files changed, 518 insertions(+), 518 deletions(-)
diff --git a/src/documentation/xdocs/3rdparty.xml b/src/documentation/xdocs/3rdparty.xml
index 25d983f95..dac1516ed 100644
--- a/src/documentation/xdocs/3rdparty.xml
+++ b/src/documentation/xdocs/3rdparty.xml
@@ -1,5 +1,4 @@
-
@@ -11,14 +10,14 @@
-
+
See How to contribute to Poi.
-
+
-
+
These are not necessarily deemed to be high enough quality to be included in the
core distribution, but they have been tested under
@@ -32,18 +31,18 @@
listed below will eventually migrate to the "contributed components" level, and
then maybe even into the main distribution.
-
+
-
+
Submissions of modifications
to Poi which are awaiting review. Anyone can
comment on them on the dev mailing list - code reviewers are needed!
Use these at your own risk - although Poi has no guarantee
either, these patches have not been reviewed, let alone accepted.
-
+
-
+
The other extensions listed here are not endorsed by the Poi
project either - they are provided as a convenience only. They may or may not work,
they may or may not be open source, etc.
@@ -63,6 +62,6 @@
-
+
diff --git a/src/documentation/xdocs/contrib.xml b/src/documentation/xdocs/contrib.xml
index 22b96c9fd..e95bc34b1 100644
--- a/src/documentation/xdocs/contrib.xml
+++ b/src/documentation/xdocs/contrib.xml
@@ -15,7 +15,7 @@
-
+
The POI Project is an Open Source
@@ -48,9 +48,9 @@
we have work for you! And we'll be very available to you for any questions!
-
+
-
+
The rest of this document is mainly about
contributing new or improved code and/or documentation, but we would also be glad to have
@@ -81,10 +81,10 @@
-
+
-
+
An overview of how to use CVS to participate in POI development.
Do not be afraid - you cannot accidently destroy the actual code repository,
because you are working with a local copy as an anonymous user.
@@ -105,9 +105,9 @@
repository, how to keep it up-to-date, and how to generate the differences
to create a patch. (The commands are for Linux.)
-
+
-
+
After a developer has consistently provided contributions (code,
documentation and discussion), then the rest of the dev community
may vote to grant this developer commit access to CVS.
@@ -125,10 +125,10 @@
- See the bottom of the page for links to tips for UNIX and Windows.
Even if you are on UNIX, the Windows page will also help.
-
+
-
+
There are two methods for discussing development and submitting patches.
So that everyone can be productive, it is important to know which method
@@ -178,10 +178,10 @@
posting - perhaps it was not clear enough
and the readers' eyes glazed over.
-
+
-
+
This is a collection of tips for contributing to the project in a manner
that is productive for all parties.
@@ -273,7 +273,7 @@
see the way other people do things. Follow the leading examples.
-
+
diff --git a/src/documentation/xdocs/faq.xml b/src/documentation/xdocs/faq.xml
index 79b63a6b3..7934dfd6e 100644
--- a/src/documentation/xdocs/faq.xml
+++ b/src/documentation/xdocs/faq.xml
@@ -32,9 +32,10 @@
Why am I getting an exception each time I attempt to read my spreadsheet?
+
It's possible your spreadsheet contains a feature that is not currently supported by HSSF.
For example - spreadsheets containing cells with rich text are not currently supported.
+
-
diff --git a/src/documentation/xdocs/hdf/index.xml b/src/documentation/xdocs/hdf/index.xml
index ad1fbe65b..e9b1658f4 100644
--- a/src/documentation/xdocs/hdf/index.xml
+++ b/src/documentation/xdocs/hdf/index.xml
@@ -1,5 +1,5 @@
-
+
-
+
HDF will be the name of OUR port of the Microsoft Word 97(-2002) file format to
pure Java.
@@ -20,6 +20,6 @@
follow development on the poi-dev mailing list.
-
+
diff --git a/src/documentation/xdocs/historyandfuture.xml b/src/documentation/xdocs/historyandfuture.xml
index ae26b195c..3855480f6 100755
--- a/src/documentation/xdocs/historyandfuture.xml
+++ b/src/documentation/xdocs/historyandfuture.xml
@@ -12,7 +12,7 @@
-
+
The POI project was dreamed up back around April 2001, when
Andy Oliver landed a short term contract to do Java-based
@@ -76,9 +76,9 @@ already started making waves.
looks like everything turned out since you're reading this!
-
+
-
+
First we'll tackle this from a project standpoint: Well, we
made an offer to Microsoft and Actuate (tongue in cheek
... well mostly) that we'd quit the project and retire if
@@ -120,7 +120,7 @@ already started making waves.
that new blood will join the team and allow us to tackle this
even faster (in part because POIFS is already finished). But
maybe what we need most is you!
-
+
diff --git a/src/documentation/xdocs/hpsf/how-to.xml b/src/documentation/xdocs/hpsf/how-to.xml
index 85da8cf7f..1a737254d 100644
--- a/src/documentation/xdocs/hpsf/how-to.xml
+++ b/src/documentation/xdocs/hpsf/how-to.xml
@@ -1,6 +1,6 @@
+"../dtd/document-v11.dtd">
@@ -11,7 +11,7 @@
-
+
This HOW-TO is organized in three section. You should read them
sequentially because the later sections build upon the earlier ones.
@@ -40,7 +40,7 @@
-
+
This section explains how to read
the most important standard properties of a Microsoft Office
@@ -83,7 +83,7 @@
Sounds easy, doesn't it? Here are the steps in detail.
-
An application that wants to open a document in a POI filesystem
@@ -215,11 +215,11 @@ static class MyPOIFSReaderListener implements POIFSReaderListener
\005SummaryInformation stream. In this case the applications
won't throw an exception but simply does not call the
processPOIFSReaderEvent
method. You have been warned!
-
-
+
+
-
+
This section focusses on reading additional standard properties. It
also talks about exceptions that may be thrown when dealing with HPSF and
@@ -292,17 +292,17 @@ static class MyPOIFSReaderListener implements POIFSReaderListener
contrib section tries to open each and every document in a POI filesystem
as a property set stream. If this operation was successful it displays the
properties.
-
+
-
+
This section tells how to read
non-standard properties. Non-standard properties are application-specific
name/value/type triples.
Write this section!
-
-
+
+
diff --git a/src/documentation/xdocs/hpsf/index.xml b/src/documentation/xdocs/hpsf/index.xml
index 63a9d7c99..1842b5a85 100644
--- a/src/documentation/xdocs/hpsf/index.xml
+++ b/src/documentation/xdocs/hpsf/index.xml
@@ -1,5 +1,5 @@
-
+
@@ -11,7 +11,7 @@
-
+
Microsoft applications like "Word" or "Excel" let the user describe his
document by properties like "title", "category" and so on. The application
itself adds further information: last author, creation date etc. These
@@ -28,7 +28,7 @@
case of document properties mentioned above. The HPSF description describes the internal
structure of property set streams.
-
+
diff --git a/src/documentation/xdocs/hpsf/internals.xml b/src/documentation/xdocs/hpsf/internals.xml
index e9a875361..25d374511 100644
--- a/src/documentation/xdocs/hpsf/internals.xml
+++ b/src/documentation/xdocs/hpsf/internals.xml
@@ -1,5 +1,5 @@
-
+
@@ -10,9 +10,9 @@
-
+
-
+
A Microsoft Office document is internally organized like a filesystem
with directory and files. Microsoft calls these files
@@ -45,11 +45,11 @@
Embedded documents may have their own property set streams. You cannot
tell by a stream's name whether it is a property set stream or not.
Instead you have to open the stream and look at its bytes.
-
+
-
+
Before delving into the details of the property set stream format we
have to have a short look at data types. Integral values are stored in the
@@ -148,11 +148,11 @@
-
+
-
+
A property set stream consists of three main parts:
@@ -164,11 +164,11 @@
the section(s) containing the properties.
-
+
-
+
The first bytes in a property set stream is the header .
It has a fixed length and looks like this:
@@ -265,11 +265,11 @@
-
+
-
+
Following the header is the section list. This is an array of pairs each
consisting of a section format ID and an offset. This array has as many
@@ -355,11 +355,11 @@
-
+
-
+
A section is divided into three parts: the section header (with the
section length and the number of properties in the section), the
@@ -509,11 +509,11 @@
-
+
-
+
As seen above, a section holds a property list: an array with property
@@ -535,7 +535,7 @@
Information and the Document Summary Information streams. You can extend
them by your own additional IDs. This will be described below.
-
+
The Summary Information stream has a single section with a section
format ID of 0xF29F85E04FF91068AB9108002B27B3D9
. The following
@@ -672,11 +672,11 @@
VT_I4
-
+
-
+
The Document Summary Information stream has two sections with a section
format ID of 0xD5CDD5022E9C101B939708002B2CF9AE
for the first
@@ -781,12 +781,12 @@
VT_BOOL
-
-
+
+
-
+
A property consists of a DWord type field followed by the
@@ -1090,11 +1090,11 @@
-
+
-
+
In order to assemble the HPSF description I used information publically
available on the Internet only. The references given below have been very
@@ -1144,8 +1144,8 @@
This documentation origins from the HPSF description available at http://www.rainer-klute.de/~klute/Software/poibrowser/doc/HPSF-Description.html.
-
-
+
+
diff --git a/src/documentation/xdocs/hpsf/todo.xml b/src/documentation/xdocs/hpsf/todo.xml
index df7c06c3e..4d2d47c09 100644
--- a/src/documentation/xdocs/hpsf/todo.xml
+++ b/src/documentation/xdocs/hpsf/todo.xml
@@ -10,7 +10,7 @@
-
+
The following functionalities should be added to HPFS:
@@ -37,7 +37,7 @@
yet supported (other than byte arrays).
-
+
diff --git a/src/documentation/xdocs/hssf/alternatives.xml b/src/documentation/xdocs/hssf/alternatives.xml
index 0b4cbc751..c32f4aa9a 100644
--- a/src/documentation/xdocs/hssf/alternatives.xml
+++ b/src/documentation/xdocs/hssf/alternatives.xml
@@ -1,5 +1,5 @@
-
+
-
+
Maybe it's unwise to advertise your competitors but we believe
competition is good and we have the best support reading and
@@ -78,6 +78,6 @@
There are a number of perl and C libraries, however none of them are consistent.
-
+
diff --git a/src/documentation/xdocs/hssf/diagram1.xml b/src/documentation/xdocs/hssf/diagram1.xml
index be8481c14..9d1cd2a7f 100644
--- a/src/documentation/xdocs/hssf/diagram1.xml
+++ b/src/documentation/xdocs/hssf/diagram1.xml
@@ -1,5 +1,5 @@
-
+
-
+
-
+
diff --git a/src/documentation/xdocs/hssf/diagrams.xml b/src/documentation/xdocs/hssf/diagrams.xml
index d7932bdf8..1a1c1bbd1 100644
--- a/src/documentation/xdocs/hssf/diagrams.xml
+++ b/src/documentation/xdocs/hssf/diagrams.xml
@@ -1,5 +1,5 @@
-
+
-
+
This section is intended for diagrams (UML/etc) that help
explain HSSF.
@@ -33,6 +33,6 @@
many good affordable UML tools yet! And no they don't HAVE to be UML...
just useful.
-
+
diff --git a/src/documentation/xdocs/hssf/how-to.xml b/src/documentation/xdocs/hssf/how-to.xml
index 2dec74523..8c5d930db 100644
--- a/src/documentation/xdocs/hssf/how-to.xml
+++ b/src/documentation/xdocs/hssf/how-to.xml
@@ -10,9 +10,9 @@
-
+
-
+
This release of the how-to outlines functionality for the 1.5 release.
Those looking for information on previous releases should
look in the documentation distributed with that release.
@@ -26,10 +26,10 @@
and is intended for intermediate developers who need a smaller
memory footprint. It will also serve as the basis for the HSSF
Generator.
-
-
-
-
+
+
+
+
The high level API (package: org.apache.poi.hssf.usermodel)
is what most people should use. Usage is very simple.
@@ -211,8 +211,8 @@
wb.write(out);
out.close();
]]>
-
-
+
+
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
@@ -229,9 +229,9 @@ would if creating a new xls. When you are done modifying cells just
call workbook.write(outputstream) just as you did above.
An example of this can be seen in
org.apache.poi.hssf.dev.HSSF.
-
-
-
+
+
+
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
@@ -359,8 +359,8 @@ public class EventExample
}
}
]]>
-
-
+
+
The low level API is not much to look at. It consists of lots of
"Records" in the org.apache.poi.hssf.record.* package,
@@ -374,8 +374,8 @@ order to gain a good understanding of how to use the low level APIs
should view the source in org.apache.poi.hssf.usermodel.* and
the classes in org.apache.poi.hssf.model.*. You should read the
documentation for the POIFS libraries as well.
-
-
+
+
The HSSF application is nothing more than a test for the high
level API (and indirectly the low level support). The main body of
@@ -402,8 +402,8 @@ This is the read/write/modify test. It reads in the spreadsheet, modifies a cel
Failing this test is not necessarily a bad thing. If HSSF tries to modify a non-existant sheet then this will
most likely fail. No big deal.
-
-
+
+
HSSF now has a logging facility (using
commons logging)
that will record massive amounts of debugging information. Its mostly
@@ -444,8 +444,8 @@ many cases the Commons Logging component can fill that role.
Refer to the commons logging package level javadoc for more information concerning how to
configure commons logging.
-
-
+
+
HSSF has a number of tools useful for developers to debug/develop
stuff using HSSF (and more generally XLS files). We've already
@@ -479,8 +479,8 @@ matching "on" exactly.
FormulaViewer. The class is already there, but its not very useful
yet. When it does something, we'll document it.
-
-
+
+
This release contains code that supports "internationalization"
or more accurately non-US/UK languages; however, it has not been
@@ -501,10 +501,10 @@ As a general principal, HSSF's goal is to support HSSF-Serializer
are you using HSSF/POIFS? How would you like to use it? What features
are most important first?
-
+
-
+
-
+
diff --git a/src/documentation/xdocs/hssf/index.xml b/src/documentation/xdocs/hssf/index.xml
index 40ca933bd..9b96f3c39 100644
--- a/src/documentation/xdocs/hssf/index.xml
+++ b/src/documentation/xdocs/hssf/index.xml
@@ -1,5 +1,5 @@
-
+
-
+
HSSF is the POI Project's pure Java implementation of the Excel '97(-2002) file format.
HSSF provides a way to read spreadsheets create, modify, read and write XLS spreadsheets
@@ -42,6 +42,6 @@
it this way indirectly) is the best way...we promise.
-
+
diff --git a/src/documentation/xdocs/hssf/limitations.xml b/src/documentation/xdocs/hssf/limitations.xml
index 758449398..18b379e1a 100644
--- a/src/documentation/xdocs/hssf/limitations.xml
+++ b/src/documentation/xdocs/hssf/limitations.xml
@@ -6,7 +6,7 @@
-
+
The intent of this document is to outline some of the known limitations of the
POI HSSF API's. It is not intended to be complete list of every bug or missing
@@ -47,6 +47,6 @@
has not been tested.
-
+
-
\ No newline at end of file
+
diff --git a/src/documentation/xdocs/hssf/quick-guide.xml b/src/documentation/xdocs/hssf/quick-guide.xml
index ed84516bd..2d660255d 100644
--- a/src/documentation/xdocs/hssf/quick-guide.xml
+++ b/src/documentation/xdocs/hssf/quick-guide.xml
@@ -1,5 +1,5 @@
-
+
-
+
Want to use HSSF read and write spreadsheets in a hurry? This guide is for you. If you're after
more in-depth coverage of the HSSF user-API please consult the HOWTO
guide as it contains actual descriptions of how to use this stuff.
-
+
How to create a new workbook
How to create a sheet
@@ -29,19 +29,19 @@
Working with fonts
Reading and writing
-
-
+
+
-
+
HSSFWorkbook wb = new HSSFWorkbook();
FileOutputStream fileOut = new FileOutputStream("workbook.xls");
wb.write(fileOut);
fileOut.close();
-
+
-
+
HSSFWorkbook wb = new HSSFWorkbook();
HSSFSheet sheet1 = wb.createSheet("new sheet");
@@ -50,9 +50,9 @@
wb.write(fileOut);
fileOut.close();
-
+
-
+
HSSFWorkbook wb = new HSSFWorkbook();
HSSFSheet sheet = wb.createSheet("new sheet");
@@ -73,9 +73,9 @@
wb.write(fileOut);
fileOut.close();
-
+
-
+
HSSFWorkbook wb = new HSSFWorkbook();
HSSFSheet sheet = wb.createSheet("new sheet");
@@ -102,9 +102,9 @@
wb.write(fileOut);
fileOut.close();
-
+
-
+
HSSFWorkbook wb = new HSSFWorkbook();
HSSFSheet sheet = wb.createSheet("new sheet");
@@ -120,9 +120,9 @@
wb.write(fileOut);
fileOut.close();
-
+
-
+
public static void main(String[] args)
throws IOException
@@ -162,9 +162,9 @@
cell.setCellStyle(cellStyle);
}
-
+
-
+
HSSFWorkbook wb = new HSSFWorkbook();
HSSFSheet sheet = wb.createSheet("new sheet");
@@ -193,9 +193,9 @@
wb.write(fileOut);
fileOut.close();
-
+
-
+
HSSFWorkbook wb = new HSSFWorkbook();
HSSFSheet sheet = wb.createSheet("new sheet");
@@ -224,9 +224,9 @@
wb.write(fileOut);
fileOut.close();
-
+
-
+
HSSFWorkbook wb = new HSSFWorkbook();
HSSFSheet sheet = wb.createSheet("new sheet");
@@ -242,9 +242,9 @@
wb.write(fileOut);
fileOut.close();
-
+
-
+
HSSFWorkbook wb = new HSSFWorkbook();
HSSFSheet sheet = wb.createSheet("new sheet");
@@ -273,9 +273,9 @@
wb.write(fileOut);
fileOut.close();
-
+
-
+
POIFSFileSystem fs =
new POIFSFileSystem(new FileInputStream("workbook.xls"));
@@ -293,8 +293,8 @@
wb.write(fileOut);
fileOut.close();
-
-
-
+
+
+
diff --git a/src/documentation/xdocs/hssf/record-generator.xml b/src/documentation/xdocs/hssf/record-generator.xml
index 7dae69a73..503a1599c 100644
--- a/src/documentation/xdocs/hssf/record-generator.xml
+++ b/src/documentation/xdocs/hssf/record-generator.xml
@@ -1,5 +1,5 @@
-
+
-
+
-
+
The record generator was born from frustration with translating
the Excel records to Java classes. Doing this manually is a time
@@ -23,9 +23,9 @@
record looked like and do all the boring stuff. Thus the
record generator was born.
-
+
-
+
The record generator takes XML as input and produced the following
output:
@@ -35,8 +35,8 @@
for ensuring the record operates as designed.
-
-
+
+
The record generator is invoked as an Ant target (generate-records). It goes
through looking for all files in src/records/defintitions ending with _record.xml.
@@ -78,8 +78,8 @@
not already exist. What this means is that you may change test
stubs but not the generated records.
-
-
+
+
The record generation works by taking an XML file and styling it
using XLST. Given that XSLT is a little limited in some ways it was
@@ -89,8 +89,8 @@
See record.xsl, record_test.xsl, FieldIterator.java,
RecordUtil.java, RecordGenerator.java
-
-
+
+
The record generator does not handle all possible record types and
is not ment to. Sometimes it's going to make more sense to generate
@@ -108,7 +108,7 @@
the XSL file itself. The Java code for the record generation is
currently quite messy with minimal comments.
-
-
+
+
diff --git a/src/documentation/xdocs/hssf/use-case.xml b/src/documentation/xdocs/hssf/use-case.xml
index 6e16c2aec..ee37cf59d 100644
--- a/src/documentation/xdocs/hssf/use-case.xml
+++ b/src/documentation/xdocs/hssf/use-case.xml
@@ -1,5 +1,5 @@
-
+
-
-
+
+
Primary Actor: HSSF client
Scope: HSSF
@@ -39,8 +39,8 @@
Extensions:
2a. Exceptions
thrown by POIFS will be passed on to the HSSF client.
-
-
+
+
Primary Actor: HSSF client
Scope: HSSF
@@ -77,8 +77,8 @@ thrown by POIFS will be passed on to the HSSF client.
3a. Exceptions
from POIFS are passed to the HSSF client.
-
-
+
+
Primary Actor: HSSF client
Scope: HSSF
@@ -104,8 +104,8 @@ from POIFS are passed to the HSSF client.
Extensions:
None
-
-
+
+
Primary Actor: HSSF
Scope: HSSF
@@ -140,8 +140,8 @@ Guarantee: None
Extensions:
3a. Exceptions
thrown by POIFS will be passed on
-
-
+
+
Primary Actor: HSSF
@@ -175,8 +175,8 @@ thrown by POIFS will be passed on
write new file to file system)
Extensions: None
-
+
-
+
diff --git a/src/documentation/xdocs/index.xml b/src/documentation/xdocs/index.xml
index 04a727d1d..8c18783ba 100644
--- a/src/documentation/xdocs/index.xml
+++ b/src/documentation/xdocs/index.xml
@@ -10,7 +10,7 @@
-
+
The POI committers have voted to
"innovate" and hold a
@@ -62,8 +62,8 @@
You can see the current submissions here.
-
-
+
+
The POI project consists of APIs for manipulating various file formats
based upon Microsoft's OLE 2 Compound Document format using pure Java.
@@ -80,7 +80,7 @@
XLS format; and Lucene for which we'll soon have file
format interpretors. When practical, we donate components directly to those projects for POI-enabling them.
-
+
We'll tackle this on a component level. POI refers to the whole project.
@@ -97,9 +97,9 @@
You'd use HSSF if you needed to read or write an XLS (Excel) file using Java. You can also read and modify
spreadsheets using this API, although right now writing is more mature.
-
+
-
+
POI stands for Poor Obfuscation Implementation. Why would we name our project such a derogatory name? Well,
Microsoft's OLE 2 Compound Document Format is a poorly conceived thing. It is essentially an archive structured
@@ -116,32 +116,32 @@
So if you like acronyms, then POI is an acronym. If you hate them, then we just used the name of the food for our
project. If you wish to signify your love or hate for acronyms, use POI or Poi to refer to the project respectively.
-
+
-
+
-
-
+
+
A common misconception is that POI writes Excel files. POI is the name of the project. POI contains several
components, one of which, HSSF, writes Excel files. The following are components of the entire POI project
and a brief summary of their purpose.
-
-
+
+
POIFS is the oldest and most stable part of the project. It is our port of the OLE 2 Compound Document Format to
pure Java. It supports both read and write functionality. All of our components ultimately rely on it by
definition. Please see the POIFS project page for more information.
-
-
+
+
HSSF is our port of the Microsoft Excel 97(-2002) file format (BIFF8) to pure Java. It supports read and write
capability. Please see the HSSF project page for more information.
-
-
+
+
HDF is our port of the Microsoft Word 97 file format to pure Java. It supports read and write capability.
Please see the HDF project page for more information. This component is
in the early stages of design. Jump in!
-
-
+
+
HPSF is our port of the OLE 2 property set format to pure
Java. Property sets are mostly use to store a document's properties
(title, author, date of last modification etc.), but they can be used
@@ -149,17 +149,17 @@
read functionality only. Please see the HPSF project page for more
information.
-
+
-
+
-
+
The HSSF Serializer, which was part of our 1.0 release and last builds on
Sourceforge, has been donated to the Cocoon project. We're
currently in the process of porting it over.
-
+
-
+
So you'd like to contribute to the project? Great! We need enthusiastic, hard-working, talented folks to help
us on the project in several areas. The first is bug reports and feature requests! The second is documentation -
@@ -173,7 +173,7 @@
-
+
diff --git a/src/documentation/xdocs/inthenews.xml b/src/documentation/xdocs/inthenews.xml
index 9e8a27a60..b2fcf5561 100644
--- a/src/documentation/xdocs/inthenews.xml
+++ b/src/documentation/xdocs/inthenews.xml
@@ -10,7 +10,7 @@
-
+
These are articles/etc. posted about POI around the web. If you
see POI in the news or mentioned at least somewhat prominently
@@ -21,8 +21,8 @@
defamation as well as favorable, technical and factual. Really
stupid things won't be mentioned (sorry).
-
-
+
+
-
+
+
-
+
+
-
+
+
@@ -107,8 +107,8 @@
- Da Linux French Page
-
-
+
+
-
+
+
If you can read one of these languages, send mail to the list
telling us what language it is and we'll categorize it!
-
+
diff --git a/src/documentation/xdocs/livesites.xml b/src/documentation/xdocs/livesites.xml
index e7586f075..81decb935 100644
--- a/src/documentation/xdocs/livesites.xml
+++ b/src/documentation/xdocs/livesites.xml
@@ -14,7 +14,7 @@
-
+
Currently we don't have any sites listed that use Poi, but we're sure they're out there.
Help us change this. If you've
written a site that utilises Poi let us know.
@@ -23,8 +23,8 @@
-
+
-->
-
+
diff --git a/src/documentation/xdocs/mail-archives.xml b/src/documentation/xdocs/mail-archives.xml
index d5ecae703..e77f7d757 100644
--- a/src/documentation/xdocs/mail-archives.xml
+++ b/src/documentation/xdocs/mail-archives.xml
@@ -12,7 +12,7 @@
-
+
There are a number of mailing list archives available.
@@ -37,7 +37,7 @@
?
-
+
diff --git a/src/documentation/xdocs/mail-lists.xml b/src/documentation/xdocs/mail-lists.xml
index 1d011521f..5244ef976 100644
--- a/src/documentation/xdocs/mail-lists.xml
+++ b/src/documentation/xdocs/mail-lists.xml
@@ -10,7 +10,7 @@
-
+
IMPORTANT: Before posting a question or problem to any mailing list,
please first look at the following resources in this order:
@@ -26,9 +26,9 @@
work smarter.
See tips for Contributing
-
+
-
+
Subscribe
Unsubscribe
@@ -62,9 +62,9 @@
busy list and we do not appreciate getting the exact same message posted impatiently
several times a day/week! Doing so is only likely to make your question answered more
slowly, or not at all, not faster.
-
+
-
+
Subscribe
Unsubscribe
@@ -78,9 +78,9 @@
isn't Poi working on my machine?" -
please ask those sorts of questions on users list (after reading the
FAQ first, of course).
-
+
-
+
(See also
ODP XML links for related websites.)
@@ -92,6 +92,6 @@
tomcat-user (note it is "user"
and not "users").
-
+
diff --git a/src/documentation/xdocs/news/logocontest.xml b/src/documentation/xdocs/news/logocontest.xml
index 236591f56..1be4d46fc 100644
--- a/src/documentation/xdocs/news/logocontest.xml
+++ b/src/documentation/xdocs/news/logocontest.xml
@@ -10,33 +10,33 @@
-
+
Here are the current logo submissions. Thanks to the artists!
-
+
-
-
+
+
-
-
+
+
-
-
+
+
-
-
+
+
diff --git a/src/documentation/xdocs/overview.xml b/src/documentation/xdocs/overview.xml
index 36e5a7de7..be98f3639 100644
--- a/src/documentation/xdocs/overview.xml
+++ b/src/documentation/xdocs/overview.xml
@@ -10,47 +10,47 @@
-
+
The POI project is the master project for developing pure
Java ports of file formats based on Microsoft's OLE 2 Compound
Document Format. OLE 2 Compound Document Format is used by
Microsoft Office Documents, as well as by programs using MFC
property sets to serialize their document objects.
-
-
+
+
There following are ports, packages or components contained in the POI project.
-
+
POIFS is the set of APIs
for reading and writing OLE 2 Compound Document Formats using (only) Java.
-
+
-
+
HSSF is the set of APIs
for reading and writing Microsoft Excel 97(-XP) spreadsheet using (only) Java.
-
+
-
+
HDF is the set of APIs
for reading and writing Microsoft Word 97(-XP) spreadsheet using (only) Java.
-
+
-
+
HPSF is the set of APIs
for reading property sets using (only) Java.
-
+
-
+
POI-Utils are general purpose artifacts
from POI development that have not yet been implemented elsewhere. We're
@@ -58,8 +58,8 @@
used in another project. These are things we need to complete our mission but
are generally outside of it.
-
-
+
+
diff --git a/src/documentation/xdocs/patches.xml b/src/documentation/xdocs/patches.xml
index b12b454e4..2887174d9 100644
--- a/src/documentation/xdocs/patches.xml
+++ b/src/documentation/xdocs/patches.xml
@@ -1,7 +1,7 @@
-
+
This is an informal list - in chronological order -
of some of the noteworthy patches that have been posted
to the developers
mailing list.
@@ -17,7 +17,7 @@
Contributions. The preferred submission method for patches is:
Post to Poi developers list Describe the patch, the reason for it and (if necessary) why this is important. Generate the patch in diff -u
format from CVS Also generate a documentation patch or new file, if this is something that should be documented.
Post as an attachment rather than inline (unless it is trivially small). Following the above guidelines will facilitate your patch being reviewed
- and applied efficiently.
[Under Construction] Archive links will be added later.
+ and applied efficiently.
[Under Construction] Archive links will be added later.
Please do not bother the patch submitters/authors without first reading the
relevant post(s) in the mailing list archives.
Vapourware will not be listed.
id Summary Reviewer Resolution Status
See also additional list of patches to be added in To Do .
-
+
diff --git a/src/documentation/xdocs/plan/POI10Vision.xml b/src/documentation/xdocs/plan/POI10Vision.xml
index c6be23a06..b2b8c6c3e 100644
--- a/src/documentation/xdocs/plan/POI10Vision.xml
+++ b/src/documentation/xdocs/plan/POI10Vision.xml
@@ -12,7 +12,7 @@
-
+
(21-Jan-02) While this document is just full of useful project
introductory information and I do suggest those interested in getting
@@ -42,10 +42,10 @@
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
@@ -56,10 +56,10 @@
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
@@ -89,10 +89,10 @@
-
-
-
-
+
+
+
+
There are a number of enthusiastic
users of XML, UNIX and Java technology. Secondly, the Microsoft
@@ -122,15 +122,15 @@
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
@@ -156,16 +156,16 @@
-
-
+
+
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
@@ -173,8 +173,8 @@
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
@@ -187,8 +187,8 @@
projects to convert other OLE 2 Compound Document formats to pure
Java APIs.
-
-
+
+
HSSF Serializer for Apache Cocoon 2
@@ -239,8 +239,8 @@
-
-
+
+
The HSSF Serializer will run on
@@ -256,9 +256,9 @@
implementation.
-
-
-
+
+
+
The POIFS API will include:
@@ -295,7 +295,7 @@
about the Excel format itself.
-
+
The POI Filesystem API includes:
@@ -329,8 +329,8 @@
with system specifications and execution times for given operations)
-
-
+
+
The HSSF API includes:
@@ -364,8 +364,8 @@
specifications and execution times for given operations - possibly
the same files used for POI's tests)
-
-
+
+
The HSSF Serializer subproject:
@@ -384,15 +384,15 @@
(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:
@@ -421,15 +421,15 @@
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
@@ -441,25 +441,25 @@
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
@@ -467,43 +467,43 @@
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
index 38fcc4711..000fe8baa 100644
--- a/src/documentation/xdocs/plan/POI20Vision.xml
+++ b/src/documentation/xdocs/plan/POI20Vision.xml
@@ -14,7 +14,7 @@
-
+
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
@@ -35,10 +35,10 @@
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,
@@ -78,10 +78,10 @@
Java.
-
+
-
+
The first release of the POI project
was an astounding success. This release seeks to build on that
@@ -119,10 +119,10 @@
Providing the create excel charts. (write only)
-
-
-
-
+
+
+
+
There are a number of enthusiastic
users of XML, UNIX and Java technology. Furthermore, the Microsoft
@@ -163,15 +163,15 @@
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
@@ -213,16 +213,16 @@
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
@@ -232,8 +232,8 @@
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
@@ -246,8 +246,8 @@
tools for later projects to convert other OLE 2 Compound Document
formats to pure Java APIs.
-
-
+
+
HSSF Serializer for Apache Cocoon 2
@@ -315,8 +315,8 @@
-
-
+
+
The HSSF Serializer and Generator
@@ -355,9 +355,9 @@
-
-
-
+
+
+
Enhancements to the POIFS API will
include:
@@ -434,14 +434,14 @@
format or enhancements to existing documentation.
-
-
-
+
+
+
All Java code will be 100% pure Java.
-
-
+
+
The minimum system requirements for the POIFS API are:
@@ -480,15 +480,15 @@
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
@@ -500,25 +500,25 @@
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
@@ -528,55 +528,55 @@
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.
-
-
+
+
diff --git a/src/documentation/xdocs/plan/index.xml b/src/documentation/xdocs/plan/index.xml
index e0199f3c4..74e44e3ad 100644
--- a/src/documentation/xdocs/plan/index.xml
+++ b/src/documentation/xdocs/plan/index.xml
@@ -12,7 +12,7 @@
-
+
This is a collection of notes to assist with long-term planning and
development.
@@ -40,9 +40,9 @@
also ever-evolving, because as issues are addressed these notes will be
revised.
-
+
-
+
Release Plan
@@ -52,7 +52,7 @@
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
index 5e26aed12..0c660e085 100644
--- a/src/documentation/xdocs/plan/release.xml
+++ b/src/documentation/xdocs/plan/release.xml
@@ -12,7 +12,7 @@
-
+
+
diff --git a/src/documentation/xdocs/poifs/fileformat.xml b/src/documentation/xdocs/poifs/fileformat.xml
index 8304fd8b5..7042b5959 100644
--- a/src/documentation/xdocs/poifs/fileformat.xml
+++ b/src/documentation/xdocs/poifs/fileformat.xml
@@ -1,5 +1,5 @@
-
+
-
-
+
+
POIFS file systems are essentially normal files stored on a
Java-compatible platform's native file system. They are
typically identified by names ending in a four character
@@ -35,8 +35,8 @@
with the extension ".doc", you would actually
have a POIFS file system with a document file archived
inside of that file system.
-
-
+
+
This document utilizes the numeric types as described by
the Java Language Specification, which can be found at
http://java.sun.com. In
@@ -67,8 +67,8 @@ public int getShort (byte[] rec)
{
return ((rec[1] << 8) | (rec[0] & 0x00ff));
}
-
-
+
+
This is a walkthrough of a POIFS file system and how it is
put together. It is not intended to give a concise
description but to give a "big picture" of the
@@ -114,8 +114,8 @@ public int getShort (byte[] rec)
blocks into smaller blocks and there is a special small
block allocation table that, like the main BAT for larger
files, is used to map a small file to its small blocks.
-
-
+
+
The POIFS file system begins with a header
block . The first 64 bits of the header form a long
file type id or magic number identifier of
@@ -127,14 +127,14 @@ public int getShort (byte[] rec)
It's important to know the most important parts of the
header. These are discussed in the rest of this
section.
-
+
At offset 0x2C is an int specifying the number
of elements in the BAT array . The array at
0x4C an array of ints. This array contains the
indices of every block in the Block Allocation
Table.
-
-
+
+
Very large POIFS archives may have more blocks than can
be addressed by the BAT blocks enumerated in the header
block. How large? Well, the BAT array in the header can
@@ -170,8 +170,8 @@ public int getShort (byte[] rec)
yet to see a disk drive large enough to accommodate
such a file on the shelves at the local office supply
stores.
-
-
+
+
If a file contained in a POIFS archive is smaller than
4096 bytes, it is stored in small blocks. Small blocks
are 64 bytes in length and are contained within big
@@ -184,17 +184,17 @@ public int getShort (byte[] rec)
walking the main BAT as if it were an ordinary file in
the POIFS file system (this process is described
below).
-
-
+
+
An integer at address 0x30 specifies the start
index of the property table. This integer is specified
as a "block index" . The Property Table
is stored, as is almost everything in a POIFS file
system, in big blocks and walked via the BAT. The
Property Table is described below.
-
-
-
+
+
+
The property table is essentially nothing more than the
directory system. Properties are 128 byte records
contained within the 512 byte blocks. The first property
@@ -252,8 +252,8 @@ public int getShort (byte[] rec)
used to walk the big blocks making up this special
file.
-
-
+
+
The Root Entry in the Property Table
contains the information necessary to read and write
small files, which are files less than 4096 bytes
@@ -266,8 +266,8 @@ public int getShort (byte[] rec)
Block Array are divided into 64-byte small blocks, up to
the size indicated in the Root Entry (which should always
be a multiple of 64).
-
-
+
+
The individual properties form a directory tree, with the
Root Entry as the directory tree's root, as shown
in the accompanying drawing. Note the numbers in
@@ -293,8 +293,8 @@ public int getShort (byte[] rec)
CHILD_PROP fields contain the marker value of
-1. All file properties have a value of -1 for their
CHILD_PROP fields for example.
-
-
+
+
The BAT blocks are pointed at by the bat array
contained in the header and supplemented, if necessary,
by the XBAT blocks . These blocks form a large
@@ -337,10 +337,10 @@ public int getShort (byte[] rec)
as a block used to make up the Small Block Array, the
Property Table, the main BAT, or the SBAT
-
-
+
+
The following outlines the basic file system structures.
-
+
Field
@@ -505,8 +505,8 @@ public int getShort (byte[] rec)
-1
-
-
+
+
Field
@@ -532,8 +532,8 @@ public int getShort (byte[] rec)
-
-
+
+
Field
@@ -550,8 +550,8 @@ public int getShort (byte[] rec)
All unused space is set to -1.
-
-
+
+
Field
@@ -659,8 +659,8 @@ public int getShort (byte[] rec)
0
-
-
-
+
+
+
diff --git a/src/documentation/xdocs/poifs/how-to.xml b/src/documentation/xdocs/poifs/how-to.xml
index 7b1786de9..c9a14cfc9 100644
--- a/src/documentation/xdocs/poifs/how-to.xml
+++ b/src/documentation/xdocs/poifs/how-to.xml
@@ -1,5 +1,5 @@
-
+
-
+
This document describes how to use the POIFS APIs to read, write, and modify files that employ a POIFS-compatible data structure to organize their content.
-
+
02.10.2002 - completely rewritten from original documents on sourceforge
-
-
+
+
This document is intended for Java developers who need to use the POIFS APIs to read, write, or modify files that employ a POIFS-compatible data structure to organize their content. It is not necessary for developers to understand the POIFS data structures, and an explanation of those data structures is beyond the scope of this document. It is expected that the members of the target audience will understand the rudiments of a hierarchical file system, and familiarity with the event pattern employed by Java APIs such as AWT would be helpful.
-
-
+
+
This document attempts to be consistent in its terminology, which is defined here:
@@ -57,9 +57,9 @@
The directory at the base of a file system. All file systems have a root directory. The POIFS APIs will not allow the root directory to be removed or renamed, but it can be accessed for the purpose of reading its contents or adding files (directories and documents) to it.
-
-
-
+
+
+
This section covers reading a file system. There are two ways to read a file system; these techniques are sketched out in the following table, and then explained in greater depth in the sections following the table.
-
+
In this technique for reading, the entire file system is loaded into memory, and the entire directory tree can be walked by an application, reading specific documents at the application's leisure.
-
+
Before an application can read a file from the file system, the file system needs to be loaded into memory. This is done by using the org.apache.poi.poifs.filesystem.POIFSFileSystem
class. Once the file system has been loaded into memory, the application may need the root directory. The following code fragment will accomplish this preparation stage:
// need an open InputStream; for a file-based system, this would be appropriate:
@@ -119,8 +119,8 @@ catch (IOException e)
DirectoryEntry root = fs.getRoot();
Assuming no exception was thrown, the file system can then be read.
Note: loading the file system can take noticeable time, particularly for large file systems.
-
-
+
+
Once the file system has been loaded into memory and the root directory has been obtained, the root directory can be read. The following code fragment shows how to read the entries in an org.apache.poi.poifs.filesystem.DirectoryEntry
instance:
// dir is an instance of DirectoryEntry ...
@@ -143,10 +143,10 @@ for (Iterator iter = dir.getEntries(); iter.hasNext(); )
// internal data structure certainly allows for a lot more entry types.
}
}
-
-
+
+
There are a couple of ways to read a document, depending on whether the document resides in the root directory or in another directory. Either way, you will obtain an org.apache.poi.poifs.filesystem.DocumentInputStream
instance.
-
+
The DocumentInputStream class is a simple implementation of InputStream that makes a few guarantees worth noting:
available()
always returns the number of bytes in the document from your current position in the document.
@@ -161,8 +161,8 @@ byte[] content = new byte[ stream.available() ];
stream.read(content);
stream.close();
The combination of mark
, reset
, and skip
provide the basic mechanisms needed for random access of the document contents.
-
-
+
+
If the document resides in the root directory, you can obtain a DocumentInputStream
like this:
// load file system
@@ -176,19 +176,19 @@ catch (IOException e)
// no such document, or the Entry represented by documentName is not a
// DocumentEntry
}
-
-
+
+
A more generic technique for reading a document is to obtain an org.apache.poi.poifs.filesystem.DirectoryEntry
instance for the directory containing the desired document (recall that you can use getRoot()
to obtain the root directory from its file system). From that DirectoryEntry, you can then obtain a DocumentInputStream
like this:
DocumentEntry document = (DocumentEntry)directory.getEntry(documentName);
DocumentInputStream stream = new DocumentInputStream(document);
-
-
-
-
+
+
+
+
The event-driven API for reading documents is a little more complicated and requires that your application know, in advance, which files it wants to read. The benefit of using this API is that each document is in memory just long enough for your application to read it, and documents that you never read at all are not in memory at all. When you're finished reading the documents you wanted, the file system has no data structures associated with it at all and can be discarded.
-
+
The preparation phase involves creating an instance of org.apache.poi.poifs.eventfilesystem.POIFSReader
and to then register one or more org.apache.poi.poifs.eventfilesystem.POIFSReaderListener
instances with the POIFSReader
.
POIFSReader reader = new POIFSReader();
@@ -202,8 +202,8 @@ reader.registerListener(myOtherPickyListener, new POIFSDocumentPath(),
"fubar");
reader.registerListener(myOtherPickyListener, new POIFSDocumentPath(
new String[] { "usr", "bin" ), "fubar");
-
-
+
+
org.apache.poi.poifs.eventfilesystem.POIFSReaderListener
is an interface used to register for documents. When a matching document is read by the org.apache.poi.poifs.eventfilesystem.POIFSReader
, the POIFSReaderListener
instance receives an org.apache.poi.poifs.eventfilesystem.POIFSReaderEvent
instance, which contains an open DocumentInputStream
and information about the document.
A POIFSReaderListener
instance can register for individual documents, or it can register for all documents; once it has registered for all documents, subsequent (and previous!) registration requests for individual documents are ignored. There is no way to unregister a POIFSReaderListener
.
Thus, it is possible to register a single POIFSReaderListener
for multiple documents - one, some, or all documents. It is guaranteed that a single POIFSReaderListener
will receive exactly one notification per registered document. There is no guarantee as to the order in which it will receive notification of its documents, as future implementations of POIFSReader
are free to change the algorithm for walking the file system's directory structure.
@@ -228,8 +228,8 @@ reader.registerListener(myOtherPickyListener, new POIFSDocumentPath(
registers listener for a document with the specified name in the directory described by path
-
-
+
+
The org.apache.poi.poifs.filesystem.POIFSDocumentPath
class is used to describe a directory in a POIFS file system. Since there are no reserved characters in the name of a file in a POIFS file system, a more traditional string-based solution for describing a directory, with special characters delimiting the components of the directory name, is not feasible. The constructors for the class are used as follows:
@@ -257,26 +257,26 @@ reader.registerListener(myOtherPickyListener, new POIFSDocumentPath(
in Unix terminology, "/foo/fu/bar".
-
-
+
+
Processing org.apache.poi.poifs.eventfilesystem.POIFSReaderEvent
events is relatively easy. After all of the POIFSReaderListener
instances have been registered with POIFSReader
, the POIFSReader.read(InputStream stream)
method is called.
Assuming that there are no problems with the data, as the POIFSReader
processes the documents in the specified InputStream
's data, it calls registered POIFSReaderListener
instances' processPOIFSReaderEvent
method with a POIFSReaderEvent
instance.
The POIFSReaderEvent
instance contains information to identify the document (a POIFSDocumentPath
object to identify the directory that the document is in, and the document name), and an open DocumentInputStream
instance from which to read the document.
-
-
-
-
+
+
+
+
Writing a file system is very much like reading a file system in that there are multiple ways to do so. You can load an existing file system into memory and modify it (removing files, renaming files) and/or add new files to it, and write it, or you can start with a new, empty file system:
POIFSFileSystem fs = new POIFSFileSystem();
-
+
There are two restrictions on the names of files in a file system that must be considered when creating files:
The name of the file must not exceed 31 characters. If it does, the POIFS API will silently truncate the name to fit.
The name of the file must be unique within its containing directory. This seems pretty obvious, but if it isn't spelled out, there'll be hell to pay, to be sure. Uniqueness, of course, is determined after the name has been truncated, if the original name was too long to begin with.
-
-
+
+
A document can be created by acquiring a DirectoryEntry
and calling one of the two createDocument
methods:
@@ -316,13 +316,13 @@ POIFSFileSystem fs = new POIFSFileSystem();
Unlike reading, you don't have to choose between the in-memory and event-driven writing models; both can co-exist in the same file system.
Writing is initiated when the POIFSFileSystem
instance's writeFilesystem()
method is called with an OutputStream
to write to.
The event-driven model is quite similar to the event-driven model for reading, in that the file system calls your org.apache.poi.poifs.filesystem.POIFSWriterListener
when it's time to write your document, just as the POIFSReader
calls your POIFSReaderListener
when it's time to read your document. Internally, when writeFilesystem()
is called, the final POIFS data structures are created and are written to the specified OutputStream
. When the file system needs to write a document out that was created with the event-driven model, it calls the POIFSWriterListener
back, calling its processPOIFSWriterEvent()
method, passing an org.apache.poi.poifs.filesystem.POIFSWriterEvent
instance. This object contains the POIFSDocumentPath
and name of the document, its size, and an open org.apache.poi.poifs.filesystem.DocumentOutputStream
to which to write. A DocumentOutputStream
is a wrapper over the OutputStream
that was provided to the POIFSFileSystem
to write to, and has the responsibility of making sure that the document your application writes fits within the size you specified for it.
-
-
+
+
Creating a directory is similar to creating a document, except that there's only one way to do so:
DirectoryEntry createdDir = existingDir.createDirectory(name);
-
-
+
+
As with reading documents, it is possible to create a new document or directory in the root directory by using convenience methods of POIFSFileSystem.
@@ -342,28 +342,28 @@ DirectoryEntry createdDir = existingDir.createDirectory(name);
createDirectory(String name)
-
-
-
+
+
+
It is possible to modify an existing POIFS file system, whether it's one your application has loaded into memory, or one which you are creating on the fly.
-
+
Removing a document is simple: you get the Entry
corresponding to the document and call its delete()
method. This is a boolean method, but should always return true
, indicating that the operation succeeded.
-
-
+
+
Removing a directory is also simple: you get the Entry
corresponding to the directory and call its delete()
method. This is a boolean method, but, unlike deleting a document, may not always return true
, indicating that the operation succeeded. Here are the reasons why the operation may fail:
The directory still has files in it (to check, call isEmpty()
on its DirectoryEntry; is the return value false
?)
The directory is the root directory. You cannot remove the root directory.
-
-
+
+
Regardless of whether the file is a directory or a document, it can be renamed, with one exception - the root directory has a special name that is expected by the components of a major software vendor's office suite, and the POIFS API will not let that name be changed. Renaming is done by acquiring the file's corresponding Entry
instance and calling its renameTo
method, passing in the new name.
Like delete
, renameTo
returns true
if the operation succeeded, otherwise false
. Reasons for failure include these:
The new name is the same as another file in the same directory. And don't forget - if the new name is longer than 31 characters, it will be silently truncated. In its original length, the new name may have been unique, but truncated to 31 characters, it may not be unique any longer.
You tried to rename the root directory.
-
-
+
+
diff --git a/src/documentation/xdocs/poifs/index.xml b/src/documentation/xdocs/poifs/index.xml
index eb6fc54c2..aed66e789 100644
--- a/src/documentation/xdocs/poifs/index.xml
+++ b/src/documentation/xdocs/poifs/index.xml
@@ -10,7 +10,7 @@
-
+
POIFS is a pure Java implementation of the OLE 2 Compound
Document format.
By definition, all APIs developed by the POI project are
@@ -37,6 +37,6 @@
TODO: copy POIFS docs and port to XML (in progress). For now
please reference old
site.
-
+
diff --git a/src/documentation/xdocs/poifs/usecases.xml b/src/documentation/xdocs/poifs/usecases.xml
index 23688acad..079e2f80f 100644
--- a/src/documentation/xdocs/poifs/usecases.xml
+++ b/src/documentation/xdocs/poifs/usecases.xml
@@ -1,5 +1,5 @@
-
+
-
-
+
+
Primary Actor:
@@ -86,8 +86,8 @@
-
-
+
+
Primary Actor:
@@ -191,8 +191,8 @@
-
-
+
+
Primary Actor:
@@ -237,8 +237,8 @@
None
-
-
+
+
Primary Actor:
@@ -306,8 +306,8 @@
-
-
+
+
Primary Actor:
@@ -374,8 +374,8 @@
-
-
+
+
Primary Actor:
@@ -440,8 +440,8 @@
-
-
+
+
Primary Actor:
@@ -502,8 +502,8 @@
specified name exists.
-
-
+
+
Primary Actor:
@@ -556,8 +556,8 @@
None
-
-
+
+
Primary Actor:
@@ -617,8 +617,8 @@
extending past the known size of the file.
-
-
+
+
Primary Actor:
@@ -683,7 +683,7 @@
-
-
+
+
diff --git a/src/documentation/xdocs/resolutions/index.xml b/src/documentation/xdocs/resolutions/index.xml
index 7ff24c8d5..0e226450c 100644
--- a/src/documentation/xdocs/resolutions/index.xml
+++ b/src/documentation/xdocs/resolutions/index.xml
@@ -1,5 +1,5 @@
-
+
-
+
Every project on Jakarta has resolutions that they vote on.
Decisions are made, etc. But what happens once those decisions
@@ -32,6 +32,6 @@
discussions from taking away from whats important...developing
POI! :-D
-
+
diff --git a/src/documentation/xdocs/resolutions/res001.xml b/src/documentation/xdocs/resolutions/res001.xml
index f9cef302e..10519b3fd 100644
--- a/src/documentation/xdocs/resolutions/res001.xml
+++ b/src/documentation/xdocs/resolutions/res001.xml
@@ -1,5 +1,5 @@
-
+
-
-
+
+
As the POI project has grown the "styles" used have become more
varied, some see this as a bad thing, but in reality it
@@ -53,8 +53,8 @@
circumstances for doing so would be nice.
-
-
+
+
As opposed to the formerly used POI License which was
based on the Apache Public License, now that POI is part of
@@ -62,20 +62,20 @@
Apache Software Foundation requires us to use the full
long version.
-
-
+
+
The motion was passed unanimously with no negative or
positive votes.
-
-
+
+
Andy didn't feel like going through his mail and sucking
out the comments.. If there is anything you feel should
be added here do it yourself ;-).
-
-
+
+
diff --git a/src/documentation/xdocs/utils/index.xml b/src/documentation/xdocs/utils/index.xml
index 31b51c6f9..f3a554ea4 100644
--- a/src/documentation/xdocs/utils/index.xml
+++ b/src/documentation/xdocs/utils/index.xml
@@ -1,5 +1,5 @@
-
+
-
+
The POI Utils are classes we're looking to donate elsewhere and include.
These are usually classes that while are required for our mission,
@@ -29,6 +29,6 @@
find an alternative later, just keep pounding out that poi!"
-
+
diff --git a/src/documentation/xdocs/who.xml b/src/documentation/xdocs/who.xml
index 202a23d9f..c7341badc 100644
--- a/src/documentation/xdocs/who.xml
+++ b/src/documentation/xdocs/who.xml
@@ -12,7 +12,7 @@
-
+
The Poi Project operates on a meritocracy: the more you do, the more
responsibility you will obtain. This page lists all of the people who have
@@ -31,14 +31,14 @@
community we all grow together.
-
+
Stefano Mazzocchi (stefano at apache dot org)
-
+
-
+
Andrew C. Oliver (acoliver at apache dot org)
Marc Johnson (mjohnson at apache dot org)
@@ -46,13 +46,13 @@
Rainer Klute (klute at apache dot org)
Nicola Ken Barozzi (barozzi at nicolaken dot com)
-
-
+
+
Ryan Ackley (sackley at cfl dot rr dot com)
-
-
+
+