moparisthebest/poi
1
0
Fork 0
Code Issues Pull Requests Releases 1 Wiki Activity

Corrected the files to conform to the new DTD.

Browse Source 
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
This commit is contained in:
Nicola Ken Barozzi 2002-04-06 13:36:06 +00:00
parent 566004893a
commit 313ba122ba
38 changed files with 518 additions and 518 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

17
src/documentation/xdocs/3rdparty.xml
View File

@ -1,5 +1,4 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "./dtd/document-v11.dtd">
<document>
<header>
@ -11,14 +10,14 @@
<body>
<s1 title="How to Contribute">
<section title="How to Contribute">
<p>
See <link href="contrib.xml">How to contribute to Poi</link>.
</p>
</s1>
</section>
<s1 title="Contributed Components">
<section title="Contributed Components">
<p>
These are not necessarily deemed to be high enough quality to be included in the
core distribution, but they have been tested under <connect href="contrib.xml">
@ -32,18 +31,18 @@
listed below will eventually migrate to the "contributed components" level, and
then maybe even into the main distribution.
</p>
</s1>
</section>
<s1 title="Patch Queue">
<section title="Patch Queue">
<p><link href="patches.html">Submissions of modifications</link>
to Poi which are awaiting review. Anyone can
comment on them on the dev mailing list - code reviewers are needed!
<strong>Use these at your own risk</strong> - although Poi has no guarantee
either, these patches have not been reviewed, let alone accepted.
</p>
</s1>
</section>
<s1 title="Other Extensions">
<section title="Other Extensions">
<p>The other extensions listed here are <strong>not endorsed</strong> 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 @@
</tr>
</table>
</s1>
</section>
</body>
</document>

24
src/documentation/xdocs/contrib.xml
View File

@ -15,7 +15,7 @@
<body>
<s1 title="Introduction">
<section title="Introduction">
<p>
The POI Project is an <link href="http://www.opensource.org/">Open Source</link>
@ -48,9 +48,9 @@
we have work for you! And we'll be very available to you for any questions!
</p>
</s1>
</section>
<s1 title="Help Wanted Here">
<section title="Help Wanted Here">
<p>
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 @@
</li>
</ul>
</s1>
</section>
<anchor id="cvshowto"/>
<s1 title="CVS Usage Precis">
<section title="CVS Usage Precis">
<p>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.)
</p>
</s1>
</section>
<anchor id="ssh"/>
<s1 title="CVS Committer with Secure Shell access">
<section title="CVS Committer with Secure Shell access">
<p>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.</li>
</ul>
</s1>
</section>
<anchor id="procedure"/>
<s1 title="Procedure for Raising Development Issues">
<section title="Procedure for Raising Development Issues">
<p>
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.
</p>
</s1>
</section>
<anchor id="tips"/>
<s1 title="Contribution Notes and Tips">
<section title="Contribution Notes and Tips">
<p>
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.
</li>
</ul>
</s1>
</section>
</body>
</document>

3
src/documentation/xdocs/faq.xml
View File

@ -32,9 +32,10 @@
Why am I getting an exception each time I attempt to read my spreadsheet?
</question>
<answer>
<p>
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.
</p>
</answer>
</faq>
</faqs>

6
src/documentation/xdocs/hdf/index.xml
View File

@ -1,5 +1,5 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "../dtd/document-v10.dtd">
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "../dtd/document-v11.dtd">
<document>
<header>
@ -12,7 +12,7 @@
</header>
<body>
<s1 title="Overview">
<section title="Overview">
<p>HDF will be the name of OUR port of the Microsoft Word 97(-2002) file format to
pure Java.</p>
@ -20,6 +20,6 @@
follow development on the poi-dev mailing list.</p>
</s1>
</section>
</body>
</document>

8
src/documentation/xdocs/historyandfuture.xml
View File

@ -12,7 +12,7 @@
<body>
<s1 title="Brief Project History">
<section title="Brief Project History">
<p>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!
</p>
</s1>
</section>
<s1 title="What's next for POI">
<section title="What's next for POI">
<p>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! </p>
</s1>
</section>
</body>
<footer>

22
src/documentation/xdocs/hpsf/how-to.xml
View File

@ -1,6 +1,6 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN"
"../dtd/document-v10.dtd">
"../dtd/document-v11.dtd">
<!-- $Id$ -->
<document>
@ -11,7 +11,7 @@
</authors>
</header>
<body>
<s1 title="How To Use the HPSF APIs">
<section title="How To Use the HPSF APIs">
<p>This HOW-TO is organized in three section. You should read them
sequentially because the later sections build upon the earlier ones.</p>
@ -40,7 +40,7 @@
</ol>
<anchor id="sec1" />
<s2 title="Reading Standard Properties">
<section title="Reading Standard Properties">
<note>This section explains how to read
the most important standard properties of a Microsoft Office
@ -83,7 +83,7 @@
<p>Sounds easy, doesn't it? Here are the steps in detail.</p>
<s3 title="Open the document \005SummaryInformation in the root of the
<section title="Open the document \005SummaryInformation in the root of the
POI filesystem">
<p>An application that wants to open a document in a POI filesystem
@ -215,11 +215,11 @@ static class MyPOIFSReaderListener implements POIFSReaderListener
<em>\005SummaryInformation</em> stream. In this case the applications
won't throw an exception but simply does not call the
<code>processPOIFSReaderEvent</code> method. You have been warned!</p>
</s3>
</s2>
</section>
</section>
<anchor id="sec2"/>
<s2 title="Additional Standard Properties, Exceptions And Embedded Objects">
<section title="Additional Standard Properties, Exceptions And Embedded Objects">
<note>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.</p>
</s2>
</section>
<anchor id="sec3"/>
<s2 title="Reading Non-Standard Properties">
<section title="Reading Non-Standard Properties">
<note>This section tells how to read
non-standard properties. Non-standard properties are application-specific
name/value/type triples.</note>
<fixme author="Rainer Klute">Write this section!</fixme>
</s2>
</s1>
</section>
</section>
</body>
</document>

6
src/documentation/xdocs/hpsf/index.xml
View File

@ -1,5 +1,5 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "../dtd/document-v10.dtd">
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "../dtd/document-v11.dtd">
<!-- $Id$ -->
<document>
@ -11,7 +11,7 @@
</authors>
</header>
<body>
<s1 title="Overview">
<section title="Overview">
<p>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 <link
href="internals.html">HPSF description</link> describes the internal
structure of property set streams.</p>
</s1>
</section>
</body>
</document>

50
src/documentation/xdocs/hpsf/internals.xml
View File

@ -1,5 +1,5 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "../dtd/document-v10.dtd">
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "../dtd/document-v11.dtd">
<!-- $Id$ -->
<document>
@ -10,9 +10,9 @@
</authors>
</header>
<body>
<s1 title="HPSF Internals">
<section title="HPSF Internals">
<s2 title="Introduction">
<section title="Introduction">
<p>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.</p>
</s2>
</section>
<s2 title="Data Types">
<section title="Data Types">
<p>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 @@
</td>
</tr>
</table>
</s2>
</section>
<s2 title="HPSF Overview">
<section title="HPSF Overview">
<p>A property set stream consists of three main parts:</p>
@ -164,11 +164,11 @@
<p>the <strong>section(s)</strong> containing the properties.</p>
</li>
</ol>
</s2>
</section>
<s2 title="The Header">
<section title="The Header">
<p>The first bytes in a property set stream is the <strong>header</strong>.
It has a fixed length and looks like this:</p>
@ -265,11 +265,11 @@
</td>
</tr>
</table>
</s2>
</section>
<s2 title="Section List">
<section title="Section List">
<p>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 @@
</td>
</tr>
</table>
</s2>
</section>
<s2 title="Section">
<section title="Section">
<p>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 @@
</td>
</tr>
</table>
</s2>
</section>
<s2 title="Property IDs">
<section title="Property IDs">
<anchor id="property_ids"/>
<p>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.</p>
<s3 title="Property IDs in The Summary Information Stream">
<section title="Property IDs in The Summary Information Stream">
<p>The Summary Information stream has a single section with a section
format ID of <code>0xF29F85E04FF91068AB9108002B27B3D9</code>. The following
@ -672,11 +672,11 @@
<td><p>VT_I4</p></td>
</tr>
</table>
</s3>
</section>
<s3 title="Property IDs in The Document Summary Information Stream">
<section title="Property IDs in The Document Summary Information Stream">
<p>The Document Summary Information stream has two sections with a section
format ID of <code>0xD5CDD5022E9C101B939708002B2CF9AE</code> for the first
@ -781,12 +781,12 @@
<td><p>VT_BOOL</p></td>
</tr>
</table>
</s3>
</s2>
</section>
</section>
<s2 title="Property Types">
<section title="Property Types">
<anchor id="property_types"/>
<p>A property consists of a DWord <em>type field</em> followed by the
@ -1090,11 +1090,11 @@
<td><p><br/></p></td>
</tr>
</table>
</s2>
</section>
<s2 title="References">
<section title="References">
<p>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 @@
<p>This documentation origins from the <link href="http://www.rainer-klute.de/~klute/Software/poibrowser/doc/HPSF-Description.html">HPSF description</link> available at <link href="http://www.rainer-klute.de/~klute/Software/poibrowser/doc/HPSF-Description.html">http://www.rainer-klute.de/~klute/Software/poibrowser/doc/HPSF-Description.html</link>.</p>
</li>
</ol>
</s2>
</s1>
</section>
</section>
</body>
</document>

4
src/documentation/xdocs/hpsf/todo.xml
View File

@ -10,7 +10,7 @@
</authors>
</header>
<body>
<s1 title="To Do">
<section title="To Do">
<p>The following functionalities should be added to HPFS:</p>
@ -37,7 +37,7 @@
yet supported (other than byte arrays).</p>
</li>
</ol>
</s1>
</section>
</body>
</document>

6
src/documentation/xdocs/hssf/alternatives.xml
View File

@ -1,5 +1,5 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "../dtd/document-v10.dtd">
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "../dtd/document-v11.dtd">
<document>
<header>
@ -11,7 +11,7 @@
</header>
<body>
<s1 title="Alternatives">
<section title="Alternatives">
<p>
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 @@
<td>There are a number of perl and C libraries, however none of them are consistent.</td>
</tr>
</table>
</s1>
</section>
</body>
</document>

6
src/documentation/xdocs/hssf/diagram1.xml
View File

@ -1,5 +1,5 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "../dtd/document-v10.dtd">
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "../dtd/document-v11.dtd">
<document>
<header>
@ -12,8 +12,8 @@
</header>
<body>
<s1 title="Usermodel Class Diagram by Matthew Young">
<section title="Usermodel Class Diagram by Matthew Young">
<img src="images/usermodel.gif"/>
</s1>
</section>
</body>
</document>

6
src/documentation/xdocs/hssf/diagrams.xml
View File

@ -1,5 +1,5 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "../dtd/document-v10.dtd">
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "../dtd/document-v11.dtd">
<document>
<header>
@ -12,7 +12,7 @@
</header>
<body>
<s1 title="Overview">
<section title="Overview">
<p>
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.
</p>
</s1>
</section>
</body>
</document>

48
src/documentation/xdocs/hssf/how-to.xml
View File

@ -10,9 +10,9 @@
</authors>
</header>
<body>
<s1 title="How to use the HSSF prototype API">
<section title="How to use the HSSF prototype API">
<s2 title="Capabilities">
<section title="Capabilities">
<p>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.</p>
@ -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.</p>
</s2>
<s2 title="General Use">
<s3 title="User API">
<s4 title="Writing a new one">
</section>
<section title="General Use">
<section title="User API">
<section title="Writing a new one">
<p>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();
]]></source>
</s4>
<s4 title="Reading or modifying an existing file">
</section>
<section title="Reading or modifying an existing file">
<p>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.</p>
<p>An example of this can be seen in
<link href="http://cvs.apache.org/viewcvs/~checkout~/jakarta-poi/src/java/org/apache/poi/hssf/dev/HSSF.java?rev=1.1">org.apache.poi.hssf.dev.HSSF</link>.</p>
</s4>
</s3>
<s3 title="Event API">
</section>
</section>
<section title="Event API">
<p>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
}
}
]]></source>
</s3>
<s3 title="Low Level APIs">
</section>
<section title="Low Level APIs">
<p>The low level API is not much to look at. It consists of lots of
&quot;Records&quot; 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.</p>
</s3>
<s3 title="HSSF Class/Test Application">
</section>
<section title="HSSF Class/Test Application">
<p>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. </p></li>
</ul>
</s3>
<s3 title="HSSF Logging facility">
</section>
<section title="HSSF Logging facility">
<p>HSSF now has a logging facility (using
<link href="http://jakarta.apache.org/commons/logging.html">commons logging</link>)
that will record massive amounts of debugging information. Its mostly
@ -444,8 +444,8 @@ many cases the Commons Logging component can fill that role.</em>
Refer to the commons logging package level javadoc for more information concerning how to
<link href="http://jakarta.apache.org/commons/logging/api/index.html">configure commons logging.</link>
</p>
</s3>
<s3 title="HSSF Developer's tools">
</section>
<section title="HSSF Developer's tools">
<p>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 &quot;on&quot; exactly.</p>
FormulaViewer. The class is already there, but its not very useful
yet. When it does something, we'll document it.</p>
</s3>
<s3 title="What's Next?">
</section>
<section title="What's Next?">
<p>This release contains code that supports &quot;internationalization&quot;
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?
</p>
</s3>
</section>
</s2>
</section>
</s1>
</section>
</body>
</document>

6
src/documentation/xdocs/hssf/index.xml
View File

@ -1,5 +1,5 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "../dtd/document-v10.dtd">
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "../dtd/document-v11.dtd">
<document>
<header>
@ -12,7 +12,7 @@
</header>
<body>
<s1 title="Overview">
<section title="Overview">
<p>HSSF is the POI Project's pure Java implementation of the Excel '97(-2002) file format.</p>
<p>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.
</p>
</s1>
</section>
</body>
</document>

4
src/documentation/xdocs/hssf/limitations.xml
View File

@ -6,7 +6,7 @@
</authors>
</header>
<body>
<s1 title="Version 1.5 limitations">
<section title="Version 1.5 limitations">
<p>
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.
</li>
</ul>
</s1>
</section>
</body>
</document>

58
src/documentation/xdocs/hssf/quick-guide.xml
View File

@ -1,5 +1,5 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "../dtd/document-v10.dtd">
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "../dtd/document-v11.dtd">
<document>
<header>
@ -9,13 +9,13 @@
</authors>
</header>
<body>
<s1 title="Busy Developers' Guide to Features">
<section title="Busy Developers' Guide to Features">
<p>
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 <link href="how-to.html">HOWTO</link>
guide as it contains actual descriptions of how to use this stuff.
</p>
<s2 title="Index of Features">
<section title="Index of Features">
<ul>
<li><link href="#NewWorkbook">How to create a new workbook</link></li>
<li><link href="#NewSheet">How to create a sheet</link></li>
@ -29,19 +29,19 @@
<li><link href="#WorkingWithFonts">Working with fonts</link></li>
<li><link href="#ReadWriteWorkbook">Reading and writing</link></li>
</ul>
</s2>
<s2 title="Features">
</section>
<section title="Features">
<anchor id="NewWorkbook"/>
<s3 title="New Workbook">
<section title="New Workbook">
<source>
HSSFWorkbook wb = new HSSFWorkbook();
FileOutputStream fileOut = new FileOutputStream("workbook.xls");
wb.write(fileOut);
fileOut.close();
</source>
</s3>
</section>
<anchor id="NewSheet"/>
<s3 title="New Sheet">
<section title="New Sheet">
<source>
HSSFWorkbook wb = new HSSFWorkbook();
HSSFSheet sheet1 = wb.createSheet("new sheet");
@ -50,9 +50,9 @@
wb.write(fileOut);
fileOut.close();
</source>
</s3>
</section>
<anchor id="CreateCells"/>
<s3 title="Creating Cells">
<section title="Creating Cells">
<source>
HSSFWorkbook wb = new HSSFWorkbook();
HSSFSheet sheet = wb.createSheet("new sheet");
@ -73,9 +73,9 @@
wb.write(fileOut);
fileOut.close();
</source>
</s3>
</section>
<anchor id="CreateDateCells"/>
<s3 title="Creating Date Cells">
<section title="Creating Date Cells">
<source>
HSSFWorkbook wb = new HSSFWorkbook();
HSSFSheet sheet = wb.createSheet("new sheet");
@ -102,9 +102,9 @@
wb.write(fileOut);
fileOut.close();
</source>
</s3>
</section>
<anchor id="CellTypes"/>
<s3 title="Working with different types of cells">
<section title="Working with different types of cells">
<source>
HSSFWorkbook wb = new HSSFWorkbook();
HSSFSheet sheet = wb.createSheet("new sheet");
@ -120,9 +120,9 @@
wb.write(fileOut);
fileOut.close();
</source>
</s3>
</section>
<anchor id="Alignment"/>
<s3 title="Demonstrates various alignment options">
<section title="Demonstrates various alignment options">
<source>
public static void main(String[] args)
throws IOException
@ -162,9 +162,9 @@
cell.setCellStyle(cellStyle);
}
</source>
</s3>
</section>
<anchor id="Borders"/>
<s3 title="Working with borders">
<section title="Working with borders">
<source>
HSSFWorkbook wb = new HSSFWorkbook();
HSSFSheet sheet = wb.createSheet("new sheet");
@ -193,9 +193,9 @@
wb.write(fileOut);
fileOut.close();
</source>
</s3>
</section>
<anchor id="FillsAndFrills"/>
<s3 title="Fills and colors">
<section title="Fills and colors">
<source>
HSSFWorkbook wb = new HSSFWorkbook();
HSSFSheet sheet = wb.createSheet("new sheet");
@ -224,9 +224,9 @@
wb.write(fileOut);
fileOut.close();
</source>
</s3>
</section>
<anchor id="MergedCells"/>
<s3 title="Merging cells">
<section title="Merging cells">
<source>
HSSFWorkbook wb = new HSSFWorkbook();
HSSFSheet sheet = wb.createSheet("new sheet");
@ -242,9 +242,9 @@
wb.write(fileOut);
fileOut.close();
</source>
</s3>
</section>
<anchor id="WorkingWithFonts"/>
<s3 title="Working with fonts">
<section title="Working with fonts">
<source>
HSSFWorkbook wb = new HSSFWorkbook();
HSSFSheet sheet = wb.createSheet("new sheet");
@ -273,9 +273,9 @@
wb.write(fileOut);
fileOut.close();
</source>
</s3>
</section>
<anchor id="ReadWriteWorkbook"/>
<s3 title="Reading and Rewriting Workbooks">
<section title="Reading and Rewriting Workbooks">
<source>
POIFSFileSystem fs =
new POIFSFileSystem(new FileInputStream("workbook.xls"));
@ -293,8 +293,8 @@
wb.write(fileOut);
fileOut.close();
</source>
</s3>
</s2>
</s1>
</section>
</section>
</section>
</body>
</document>

26
src/documentation/xdocs/hssf/record-generator.xml
View File

@ -1,5 +1,5 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "../dtd/document-v10.dtd">
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "../dtd/document-v11.dtd">
<document>
<header>
@ -10,9 +10,9 @@
</authors>
</header>
<body>
<s1 title="How to Use the Record Generator">
<section title="How to Use the Record Generator">
<s2 title="History">
<section title="History">
<p>
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.
</p>
</s2>
</section>
<s2 title="Capabilities">
<section title="Capabilities">
<p>
The record generator takes XML as input and produced the following
output:
@ -35,8 +35,8 @@
for ensuring the record operates as designed.</li>
</ul>
</p>
</s2>
<s2 title="Usage">
</section>
<section title="Usage">
<p>
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.
</p>
</s2>
<s2 title="How it Works">
</section>
<section title="How it Works">
<p>
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
</p>
</s2>
<s2 title="Limitations">
</section>
<section title="Limitations">
<p>
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.
</p>
</s2>
</s1>
</section>
</section>
</body>
</document>

26
src/documentation/xdocs/hssf/use-case.xml
View File

@ -1,5 +1,5 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "../dtd/document-v10.dtd">
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "../dtd/document-v11.dtd">
<document>
<header>
@ -9,8 +9,8 @@
</authors>
</header>
<body>
<s1 title="HSSF Use Cases">
<s2 title="Use Case 1: Read existing HSSF">
<section title="HSSF Use Cases">
<section title="Use Case 1: Read existing HSSF">
<p><strong>Primary Actor:</strong> HSSF client</p>
<p><strong>Scope:</strong> HSSF</p>
@ -39,8 +39,8 @@
<p><strong>Extensions:</strong></p>
<p>2a. Exceptions
thrown by POIFS will be passed on to the HSSF client.</p>
</s2>
<s2 title="Use Case 2: Write HSSF file">
</section>
<section title="Use Case 2: Write HSSF file">
<p><strong>Primary Actor:</strong> HSSF client</p>
<p><strong>Scope:</strong> HSSF</p>
@ -77,8 +77,8 @@ thrown by POIFS will be passed on to the HSSF client.</p>
<p>3a. Exceptions
from POIFS are passed to the HSSF client.</p>
</s2>
<s2 title="Use Case 3:Create HSSF file">
</section>
<section title="Use Case 3:Create HSSF file">
<p><strong>Primary Actor:</strong> HSSF client</p>
<p><strong>Scope:</strong> HSSF</p>
@ -104,8 +104,8 @@ from POIFS are passed to the HSSF client.</p>
<p><strong>Extensions:</strong>
None</p>
</s2>
<s2 title="Use Case 4: Read workbook entry">
</section>
<section title="Use Case 4: Read workbook entry">
<p><strong>Primary Actor:</strong> HSSF</p>
<p><strong>Scope:</strong> HSSF</p>
<p>
@ -140,8 +140,8 @@ Guarantee:</strong> None</p>
<p><strong>Extensions:</strong></p>
<p>3a. Exceptions
thrown by POIFS will be passed on</p>
</s2>
<s2 title="Use Case 5: Write workbook entry">
</section>
<section title="Use Case 5: Write workbook entry">
<p><strong>Primary Actor:</strong> HSSF</p>
@ -175,8 +175,8 @@ thrown by POIFS will be passed on</p>
write new file to file system)</li>
</ol>
<p><strong>Extensions:</strong>None</p>
</s2>
</section>
</s1>
</section>
</body>
</document>

48
src/documentation/xdocs/index.xml
View File

@ -10,7 +10,7 @@
</header>
<body>
<s1 title="Logo Contest">
<section title="Logo Contest">
<p>
The POI committers have voted to
<link href="http://jakarta.apache.org/ant">"innovate"</link> and hold a
@ -62,8 +62,8 @@
You can see the current submissions <link
href="news/logocontest.html">here.</link>
</p>
</s1>
<s1 title="Purpose">
</section>
<section title="Purpose">
<p>
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 <link href="http://jakarta.apache.org/lucene">Lucene</link> for which we'll soon have file
format interpretors. When practical, we donate components directly to those projects for POI-enabling them.
</p>
<s2 title="Why/when would I use POI?">
<section title="Why/when would I use POI?">
<p>
We'll tackle this on a component level. POI refers to the whole project.
</p>
@ -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.
</p>
</s2>
</section>
<s2 title="What does POI stand for?">
<section title="What does POI stand for?">
<p>
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.
</p>
</s2>
</section>
</s1>
</section>
<s1 title="Components To Date">
<s2 title="Overview">
<section title="Components To Date">
<section title="Overview">
<p>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.</p>
</s2>
<s2 title="POIFS (POI Filesystem)">
</section>
<section title="POIFS (POI Filesystem)">
<p>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 <link href="./poifs/index.html">the POIFS project page</link> for more information.</p>
</s2>
<s2 title="HSSF (Horrible Spreadsheet Format)">
</section>
<section title="HSSF (Horrible Spreadsheet Format)">
<p>HSSF is our port of the Microsoft Excel 97(-2002) file format (BIFF8) to pure Java. It supports read and write
capability. Please see <link href="./hssf/index.html">the HSSF project page</link> for more information.</p>
</s2>
<s2 title="HDF (Horrible Document Format)">
</section>
<section title="HDF (Horrible Document Format)">
<p>HDF is our port of the Microsoft Word 97 file format to pure Java. It supports read and write capability.
Please see <link href="./hdf/index.html">the HDF project page for more information</link>. This component is
in the early stages of design. Jump in!</p>
</s2>
<s2 title="HPSF (Horrible Property Set Format)">
</section>
<section title="HPSF (Horrible Property Set Format)">
<p>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 <link
href="./hpsf/index.html">the HPSF project page</link> for more
information.</p>
</s2>
</section>
</s1>
</section>
<s1 title="What happened to the HSSF Serializer?">
<section title="What happened to the HSSF Serializer?">
<p>The HSSF Serializer, which was part of our 1.0 release and last builds on
<link href="http://www.sourceforge.net/projects/poi">Sourceforge</link>, has been donated to the Cocoon project. We're
currently in the process of porting it over.</p>
</s1>
</section>
<s1 title="Contributing ">
<section title="Contributing ">
<p>
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 @@
</p>
</s1>
</section>
</body>
<footer>
<legal>

28
src/documentation/xdocs/inthenews.xml
View File

@ -10,7 +10,7 @@
</header>
<body>
<s1 title="POI in the news">
<section title="POI in the news">
<p>
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).
</p>
</s1>
<s1 title="English">
</section>
<section title="English">
<ul>
<li>
<link href="http://www.need-a-cake.com/categories/cocoonWeblog/2002/03/07.html">
@ -78,8 +78,8 @@
</li>
</ul>
</s1>
<s1 title="Deutsch (German)">
</section>
<section title="Deutsch (German)">
<ul>
<li>
<link
@ -88,8 +88,8 @@
</link> - entwickler.com
</li>
</ul>
</s1>
<s1 title="Español (Spanish)">
</section>
<section title="Español (Spanish)">
<ul>
<li>
<link href="http://www.javahispano.com/noticias/todas.jsp">
@ -98,8 +98,8 @@
</li>
</ul>
</s1>
<s1 title="Francais (French)">
</section>
<section title="Francais (French)">
<ul>
<li>
<link href="http://linuxfr.org/section/D%E9veloppeur,0,1,8,0.html">
@ -107,8 +107,8 @@
</link> - Da Linux French Page
</li>
</ul>
</s1>
<s1 title="Nihongo (Japanese)">
</section>
<section title="Nihongo (Japanese)">
<ul>
<li>
<link
@ -118,13 +118,13 @@
</li>
</ul>
</s1>
<s1 title="No freaking idea">
</section>
<section title="No freaking idea">
<p>
If you can read one of these languages, send mail to the list
telling us what language it is and we'll categorize it!
</p>
</s1>
</section>
</body>
<footer>
<legal>

6
src/documentation/xdocs/livesites.xml
View File

@ -14,7 +14,7 @@
</header>
<body>
<s1 title="Live Sites using Poi">
<section title="Live Sites using Poi">
<p>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 @@
<ul>
<li><link href=""></link></li>
</ul>
</s1>
</section>
-->
</s1>
</section>
</body>
</document>

4
src/documentation/xdocs/mail-archives.xml
View File

@ -12,7 +12,7 @@
<body>
<s1 title="Mailing List Archives">
<section title="Mailing List Archives">
<p>
There are a number of mailing list archives available.
</p>
@ -37,7 +37,7 @@
<td>?</td>
</tr>
</table>
</s1>
</section>
</body>
</document>

16
src/documentation/xdocs/mail-lists.xml
View File

@ -10,7 +10,7 @@
</authors>
</header>
<body><s1 title="Important Notice">
<body><section title="Important Notice">
<p><strong>IMPORTANT: Before posting a question or problem to any mailing list,
</strong>please first look at the following resources in this order:</p>
<ol>
@ -26,9 +26,9 @@
work smarter.
See tips for <link href="contrib.html#tips">Contributing</link>
</p>
</s1>
</section>
<s1 title="Poi Users">
<section title="Poi Users">
<p><link href="mailto://poi-user-subscribe@jakarta.apache.org">Subscribe</link>
<link href="mailto://poi-user-unsubscribe@jakarta.apache.org">Unsubscribe</link>
</p>
@ -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.</p>
</s1>
</section>
<s1 title="Poi Dev">
<section title="Poi Dev">
<p><link href="mailto://poi-dev-subscribe@jakarta.apache.org">Subscribe</link>
<link href="mailto://poi-dev-unsubscribe@jakarta.apache.org">Unsubscribe</link>
</p>
@ -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).</p>
</s1>
</section>
<s1 title="Related Mailing Lists">
<section title="Related Mailing Lists">
<p>(See also <link href="http://dmoz.org/Computers/Data_Formats/Markup_Languages/XML/">
ODP XML links</link> for related websites.)</p>
@ -92,6 +92,6 @@
<link href="mailto:tomcat-user-subscribe@jakarta.apache.org">tomcat-user</link> (note it is "user"
and not "users").</li>
</ul>
</s1>
</section>
</body>
</document>

20
src/documentation/xdocs/news/logocontest.xml
View File

@ -10,33 +10,33 @@
</header>
<body>
<s1 title="POI logos">
<section title="POI logos">
<p>
Here are the current logo submissions. Thanks to the artists!
</p>
<s2 title="Michael Mosmann">
<section title="Michael Mosmann">
<p>
<img src="images/logoMichaelMosmann.png"/>
</p>
</s2>
<s2 title="Loïc Lefèvre">
</section>
<section title="Loïc Lefèvre">
<p>
<img src="images/logoLoicLefevre.png"/>&nbsp;&nbsp;&nbsp;
<img src="images/logoLoicLefevre2.png"/>
</p>
</s2>
<s2 title="Glen Stampoultzis">
</section>
<section title="Glen Stampoultzis">
<p>
<img src="images/logoGlenStampoutlzis.png"/>
</p>
</s2>
<s2 title="Marcus Gustafsson">
</section>
<section title="Marcus Gustafsson">
<p>
<img src="images/logoGustafsson1.png"/>&nbsp;&nbsp;&nbsp;
<img src="images/logoGustafsson2.png"/>
</p>
</s2>
</s1>
</section>
</section>
</body>
<footer>
<legal>

28
src/documentation/xdocs/overview.xml
View File

@ -10,47 +10,47 @@
</header>
<body>
<s1 title="What is it?">
<section title="What is it?">
<p>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.
</p>
</s1>
<s1 title="Sub-Projects">
</section>
<section title="Sub-Projects">
<p>
There following are ports, packages or components contained in the POI project.
</p>
<s2 title="POIFS">
<section title="POIFS">
<p>
<link href="poifs/index.html">POIFS</link> is the set of APIs
for reading and writing OLE 2 Compound Document Formats using (only) Java.
</p>
</s2>
</section>
<s2 title="HSSF">
<section title="HSSF">
<p>
<link href="hssf/index.html">HSSF</link> is the set of APIs
for reading and writing Microsoft Excel 97(-XP) spreadsheet using (only) Java.
</p>
</s2>
</section>
<s2 title="HDF">
<section title="HDF">
<p>
<link href="hdf/index.html">HDF</link> is the set of APIs
for reading and writing Microsoft Word 97(-XP) spreadsheet using (only) Java.
</p>
</s2>
</section>
<s2 title="HPSF">
<section title="HPSF">
<p>
<link href="hpsf/index.html">HPSF</link> is the set of APIs
for reading property sets using (only) Java.
</p>
</s2>
</section>
<s2 title="POI-Utils">
<section title="POI-Utils">
<p>
<link href="utils/index.html">POI-Utils</link> 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.
</p>
</s2>
</s1>
</section>
</section>
</body>
<footer>
<legal>

6
src/documentation/xdocs/patches.xml
View File

@ -1,7 +1,7 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "./dtd/document-v11.dtd">
<document><header><title>Patch Queue</title><authors><person email="greenrd@hotmail.com" name="Robin Green"/><person email="barozzi@nicolaken.com" name="Nicola Ken Barozzi"/></authors></header><body><s1 title="Introduction"><p>
<document><header><title>Patch Queue</title><authors><person email="greenrd@hotmail.com" name="Robin Green"/><person email="barozzi@nicolaken.com" name="Nicola Ken Barozzi"/></authors></header><body><section title="Introduction"><p>
This is an <strong>informal</strong> list - in chronological order -
of some of the noteworthy patches that have been posted
to the <code>developers</code> mailing list.
@ -17,7 +17,7 @@
Contributions</connect>. The preferred submission method for patches is:
</p><ul><li>Post to Poi developers list</li><li>Describe the patch, the reason for it and (if necessary) why this is important.</li><li>Generate the patch in <code>diff -u</code> format from CVS</li><li>Also generate a documentation patch or new file, if this is something that should be documented.
</li><li>Post as an attachment rather than inline (unless it is trivially small).</li></ul><p>Following the above guidelines will facilitate your patch being reviewed
and applied efficiently.</p></s1><s1 title="Patch Queue"><p><strong> [Under Construction] </strong> Archive links will be added later.
and applied efficiently.</p></section><section title="Patch Queue"><p><strong> [Under Construction] </strong> Archive links will be added later.
<strong>Please do not bother the patch submitters/authors</strong> without first reading the
relevant post(s) in the <connect href="mail-archives.xml">mailing list archives.</connect></p><p>Vapourware will not be listed.</p><table><tr><th>id</th><th>Summary</th><th>Reviewer</th><th>Resolution</th><th>Status</th></tr></table><p>See also additional list of patches to be added in <connect href="todo.xml">To Do</connect>.
</p></s1></body></document>
</p></section></body></document>

132
src/documentation/xdocs/plan/POI10Vision.xml
View File

@ -12,7 +12,7 @@
<body>
<s1 title="Preface">
<section title="Preface">
<p>
(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?)
</p>
</s1>
</section>
<s1 title="1. Introduction">
<s2 title="1.1 Purpose of this document">
<section title="1. Introduction">
<section title="1.1 Purpose of this document">
<p>
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.
</p>
</s2>
</section>
<s2 title="1.2 Project Overview">
<section title="1.2 Project Overview">
<p>
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 @@
</li>
</ul>
</s2>
</s1>
<s1 title="2. User Description">
<s2 title="2.1 User/Market Demographics">
</section>
</section>
<section title="2. User Description">
<section title="2.1 User/Market Demographics">
<p>
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.
</li>
</ol>
</s2>
<s2 title="2.2. User environment">
</section>
<section title="2.2. User environment">
<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>
</s2>
<s2 title="2.3. Key User Needs">
</section>
<section title="2.3. Key User Needs">
<p>
The OLE 2 Compound Document format is
undocumented for all practical purposes and cryptic for all
@ -156,16 +156,16 @@
</p>
</s2>
<s2 title="2.4. Alternatives and Competition">
</section>
<section title="2.4. Alternatives and Competition">
<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>
</s2>
</s1>
<s1 title="3. Project Overview">
<s2 title="3.1. Project Perspective">
</section>
</section>
<section title="3. Project Overview">
<section title="3.1. Project Perspective">
<p>
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).
</p>
</s2>
<s2 title="3.2. Project Position Statement">
</section>
<section title="3.2. Project Position Statement">
<p>
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.
</p>
</s2>
<s2 title="3.3. Summary of Capabilities">
</section>
<section title="3.3. Summary of Capabilities">
<p>
HSSF Serializer for Apache Cocoon 2
</p>
@ -239,8 +239,8 @@
</td>
</tr>
</table>
</s2>
<s2 title="3.4. Assumptions and Dependencies">
</section>
<section title="3.4. Assumptions and Dependencies">
<ul>
<li>
The HSSF Serializer will run on
@ -256,9 +256,9 @@
implementation.
</li>
</ul>
</s2>
</s1>
<s1 title="4. Project Features">
</section>
</section>
<section title="4. Project Features">
<p>
The POIFS API will include:
</p>
@ -295,7 +295,7 @@
about the Excel format itself.
</li>
</ul>
<s2 title="4.1 POI Filesystem API">
<section title="4.1 POI Filesystem API">
<p>
The POI Filesystem API includes:
</p>
@ -329,8 +329,8 @@
with system specifications and execution times for given operations)
</li>
</ul>
</s2>
<s2 title="4.2 HSSF API">
</section>
<section title="4.2 HSSF API">
<p>
The HSSF API includes:
</p>
@ -364,8 +364,8 @@
specifications and execution times for given operations - possibly
the same files used for POI's tests)</li>
</ul>
</s2>
<s2 title="4.3 HSSF Serializer">
</section>
<section title="4.3 HSSF Serializer">
<p>
The HSSF Serializer subproject:
</p>
@ -384,15 +384,15 @@
(Example XML docs and stylesheets rated by some measure of
complexity along with system specifications and execution times)</li>
</ul>
</s2>
</s1>
<s1 title="5. Other Product Requirements">
<s2 title="5.1. Applicable Standards">
</section>
</section>
<section title="5. Other Product Requirements">
<section title="5.1. Applicable Standards">
<p>
All Java code will be 100% pure Java.
</p>
</s2>
<s2 title="5.2. System Requirements">
</section>
<section title="5.2. System Requirements">
<p>
The minimum system requirements for POIFS are:
</p>
@ -421,15 +421,15 @@
<li>HSSF API</li>
<li>POI API</li>
</ul>
</s2>
<s2 title="5.3. Performance Requirements">
</section>
<section title="5.3. Performance Requirements">
<p>
All components must perform well enough
to be practical for use in a webserver environment (especially
Cocoon2/Tomcat/Apache combo)
</p>
</s2>
<s2 title="5.4. Environmental Requirements">
</section>
<section title="5.4. Environmental Requirements">
<p>
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.
</p>
</s2>
</s1>
<s1 title="6. Documentation Requirements">
<s2 title="6.1 POI Filesystem">
</section>
</section>
<section title="6. Documentation Requirements">
<section title="6.1 POI Filesystem">
<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>
</s2>
<s2 title="6.2. POI API">
</section>
<section title="6.2. POI API">
<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>
</s2>
<s2 title="6.3. HSSF File Format">
</section>
<section title="6.3. HSSF File Format">
<p>
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 &quot;legal stuff&quot;.
</p>
</s2>
<s2 title="6.4. HSSF API">
</section>
<section title="6.4. HSSF API">
<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>
</s2>
</section>
<s2 title="6.5. HSSF Serializer">
<section title="6.5. HSSF Serializer">
<p>
The HSSF Serializer will be documented
by javadoc.
</p>
</s2>
</section>
<s2 title="6.6 HSSF Serializer Tag language">
<section title="6.6 HSSF Serializer Tag language">
<p>
The XML tag language along with
function and usage shall be fully documented. Examples will be
provided as well.
</p>
</s2>
</s1>
<s1 title="7. Terminology">
<s2 title="7.1 Filesystem">
</section>
</section>
<section title="7. Terminology">
<section title="7.1 Filesystem">
<p>
filesystem shall refer only to the POI formatted archive.
</p>
</s2>
<s2 title="7.2 File">
</section>
<section title="7.2 File">
<p>
file shall refer to the embedded data stream within a
POI filesystem. This will be the actual embedded document.
</p>
</s2>
</s1>
</section>
</section>
</body>
</document>

128
src/documentation/xdocs/plan/POI20Vision.xml
View File

@ -14,7 +14,7 @@
<body>
<s1 title="Preface">
<section title="Preface">
<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
@ -35,10 +35,10 @@
other groups), but they are no longer technically part of the
POI project itself.
</p>
</s1>
</section>
<s1 title="1. Introduction">
<s2 title="1.1 Purpose of this document">
<section title="1. Introduction">
<section title="1.1 Purpose of this document">
<p>
The purpose of this document is to
collect, analyze and define high-level requirements, user needs,
@ -78,10 +78,10 @@
Java.</li>
</ul>
</s2>
</section>
<s2 title="1.2 Project Overview">
<section title="1.2 Project Overview">
<p>
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)
</li>
</ul>
</s2>
</s1>
<s1 title="2. User Description">
<s2 title="2.1 User/Market Demographics">
</section>
</section>
<section title="2. User Description">
<section title="2.1 User/Market Demographics">
<p>
There are a number of enthusiastic
users of XML, UNIX and Java technology. Furthermore, the Microsoft
@ -163,15 +163,15 @@
creation to their projects.
</li>
</ol>
</s2>
<s2 title="2.2. User environment">
</section>
<section title="2.2. User environment">
<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>
</s2>
<s2 title="2.3. Key User Needs">
</section>
<section title="2.3. Key User Needs">
<p>
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.
</p>
</s2>
<s2 title="2.4. Alternatives and Competition">
</section>
<section title="2.4. Alternatives and Competition">
<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>
</s2>
</s1>
<s1 title="3. Project Overview">
<s2 title="3.1. Project Perspective">
</section>
</section>
<section title="3. Project Overview">
<section title="3.1. Project Perspective">
<p>
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.
</p>
</s2>
<s2 title="3.2. Project Position Statement">
</section>
<section title="3.2. Project Position Statement">
<p>
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.
</p>
</s2>
<s2 title="3.3. Summary of Capabilities">
</section>
<section title="3.3. Summary of Capabilities">
<p>
HSSF Serializer for Apache Cocoon 2
</p>
@ -315,8 +315,8 @@
</tr>
</table>
</s2>
<s2 title="3.4. Assumptions and Dependencies">
</section>
<section title="3.4. Assumptions and Dependencies">
<ul>
<li>
The HSSF Serializer and Generator
@ -355,9 +355,9 @@
</li>
</ul>
</s2>
</s1>
<s1 title="4. Project Features">
</section>
</section>
<section title="4. Project Features">
<p>
Enhancements to the POIFS API will
include:
@ -434,14 +434,14 @@
format or enhancements to existing documentation.
</li>
</ul>
</s1>
<s1 title="5. Other Product Requirements">
<s2 title="5.1. Applicable Standards">
</section>
<section title="5. Other Product Requirements">
<section title="5.1. Applicable Standards">
<p>
All Java code will be 100% pure Java.
</p>
</s2>
<s2 title="5.2. System Requirements">
</section>
<section title="5.2. System Requirements">
<p>
The minimum system requirements for the POIFS API are:
</p>
@ -480,15 +480,15 @@
<li>HSSF API</li>
<li>POI API</li>
</ul>
</s2>
<s2 title="5.3. Performance Requirements">
</section>
<section title="5.3. Performance Requirements">
<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>
</s2>
<s2 title="5.4. Environmental Requirements">
</section>
<section title="5.4. Environmental Requirements">
<p>
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.
</p>
</s2>
</s1>
<s1 title="6. Documentation Requirements">
<s2 title="6.1 POI Filesystem">
</section>
</section>
<section title="6. Documentation Requirements">
<section title="6.1 POI Filesystem">
<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>
</s2>
<s2 title="6.2. POI API">
</section>
<section title="6.2. POI API">
<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>
</s2>
<s2 title="6.3. HSSF File Format">
</section>
<section title="6.3. HSSF File Format">
<p>
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.
</p>
</s2>
<s2 title="6.4. HSSF API">
</section>
<section title="6.4. HSSF API">
<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>
</s2>
<s2 title="6.5 HDF API">
</section>
<section title="6.5 HDF API">
<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>
</s2>
<s2 title="6.6 HSSF Serializer">
</section>
<section title="6.6 HSSF Serializer">
<p>
The HSSF Serializer will be documented
by javadoc.
</p>
</s2>
<s2 title="6.7 HSSF Generator">
</section>
<section title="6.7 HSSF Generator">
<p>
The HSSF Generator will be documented
by javadoc.
</p>
</s2>
<s2 title="6.8 HSSF Serializer Tag language">
</section>
<section title="6.8 HSSF Serializer Tag language">
<p>
The XML tag language along with
function and usage shall be fully documented. Examples will be
provided as well.
</p>
</s2>
</s1>
<s1 title="7. Terminology">
<s2 title="7.1 Filesystem">
</section>
</section>
<section title="7. Terminology">
<section title="7.1 Filesystem">
<p>
filesystem shall refer only to the POI formatted archive.
</p>
</s2>
<s2 title="7.2 File">
</section>
<section title="7.2 File">
<p>
file shall refer to the embedded data stream within a
POI filesystem. This will be the actual embedded document.
</p>
</s2>
</s1>
</section>
</section>
</body>
</document>

8
src/documentation/xdocs/plan/index.xml
View File

@ -12,7 +12,7 @@
</header>
<body>
<s1 title="Overview">
<section title="Overview">
<p>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.
</p>
</s1>
</section>
<s1 title="Topics and Issues">
<section title="Topics and Issues">
<ul>
<li><link href="release.html">Release Plan</link>
@ -52,7 +52,7 @@
<li>See the general <link href="../todo.html">To Do</link> list
and the <code>dev</code> email archives for other issues</li>
</ul>
</s1>
</section>
</body>
</document>

4
src/documentation/xdocs/plan/release.xml
View File

@ -12,7 +12,7 @@
</header>
<body>
<s1 title="Preparation for release of Poi">
<section title="Preparation for release of Poi">
<p>Todo</p>
<!-- NKB todo
<p>The 2.0 final release is scheduled for the end of November 2001.
@ -57,7 +57,7 @@ until last.
components have suitable licensing requirements.
]]></source>
-->
</s1>
</section>
</body>
</document>

74
src/documentation/xdocs/poifs/fileformat.xml
View File

@ -1,5 +1,5 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "../dtd/document-v10.dtd">
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "../dtd/document-v11.dtd">
<document>
<header>
<authors>
@ -7,8 +7,8 @@
</authors>
</header>
<body>
<s1 title="POIFS File System Internals">
<s2 title="Introduction">
<section title="POIFS File System Internals">
<section title="Introduction">
<p>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 &quot;.doc&quot;, you would actually
have a POIFS file system with a document file archived
inside of that file system.</p>
</s2>
<s2 title="Document Conventions">
</section>
<section title="Document Conventions">
<p>This document utilizes the numeric types as described by
the Java Language Specification, which can be found at
<link href="http://java.sun.com">http://java.sun.com</link>. In
@ -67,8 +67,8 @@ public int getShort (byte[] rec)
{
return ((rec[1] &lt;&lt; 8) | (rec[0] &amp; 0x00ff));
}</source>
</s2>
<s2 title="File System Walkthrough">
</section>
<section title="File System Walkthrough">
<p>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 &quot;big picture&quot; 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.</p>
</s2>
<s3 title="Header Block">
</section>
<section title="Header Block">
<p>The POIFS file system begins with a <b>header
block</b>. The first 64 bits of the header form a long
<b>file type id</b> or <b>magic number identifier</b> of
@ -127,14 +127,14 @@ public int getShort (byte[] rec)
<p>It's important to know the most important parts of the
header. These are discussed in the rest of this
section.</p>
<s4 title="BATs">
<section title="BATs">
<p>At offset <b>0x2C</b> is an int specifying the number
of elements in the <b>BAT array</b>. The array at
<b>0x4C</b> an array of ints. This array contains the
indices of every block in the Block Allocation
Table.</p>
</s4>
<s4 title="XBATs">
</section>
<section title="XBATs">
<p>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.</p>
</s4>
<s4 title="SBATs">
</section>
<section title="SBATs">
<p>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).</p>
</s4>
<s4 title="Property Table Start Index">
</section>
<section title="Property Table Start Index">
<p>An integer at address <b>0x30</b> specifies the start
index of the property table. This integer is specified
as a <b>&quot;block index&quot;</b>. 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.</p>
</s4>
</s3>
<s3 title="Property Table">
</section>
</section>
<section title="Property Table">
<p>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.</li>
</ul>
</s3>
<s3 title="Root Entry">
</section>
<section title="Root Entry">
<p>The <b>Root Entry</b> in the <b>Property Table</b>
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).</p>
</s3>
<s3 title="Walking the Nodes of the Property Table">
</section>
<section title="Walking the Nodes of the Property Table">
<p>The individual properties form a directory tree, with the
<b>Root Entry</b> 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)
<b>CHILD_PROP</b> fields contain the marker value of
-1. All file properties have a value of -1 for their
CHILD_PROP fields for example.</p>
</s3>
<s3 title="Block Allocation Table">
</section>
<section title="Block Allocation Table">
<p>The <b>BAT blocks</b> are pointed at by the bat array
contained in the header and supplemented, if necessary,
by the <b>XBAT blocks</b>. 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</li>
</ul>
</s3>
<s2 title="File System Structures">
</section>
<section title="File System Structures">
<p>The following outlines the basic file system structures.</p>
<s3 title="Header (block 1) -- 512 (0x200) bytes">
<section title="Header (block 1) -- 512 (0x200) bytes">
<table>
<tr>
<td><b>Field</b></td>
@ -505,8 +505,8 @@ public int getShort (byte[] rec)
<td>-1</td>
</tr>
</table>
</s3>
<s3 title="Block Allocation Table Block -- 512 (0x200) bytes">
</section>
<section title="Block Allocation Table Block -- 512 (0x200) bytes">
<table>
<tr>
<td><B>Field</B></td>
@ -532,8 +532,8 @@ public int getShort (byte[] rec)
</td>
</tr>
</table>
</s3>
<s3 title="Property Block -- 512 (0x200) byte block">
</section>
<section title="Property Block -- 512 (0x200) byte block">
<table>
<tr>
<td><B>Field</B></td>
@ -550,8 +550,8 @@ public int getShort (byte[] rec)
<td>All unused space is set to -1.</td>
</tr>
</table>
</s3>
<s3 title="Property -- 128 (0x80) byte block">
</section>
<section title="Property -- 128 (0x80) byte block">
<table>
<tr>
<td><B>Field</B></td>
@ -659,8 +659,8 @@ public int getShort (byte[] rec)
<td>0</td>
</tr>
</table>
</s3>
</s2>
</s1>
</section>
</section>
</section>
</body>
</document>

106
src/documentation/xdocs/poifs/how-to.xml
View File

@ -1,5 +1,5 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "../dtd/document-v10.dtd">
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "../dtd/document-v11.dtd">
<document>
<header>
<authors>
@ -7,17 +7,17 @@
</authors>
</header>
<body>
<s1 title="How To Use the POIFS APIs">
<section title="How To Use the POIFS APIs">
<p>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.</p>
<s2 title="Revision History">
<section title="Revision History">
<ul>
<li>02.10.2002 - completely rewritten from original documents on <link href="https://sourceforge.net/cvs/?group_id=32701">sourceforge</link></li>
</ul>
</s2>
<s2 title="Target Audience">
</section>
<section title="Target Audience">
<p>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.</p>
</s2>
<s2 title="Glossary">
</section>
<section title="Glossary">
<p>This document attempts to be consistent in its terminology, which is defined here:</p>
<table>
<tr>
@ -57,9 +57,9 @@
<td>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.</td>
</tr>
</table>
</s2>
</s1>
<s1 title="Reading a File System">
</section>
</section>
<section title="Reading a File System">
<p>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.</p>
<table>
<tr>
@ -99,9 +99,9 @@
</td>
</tr>
</table>
<s2 title="Conventional Reading">
<section title="Conventional Reading">
<p>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.</p>
<s3 title="Preparation">
<section title="Preparation">
<p>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 <code>org.apache.poi.poifs.filesystem.POIFSFileSystem</code> 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:</p>
<source>
// need an open InputStream; for a file-based system, this would be appropriate:
@ -119,8 +119,8 @@ catch (IOException e)
DirectoryEntry root = fs.getRoot();</source>
<p>Assuming no exception was thrown, the file system can then be read.</p>
<p>Note: loading the file system can take noticeable time, particularly for large file systems.</p>
</s3>
<s3 title="Reading the Directory Tree">
</section>
<section title="Reading the Directory Tree">
<p>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 <code>org.apache.poi.poifs.filesystem.DirectoryEntry</code> instance:</p>
<source>
// 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.
}
}</source>
</s3>
<s3 title="Reading a Specific Document">
</section>
<section title="Reading a Specific Document">
<p>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 <code>org.apache.poi.poifs.filesystem.DocumentInputStream</code> instance.</p>
<s4 title="DocumentInputStream">
<section title="DocumentInputStream">
<p>The DocumentInputStream class is a simple implementation of InputStream that makes a few guarantees worth noting:</p>
<ul>
<li><code>available()</code> always returns the number of bytes in the document from your current position in the document.</li>
@ -161,8 +161,8 @@ byte[] content = new byte[ stream.available() ];
stream.read(content);
stream.close();</source>
<p>The combination of <code>mark</code>, <code>reset</code>, and <code>skip</code> provide the basic mechanisms needed for random access of the document contents.</p>
</s4>
<s4 title="Reading a Document From the Root Directory">
</section>
<section title="Reading a Document From the Root Directory">
<p>If the document resides in the root directory, you can obtain a <code>DocumentInputStream</code> like this:</p>
<source>
// load file system
@ -176,19 +176,19 @@ catch (IOException e)
// no such document, or the Entry represented by documentName is not a
// DocumentEntry
}</source>
</s4>
<s4 title="Reading a Document From an Arbitrary Directory">
</section>
<section title="Reading a Document From an Arbitrary Directory">
<p>A more generic technique for reading a document is to obtain an <code>org.apache.poi.poifs.filesystem.DirectoryEntry</code> instance for the directory containing the desired document (recall that you can use <code>getRoot()</code> to obtain the root directory from its file system). From that DirectoryEntry, you can then obtain a <code>DocumentInputStream</code> like this:</p>
<source>
DocumentEntry document = (DocumentEntry)directory.getEntry(documentName);
DocumentInputStream stream = new DocumentInputStream(document);
</source>
</s4>
</s3>
</s2>
<s2 title="Event-Driven Reading">
</section>
</section>
</section>
<section title="Event-Driven Reading">
<p>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.</p>
<s3 title="Preparation">
<section title="Preparation">
<p>The preparation phase involves creating an instance of <code>org.apache.poi.poifs.eventfilesystem.POIFSReader</code> and to then register one or more <code>org.apache.poi.poifs.eventfilesystem.POIFSReaderListener</code> instances with the <code>POIFSReader</code>.</p>
<source>
POIFSReader reader = new POIFSReader();
@ -202,8 +202,8 @@ reader.registerListener(myOtherPickyListener, new POIFSDocumentPath(),
"fubar");
reader.registerListener(myOtherPickyListener, new POIFSDocumentPath(
new String[] { "usr", "bin" ), "fubar");</source>
</s3>
<s3 title="POIFSReaderListener">
</section>
<section title="POIFSReaderListener">
<p><code>org.apache.poi.poifs.eventfilesystem.POIFSReaderListener</code> is an interface used to register for documents. When a matching document is read by the <code>org.apache.poi.poifs.eventfilesystem.POIFSReader</code>, the <code>POIFSReaderListener</code> instance receives an <code>org.apache.poi.poifs.eventfilesystem.POIFSReaderEvent</code> instance, which contains an open <code>DocumentInputStream</code> and information about the document.</p>
<p>A <code>POIFSReaderListener</code> 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 <code>POIFSReaderListener</code>.</p>
<p>Thus, it is possible to register a single <code>POIFSReaderListener</code> for multiple documents - one, some, or all documents. It is guaranteed that a single <code>POIFSReaderListener</code> 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 <code>POIFSReader</code> are free to change the algorithm for walking the file system's directory structure.</p>
@ -228,8 +228,8 @@ reader.registerListener(myOtherPickyListener, new POIFSDocumentPath(
<td>registers <b>listener</b> for a document with the specified <b>name</b> in the directory described by <b>path</b></td>
</tr>
</table>
</s3>
<s3 title="POIFSDocumentPath">
</section>
<section title="POIFSDocumentPath">
<p>The <code>org.apache.poi.poifs.filesystem.POIFSDocumentPath</code> 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:</p>
<table>
<tr>
@ -257,26 +257,26 @@ reader.registerListener(myOtherPickyListener, new POIFSDocumentPath(
<td>in Unix terminology, "/foo/fu/bar".</td>
</tr>
</table>
</s3>
<s3 title="Processing POIFSReaderEvent Events">
</section>
<section title="Processing POIFSReaderEvent Events">
<p>Processing <code>org.apache.poi.poifs.eventfilesystem.POIFSReaderEvent</code> events is relatively easy. After all of the <code>POIFSReaderListener</code> instances have been registered with <code>POIFSReader</code>, the <code>POIFSReader.read(InputStream stream)</code> method is called.</p>
<p>Assuming that there are no problems with the data, as the <code>POIFSReader</code> processes the documents in the specified <code>InputStream</code>'s data, it calls registered <code>POIFSReaderListener</code> instances' <code>processPOIFSReaderEvent</code> method with a <code>POIFSReaderEvent</code> instance.</p>
<p>The <code>POIFSReaderEvent</code> instance contains information to identify the document (a <code>POIFSDocumentPath</code> object to identify the directory that the document is in, and the document name), and an open <code>DocumentInputStream</code> instance from which to read the document.</p>
</s3>
</s2>
</s1>
<s1 title="Writing a File System">
</section>
</section>
</section>
<section title="Writing a File System">
<p>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:</p>
<source>
POIFSFileSystem fs = new POIFSFileSystem();</source>
<s2 title="The Naming of Names">
<section title="The Naming of Names">
<p>There are two restrictions on the names of files in a file system that must be considered when creating files:</p>
<ol>
<li>The name of the file must not exceed 31 characters. If it does, the POIFS API will silently truncate the name to fit.</li>
<li>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 <b>after</b> the name has been truncated, if the original name was too long to begin with.</li>
</ol>
</s2>
<s2 title="Creating a Document">
</section>
<section title="Creating a Document">
<p>A document can be created by acquiring a <code>DirectoryEntry</code> and calling one of the two <code>createDocument</code> methods:</p>
<table>
<tr>
@ -316,13 +316,13 @@ POIFSFileSystem fs = new POIFSFileSystem();</source>
<p>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.</p>
<p>Writing is initiated when the <code>POIFSFileSystem</code> instance's <code>writeFilesystem()</code> method is called with an <code>OutputStream</code> to write to.</p>
<p>The event-driven model is quite similar to the event-driven model for reading, in that the file system calls your <code>org.apache.poi.poifs.filesystem.POIFSWriterListener</code> when it's time to write your document, just as the <code>POIFSReader</code> calls your <code>POIFSReaderListener</code> when it's time to read your document. Internally, when <code>writeFilesystem()</code> is called, the final POIFS data structures are created and are written to the specified <code>OutputStream</code>. When the file system needs to write a document out that was created with the event-driven model, it calls the <code>POIFSWriterListener</code> back, calling its <code>processPOIFSWriterEvent()</code> method, passing an <code>org.apache.poi.poifs.filesystem.POIFSWriterEvent</code> instance. This object contains the <code>POIFSDocumentPath</code> and name of the document, its size, and an open <code>org.apache.poi.poifs.filesystem.DocumentOutputStream</code> to which to write. A <code>DocumentOutputStream</code> is a wrapper over the <code>OutputStream</code> that was provided to the <code>POIFSFileSystem</code> to write to, and has the responsibility of making sure that the document your application writes fits within the size you specified for it.</p>
</s2>
<s2 title="Creating a Directory">
</section>
<section title="Creating a Directory">
<p>Creating a directory is similar to creating a document, except that there's only one way to do so:</p>
<source>
DirectoryEntry createdDir = existingDir.createDirectory(name);</source>
</s2>
<s2 title="Using POIFSFileSystem Directly To Create a Document Or Directory">
</section>
<section title="Using POIFSFileSystem Directly To Create a Document Or Directory">
<p>As with reading documents, it is possible to create a new document or directory in the root directory by using convenience methods of POIFSFileSystem.</p>
<table>
<tr>
@ -342,28 +342,28 @@ DirectoryEntry createdDir = existingDir.createDirectory(name);</source>
<td>createDirectory(String name)</td>
</tr>
</table>
</s2>
</s1>
<s1 title="Modifying a File System">
</section>
</section>
<section title="Modifying a File System">
<p>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.</p>
<s2 title="Removing a Document">
<section title="Removing a Document">
<p>Removing a document is simple: you get the <code>Entry</code> corresponding to the document and call its <code>delete()</code> method. This is a boolean method, but should always return <code>true</code>, indicating that the operation succeeded.</p>
</s2>
<s2 title="Removing a Directory">
</section>
<section title="Removing a Directory">
<p>Removing a directory is also simple: you get the <code>Entry</code> corresponding to the directory and call its <code>delete()</code> method. This is a boolean method, but, unlike deleting a document, may not always return <code>true</code>, indicating that the operation succeeded. Here are the reasons why the operation may fail:</p>
<ul>
<li>The directory still has files in it (to check, call <code>isEmpty()</code> on its DirectoryEntry; is the return value <code>false</code>?)</li>
<li>The directory is the root directory. You cannot remove the root directory.</li>
</ul>
</s2>
<s2 title="Renaming a File">
</section>
<section title="Renaming a File">
<p>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 <code>Entry</code> instance and calling its <code>renameTo</code> method, passing in the new name.</p>
<p>Like <code>delete</code>, <code>renameTo</code> returns <code>true</code> if the operation succeeded, otherwise <code>false</code>. Reasons for failure include these:</p>
<ul>
<li>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 <b>will</b> 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.</li>
<li>You tried to rename the root directory.</li>
</ul>
</s2>
</s1>
</section>
</section>
</body>
</document>

4
src/documentation/xdocs/poifs/index.xml
View File

@ -10,7 +10,7 @@
</authors>
</header>
<body>
<s1 title="Overview">
<section title="Overview">
<p>POIFS is a pure Java implementation of the OLE 2 Compound
Document format.</p>
<p>By definition, all APIs developed by the POI project are
@ -37,6 +37,6 @@
<p>TODO: copy POIFS docs and port to XML (in progress). For now
please reference <link href="http://poi.sourceforge.net">old
site</link>.</p>
</s1>
</section>
</body>
</document>

46
src/documentation/xdocs/poifs/usecases.xml
View File

@ -1,5 +1,5 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "../dtd/document-v10.dtd">
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "../dtd/document-v11.dtd">
<document>
<header>
<authors>
@ -7,8 +7,8 @@
</authors>
</header>
<body>
<s1 title="POIFS Use Cases">
<s2 title="Use Case 1: Read existing file system">
<section title="POIFS Use Cases">
<section title="Use Case 1: Read existing file system">
<table>
<tr>
<td><B>Primary Actor:</B></td>
@ -86,8 +86,8 @@
</td>
</tr>
</table>
</s2>
<s2 title="Use Case 2: Write file system">
</section>
<section title="Use Case 2: Write file system">
<table>
<tr>
<td><B>Primary Actor:</B></td>
@ -191,8 +191,8 @@
</td>
</tr>
</table>
</s2>
<s2 title="Use Case 3: Create new file system">
</section>
<section title="Use Case 3: Create new file system">
<table>
<tr>
<td><B>Primary Actor:</B></td>
@ -237,8 +237,8 @@
<td>None</td>
</tr>
</table>
</s2>
<s2 title="Use Case 4: Replace file in file system">
</section>
<section title="Use Case 4: Replace file in file system">
<table>
<tr>
<td><B>Primary Actor:</B></td>
@ -306,8 +306,8 @@
</td>
</tr>
</table>
</s2>
<s2 title="Use Case 5: Delete file from file system">
</section>
<section title="Use Case 5: Delete file from file system">
<table>
<tr>
<td><B>Primary Actor:</B></td>
@ -374,8 +374,8 @@
</td>
</tr>
</table>
</s2>
<s2 title="Use Case 6: Write new file to file system">
</section>
<section title="Use Case 6: Write new file to file system">
<table>
<tr>
<td><B>Primary Actor:</B></td>
@ -440,8 +440,8 @@
</td>
</tr>
</table>
</s2>
<s2 title="Use Case 7: Read existing file from file system">
</section>
<section title="Use Case 7: Read existing file from file system">
<table>
<tr>
<td><B>Primary Actor:</B></td>
@ -502,8 +502,8 @@
specified name exists.</td>
</tr>
</table>
</s2>
<s2 title="Use Case 8: Read file system directory">
</section>
<section title="Use Case 8: Read file system directory">
<table>
<tr>
<td><B>Primary Actor:</B></td>
@ -556,8 +556,8 @@
<td>None</td>
</tr>
</table>
</s2>
<s2 title="Use Case 9: Read file">
</section>
<section title="Use Case 9: Read file">
<table>
<tr>
<td><B>Primary Actor:</B></td>
@ -617,8 +617,8 @@
extending past the known size of the file.</td>
</tr>
</table>
</s2>
<s2 title="Use Case 10: Rename existing file in the file system">
</section>
<section title="Use Case 10: Rename existing file in the file system">
<table>
<tr>
<td><B>Primary Actor:</B></td>
@ -683,7 +683,7 @@
</td>
</tr>
</table>
</s2>
</s1>
</section>
</section>
</body>
</document>

6
src/documentation/xdocs/resolutions/index.xml
View File

@ -1,5 +1,5 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "../dtd/document-v10.dtd">
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "../dtd/document-v11.dtd">
<document>
<header>
@ -11,7 +11,7 @@
</header>
<body>
<s1 title="About Resolutions">
<section title="About Resolutions">
<p>
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
</p>
</s1>
</section>
</body>
</document>

22
src/documentation/xdocs/resolutions/res001.xml
View File

@ -1,5 +1,5 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "../dtd/document-v10.dtd">
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "../dtd/document-v11.dtd">
<document>
<header>
@ -11,8 +11,8 @@
</header>
<body>
<s1 title="Resolution 001 - Minimal Coding Standards">
<s2 title="Majority Position">
<section title="Resolution 001 - Minimal Coding Standards">
<section title="Majority Position">
<p>
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.
</li>
</ol>
</s2>
<s2 title="Amendments (informal by extension and not by vote)">
</section>
<section title="Amendments (informal by extension and not by vote)">
<p>
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.
</p>
</s2>
<s2 title="Dissent">
</section>
<section title="Dissent">
<p>
The motion was passed unanimously with no negative or
positive votes.
</p>
</s2>
<s2 title="Comments">
</section>
<section title="Comments">
<p>
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 ;-).
</p>
</s2>
</s1>
</section>
</section>
</body>
</document>

6
src/documentation/xdocs/utils/index.xml
View File

@ -1,5 +1,5 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "../dtd/document-v10.dtd">
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "./dtd/document-v11.dtd">
<document>
<header>
@ -11,7 +11,7 @@
</header>
<body>
<s1 title="Overview">
<section title="Overview">
<p>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!"
</p>
</s1>
</section>
</body>
</document>

16
src/documentation/xdocs/who.xml
View File

@ -12,7 +12,7 @@
<body>
<s1 title="Who we are">
<section title="Who we are">
<p>
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.
</p>
<s2 title="Advisors">
<section title="Advisors">
<ul>
<li><link href="http://jakarta.apache.org/avalon/authors/stefano.html">Stefano Mazzocchi</link> (stefano at apache dot org)
</li>
</ul>
</s2>
</section>
<s2 title="Committers">
<section title="Committers">
<ul>
<li><link href="http://trilug.org/~acoliver">Andrew C. Oliver</link> (acoliver at apache dot org)</li>
<li><link href="http://www.marcj.com">Marc Johnson</link> (mjohnson at apache dot org)</li>
@ -46,13 +46,13 @@
<li><link href="http://www.rainer-klute.de/">Rainer Klute</link> (klute at apache dot org)</li>
<li>Nicola Ken Barozzi (barozzi at nicolaken dot com)</li>
</ul>
</s2>
<s2 title="Developers">
</section>
<section title="Developers">
<ul>
<li>Ryan Ackley (sackley at cfl dot rr dot com)</li>
</ul>
</s2>
</s1>
</section>
</section>
</body>
</document>