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

Replace release branch documentation by the old state of previous stable release via svn copy instead of externals

Browse Source 
git-svn-id: https://svn.apache.org/repos/asf/poi/branches/REL_3_10_BRANCH@1617714 13f79535-47bb-0310-9956-ffa450edef68
This commit is contained in:
Uwe Schindler 2014-08-13 12:36:10 +00:00
parent 5e40f3cfc3
commit 780932ef38
284 changed files with 35675 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

10
src/documentation/README.txt Normal file
View File

@ -0,0 +1,10 @@
This is the base documentation directory. It usually contains two files:
skinconf.xml # This file customizes Forrest for your project. In it, you
# tell forrest the project name, logo, copyright info, etc
sitemap.xmap # Optional. This sitemap overrides the default one bundled
# with Forrest. Typically, one would copy a sitemap from
# xml-forrest/src/resources/conf/sitemap.xmap, and customize
# it.

43
src/documentation/RELEASE-NOTES.txt Normal file
View File

@ -0,0 +1,43 @@
The Apache POI project is pleased to announce the release of POI @VERSION@.
Featured are a handful of new areas of functionality, and numerous bug fixes.
See the downloads page for binary and source distributions: http://poi.apache.org/download.html
Release Notes
Changes
------------
The most notable changes in this release are:
@List changes here@
A full list of changes is available in the change log: http://poi.apache.org/changes.html.
People interested should also follow the dev mailing list to track further progress.
Release Contents
----------------
This release comes in two forms:
- pre-built binaries containing compiled versions of all Apache POI components and documentation
(poi-bin-@VERSION@.zip or poi-bin-@VERSION@.tar.gz)
- source archive you can build POI from (poi-src-@VERSION@.zip or poi-src-@VERSION@.tar.gz)
Unpack the archive and use the following command to build all POI components with Apache Ant 1.6+ and JDK 1.5 or higher:
ant jar
Pre-built versions of all POI components are also available in the central Maven repository
under Group ID "org.apache.poi" and Version "@VERSION@"
All release artifacts are accompanied by MD5 checksums and a PGP signatures
that you can use to verify the authenticity of your download.
The public key used for the PGP signature can be found at
http://svn.apache.org/repos/asf/poi/tags/@RELEASE_TAG@/KEYS
About Apache POI
-----------------------
Apache POI is well-known in the Java field as a library for reading and
writing Microsoft Office file formats, such as Excel, PowerPoint, Visio and
Word. Since POI 3.5, the new OOXML (Office Open XML) formats introduced in Office 2007 have been supported.
See http://poi.apache.org/ for more details

74
src/documentation/Release-Checklist.txt Normal file
View File

@ -0,0 +1,74 @@
# Licensed to the Apache Software Foundation (ASF) under one
# or more contributor license agreements. See the NOTICE file
# distributed with this work for additional information
# regarding copyright ownership. The ASF licenses this file
# to you under the Apache License, Version 2.0 (the
# "License"); you may not use this file except in compliance
# with the License. You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing,
# software distributed under the License is distributed on an
# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
# KIND, either express or implied. See the License for the
# specific language governing permissions and limitations
# under the License.
================================
POI Release Checklist
================================
Note - this file should be read in conjunction with the
POI Release Guide. They should probably be merged in future...
- ensure the changelog is up to date
- tag SVN
- build distributions as if it was the final release
- update any filename dates from today's date, to the date that the
vote will end (typically 7 days time)
- copy the -redirect pom to a subdirectory of redirect/, and remove
-redirect from its name
- sign and checksum distributions as per
http://www.apache.org/dev/mirror-step-by-step.html
- upload the files to the POI dev dist area under /<version>-RC-<x>/
eg https://dist.apache.org/repos/dist/dev/poi/3.8-RC2/ for
3.8 Release Candidate 2
- add a README.txt to the directory that states the files are a
release candidate pending a vote, despite their name being -FINAL
- include the URL of this in the release vote (goes to dev, not user)
(eg https://dist.apache.org/repos/dist/dev/poi/3.8-RC2/)
- wait for release vote to pass
- send notification of vote passing to private@
- move the regular distributions from the dev area of the dist svn to the
release area of svn
- remove the old distribition from the release area of svn
- ensure that the artificats show up on www.apache.org/dist/poi/ (they
should appear within a minute)
- copy the maven distribution from a checkout of the dev area of the dist
svn, to the distribution directories on
people.apache.org/repo/m1-ibiblio-rsync-repository/org.apache.poi/
- copy the maven redirection pom from a checkout of the dev area of the
dist svn, to people.apache.org/repo/m1-ibiblio-rsync-repository/poi/poms/
- wait for the distributions to appear on your favourite mirror
- generate announcements
- generate www pages and upload
- bump release ID in build.xml
- send announcements to user and dev lists
- send announcements to announcement@apache.org, announcements@jakarta.apache.org
- news to newsgroups: comp.lang.java.softwaretools
- post stories on
*) jakarta news page
*) theserverside.com
*) freshmeat.net
*) www.javaworld.com
*) www.javalobby.com
*) www.jguru.com
*) www.slashdot.org
(and follow them up)

86
src/documentation/content/xdocs/3rdparty.xml Normal file
View File

@ -0,0 +1,86 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
====================================================================
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
====================================================================
-->
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.3//EN" "./dtd/document-v13.dtd">
<document>
<header>
<title>Third Party Contributions</title>
<authors>
<person name="Nicola Ken Barozzi" email="barozzi@nicolaken.com"/>
</authors>
</header>
<body>
<section><title>How to Contribute</title>
<p>
See <link href="contrib.xml">How to contribute to Poi</link>.
</p>
</section>
<section><title>Contributed Components</title>
<p>
These are not necessarily deemed to be high enough quality to be included in the
core distribution, but they have been tested under <link href="contrib.xml">
several key environments</link>, they are provided under the same license
as Poi, and they are included in the POI distribution under the
<code>contrib/</code> directory.
</p>
<p>
<strong>None as yet!</strong> - although you can expect that some of the links
listed below will eventually migrate to the "contributed components" level, and
then maybe even into the main distribution.
</p>
</section>
<section><title>Patch Queue</title>
<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>
</section>
<section><title>Other Extensions</title>
<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.
</p>
<p>To have a link added to this table, see <link href="contrib.xml">How to contribute
to POI</link>.</p>
<table>
<tr>
<th>Name and Link</th>
<th>Type</th>
<th>Description</th>
<th>Status</th>
<th>Licensing</th>
<th>Contact</th>
</tr>
</table>
</section>
</body>
</document>

72
src/documentation/content/xdocs/book.xml Normal file
View File

@ -0,0 +1,72 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
====================================================================
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
====================================================================
-->
<!DOCTYPE book PUBLIC "-//APACHE//DTD Cocoon Documentation Book V1.0//EN" "./dtd/book-cocoon-v10.dtd">
<book software="POI"
title="POI Project Documentation"
copyright="@year@ POI Project"
xmlns:xlink="http://www.w3.org/1999/xlink">
<menu label="Overview">
<menu-item label="Home" href="index.html"/>
<menu-item label="Download" href="download.html"/>
<menu-item label="Components" href="overview.html"/>
<menu-item label="Text Extraction" href="text-extraction.html"/>
<menu-item label="Encryption support" href="encryption.html"/>
<menu-item label="Case Studies" href="casestudies.html"/>
<menu-item label="Legal" href="legal.html"/>
</menu>
<menu label="Help">
<menu-item label="Javadocs" href="ext:javadoc"/>
<menu-item label="FAQ" href="faq.html"/>
<menu-item label="Mailing Lists" href="mailinglists.html"/>
<menu-item label="Bug Database" href="http://issues.apache.org/bugzilla/buglist.cgi?product=POI"/>
<menu-item label="Changes Log" href="changes.html"/>
</menu>
<menu label="Getting Involved">
<menu-item label="Subversion Repository" href="subversion.html"/>
<menu-item label="How To Build" href="howtobuild.html"/>
<menu-item label="Contribution Guidelines" href="guidelines.html"/>
<menu-item label="Who We Are" href="who.html"/>
</menu>
<menu label="Component APIs">
<menu-item label="Excel (SS=HSSF+XSSF)" href="spreadsheet/index.html"/>
<menu-item label="Word (HWPF+XWPF)" href="hwpf/index.html"/>
<menu-item label="PowerPoint (HSLF+XSLF)" href="slideshow/index.html"/>
<menu-item label="OpenXML4J (OOXML)" href="oxml4j/index.html"/>
<menu-item label="OLE2 Filesystem (POIFS)" href="poifs/index.html"/>
<menu-item label="OLE2 Document Props (HPSF)" href="hpsf/index.html"/>
<menu-item label="Outlook (HSMF)" href="hsmf/index.html"/>
<menu-item label="Visio (HDGF)" href="hdgf/index.html"/>
<menu-item label="TNEF (HMEF)" href="hmef/index.html"/>
<menu-item label="Publisher (HPBF)" href="hpbf/index.html"/>
</menu>
<menu label="Apache Wide">
<menu-item label="Apache Software Foundation" href="http://www.apache.org/" />
<menu-item label="License" href="http://www.apache.org/licenses/" />
<menu-item label="Sponsorship" href="http://www.apache.org/foundation/sponsorship.html" />
<menu-item label="Thanks" href="http://www.apache.org/foundation/thanks.html" />
<menu-item label="Security" href="http://www.apache.org/security/" />
</menu>
</book>

321
src/documentation/content/xdocs/casestudies.xml Normal file
View File

@ -0,0 +1,321 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
====================================================================
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
====================================================================
-->
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.3//EN" "./dtd/document-v13.dtd">
<document>
<header>
<title>Apache POI - Case Studies</title>
<authors>
<person id="AO" name="Andrew C. Oliver" email="acoliver@apache.org"/>
<person id="CR" name="Cameron Riley" email="crileyNO@SPAMekmail.com"/>
<person id="DF" name="David Fisher" email="dfisher@jmlafferty.com"/>
<person id="DS" name="Dominik Stadler" email="centic@apache.org"/>
</authors>
</header>
<body>
<section>
<title>Introduction</title>
<p>
A number of people are using POI for a variety of purposes. As with
any new API or technology, the first question people generally ask
is not "how can I" but rather "Who else is doing what I'm about to
do?" This is understandable with the abysmal success rate in the
software business. These case statements are meant to help create
confidence and understanding.
</p>
</section>
<section>
<title>Submitting a Case Study</title>
<p>
We are actively seeking case studies for this page (after all it
just started). To submit a case study, either
<link href="guidelines.html">
submit a patch for this page</link> or email it to the
<link href="mailinglists.html">mailing list
</link> (with [PATCH] prefixed subject, please).
</p>
</section>
<section>
<title>Case Studies</title>
<section><title>REWOO Scope</title>
<p>
<link href="http://www.rewoo.de/">REWOO Scope</link> is a modern and easy to use web-based enterprise content management system. It supports knowledge workers and managers in making the right decisions based upon all relevant information.
</p>
<p>
The system uses Apache POI to extract information stored within excel files and use it transparently within REWOO Scope. Thus, POI allows our customers to work in their standard office environment while also having all important information in the REWO Scope system.
</p>
</section>
<section><title>QuestionPro</title>
<p>
<link href="http://www.questionpro.com">QuestionPro</link> is an online service allowing businesses and individuals to create, deploy and do in-depth analysis of Online Surveys. The technology is build on open-source frameworks like Struts, Velocity, POI, Lucene ... the List goes on. The application deployment is on a Linux Application Cluster farm with a Mysql database.
</p>
<p>
There are quite a few competitors delivering similar solutions using Microsoft Technologies like asp and .net. One of the distinct advantages our competitors had over us was the ability to generate Excel Spreadsheets, Access Databases (MDB) etc. on the fly using the Component Object Model (COM) - since their servers were running IIS and they had access to the COM registry and such.
</p>
<p>
QuestionPro's initial solution was to generate CSV files. This was easy however it was a cumbersome process for our clients to download the CSV files and then import them into Excel. Moreover, formatting information could not be preserved or captured using the CSV format. This is where POI came to our rescue. With a POI based solution, we could generate a full report with multiple sheets and all the analytical reports. To keep the solution scalable, we had a dedicated cluster for generating out the reports.
</p>
<p>
The Apache-POI project has helped QuestionPro compete with the other players in the marketplace with proprietary technology. It leveled the playing field with respect to reporting and data analysis solutions. It helped in opening doors into closed solutions like Microsoft's CDF. Today about 100 excel reports are generated daily, each with about 10-30 sheets in them.
</p>
<p>
Vivek Bhaskaran
</p>
<p>
<link href="http://www.questionpro.com">QuestionPro, Inc</link>
</p>
<p>
POI In Action - <link href="http://www.questionpro.com/marketing/SurveyReport-289.xls">http://www.questionpro.com/marketing/SurveyReport-289.xls</link>
</p>
</section>
<section><title>Sunshine Systems</title>
<p>
<link href="http://www.sunshinesys.com/">Sunshine Systems</link> deveveloped a
POI based reporting solution for a price optimization software package which
is used by major retail chains.
</p>
<p>The solution allowed the retailer's merchandise planners and managers to request a
markdown decision support reports and price change reports using a standard browser
The users could specify report type, report options, as well as company,
division,
and department filter criteria. Report generation took place in the
multi-threaded
application server and was capable of supporting many simultaneous report requests.
</p>
<p>The reporting application collected business information from the price
optimization
application's Oracle database. The data was aggregated and summarized
based upon the
specific report type and filter criteria requested by the user. The
final report was
rendered as a Microsoft Excel spreadsheet using the POI HSSF API and
was stored on
the report database server for that specific user as a BLOB. Reports
could be
seamlessly and easily viewed using the same browser.
</p>
<p>The retailers liked the solution because they had instantaneous access
to critical
business data through an extremely easy to use browser interface. They
did not need
to train the broader user community on all the complexities of the optimization
application. Furthermore, the reports were generated in an Excel spreadsheet
format,
which everyone was familiar with and which also allowed further data
analysis using
standard Excel features.
</p>
<p>Rob Stevenson (rstevenson at sunshinesys dot com)
</p>
</section>
<section>
<title>Bank of Lithuania</title>
<p>
The
<link href="http://www.lbank.lt/">Bank of Lithuania</link>
reports financial statistical data to Excel format using the
<link href="http://poi.apache.org/">Apache POI</link>
project's
<link href="spreadsheet/">
HSSF</link> API. The system is based on Oracle JServer and
utilizes a Java stored procedure that outputs to XLS format
using the HSSF API. - Arian Lashkov (alaskov at lbank.lt)
</p>
</section>
<!-- <section>-->
<!-- <title>Bit Tracker by Tracker Inc., and ThinkVirtual</title>-->
<!-- <p>-->
<!-- Bit Tracker (http://www.bittracker.com/) is the world's first and only web-based drill bit tracking system to manage your company's critical bit information and use that data to its full potential. It manages all bit related data, including their usage, locations, how they were used, and results such as rate of penetration and dull grade after use. This data needs to be available in Excel format for backwards compatibility and other uses in the industry. After using CSV and HTML formats, we needed something better for creating the spreadsheets and POI is the answer. It works great and was easy to implement. Kudos to the POI team.-->
<!-- </p>-->
<!-- <p>-->
<!-- Travis Reeder (travis at thinkvirtual dot com)-->
<!-- </p>-->
<!-- </section>-->
<section>
<title>Edwards And Kelcey Technology</title>
<p>
Edwards and Kelcey Technology (http://www.ekcorp.com/) developed a
Facility
Managament and Maintenance System for the Telecommunications industry
based
on Turbine and Velocity. Originally the invoicing was done with a simple
CSV
sheet which was then marked up by accounts and customized for each client.
As growth has been consistent with the application, the requirement for
invoices that need not be touched by hand increased. POI provided the
solution to this issue, integrating easily and transparently into the
system. POI HSSF was used to create the invoices directly from the server
in
Excel 97 format and now services over 150 unique invoices per month.
</p>
<p>
Cameron Riley (crileyNO@ SPAMekmail.com)
</p>
</section>
<section>
<title>ClickFind</title>
<p>
<link href="http://www.clickfind.com/">ClickFind Inc.</link> used the POI
projects HSSF API to provide their medical
research clients with an Excel export from their electronic data
collection web service Data Collector 3.0. The POI team's assistance
allowed ClickFind to give their clients a data format that requires less
technical expertise than the XML format used by the Data Collector
application. This was important to ClickFind as many of their current
and potential clients are already using Excel in their day-to-day
operations and in established procedures for handling their generated
clinical data. - Jared Walker (jared.walker at clickfind.com)
</p>
</section>
<section>
<title>IKAN Software NV</title>
<p>In addition to Change Management and Database Modelling, IKAN Software NV
(http://www.ikan.be/) develops and supports its own ETL
(Extract/Transform/Load) tools.</p>
<p>IKAN's latest product is this domain is called ETL4ALL
(http://www.ikan.be/etl4all/). ETL4ALL is an open source tool
allowing data transfer from and to virtually any data source. Users can
combine and examine data stored in relational databases, XML databases, PDF
files, EDI, CSV files, etc.
</p>
<p>It is obvious that Microsoft Excel files are also supported.
POI has been used to successfully implement this support in ETL4ALL.</p>
</section>
<section>
<title>JM Lafferty Associates, Inc.</title>
<p>
On its <link href="http://www.forecastworks.com/public/">ForecastWorks</link> website
<link href="http://www.jmlafferty.com/">JM Lafferty Associates, Inc.</link> produces dynamic on demand
financial analyses of companies and institutional funds. The pages produced are selected and exported
in several file formats including PPT and XLS.
</p>
<ul>
<li>The PPT files produced are of high quality which is on a par with similar PDF files.</li>
<li>The XLS files produced contain a complex forecasting model built from a template with a VBA Macro.</li>
</ul>
<p>
David Fisher (dfisher@jmlafferty.com)
</p>
</section>
<section>
<title>iDATA Development Ltd (IDD)</title>
<p>
<link href="http://www.iexlsoftware.com/">IDD</link> have developed the iEXL product to
generate Excel spreadsheets directly on the Iseries/AS400 IBM I on Power platform.
</p>
<p>
Professional spreadsheets created via a menu system. Some basic programming is required for more complex options.
When programming is required it can be carried out using RPG, SQL, QUERY, JAVA, COBOL etc.
In other words your existing staffs knowledge
</p>
<p>
Design spreadsheets with:
</p>
<ul>
<li>Fonts down to cell level</li>
<li>Colours (Background and text) down to cell level</li>
<li>Shading down to cell level</li>
<li>Cell patterns down to cell level</li>
<li>Cell initialization</li>
<li>Freeze Panes</li>
<li>Passwords</li>
<li>Images/Pictures both static and dynamic</li>
<li>Headings</li>
<li>Page breaks</li>
<li>Sheet breaks</li>
<li>Text insertion and much more</li>
<li>Functions/Formula</li>
<li>Merge cells</li>
<li>Row Height</li>
<li>Cell text alignment</li>
<li>Text Rotation </li>
<li>50 Database files per workbook.</li>
<li>E-mail the spreadsheet</li>
</ul>
<p>
The product name is 'iEXL' and has been live on both European and North American systems for over four years.
It is being used in preference to more established commercial products which our clients have already purchased.
This is due to cost and ease of use.
</p>
<p>
All spreadsheets can be archived if required so that historical spreadsheets can be retrieved.
</p>
<p>
The system has benefits for all departments within an organisation.
Examples of this are accounts department for things such as aged trial balance,
distribution department for ASN’s, warehousing for stock figures, IS for security reporting etc.
</p>
<p>
Clients have at this point (June 2012) created over 300 spreadsheets which in turn have generated over
500,000 E-mails. iEXL has a menu driven email system.
</p>
<p>
Due to the Apache-POI project IDD have been able to create the IEXL product.
This is a well priced product which allows companies of all sizes access to a product that opens up their reporting capabilities
</p>
<p>
Within the <link href="http://www.iexlsoftware.com/">iEXLSOFTWARE.COM</link> website you will find a full user manual,
installation instructions, a call log (Ticket) system and a downloadable 45 day trial version.
</p>
<p>
<em>Author: Mark.D.Golden</em>
</p>
</section>
<section>
<title>Ugly Duckling</title>
<p>
<link href="http://uglyduckling.nl/">Ugly Duckling</link> focus on Software, Management and Finance.
We have recently been using Apache POI to create tools for the mortgage group of
<link href="https://www.abnamro.nl/en/personal/index.html">ABN AMRO</link> in the Netherlands.
During this project we created a number of what we call 'Robots' using the HSSF API.
</p>
<p>
These <link href="http://uglyduckling.nl/work/robots/">robots</link> run as services on the network and
help automate the processing of large amounts of data. Our Robots can be used to spot problems that
a human might not, and also to automate repetitive tasks.
</p>
<p>
We found Apache POI to be extremely useful. We took the base API, wrapped it in a builder pattern and
thus created a DSL with a fluid interface. Throughout the project we enjoyed very much working with
Apache POI and found it to be very reliable.
</p>
</section>
</section>
</body>
<footer>
<legal>
Copyright (c) @year@ The Apache Software Foundation All rights reserved.
<br />
Apache POI, POI, Apache, the Apache feather logo, and the Apache
POI project logo are trademarks of The Apache Software Foundation.
</legal>
</footer>
</document>

189
src/documentation/content/xdocs/download.xml Normal file
View File

@ -0,0 +1,189 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
====================================================================
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
====================================================================
-->
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.3//EN" "./dtd/document-v13.dtd">
<document>
<header>
<title>Apache POI - Download Release Artifacts</title>
</header>
<body>
<section><title>Available Downloads</title>
<p>
This page provides instructions on how to download and verify the
Apache POI release artifacts. Apache POI is a pure Java library for
manipulating Microsoft Documents, for more information please see
<link href="index.html">the project homepage</link>.
</p>
<ul>
<li><link href="download.html#POI-3.10-FINAL">The latest stable release is Apache POI 3.10-FINAL</link></li>
<li><link href="download.html#archive">Archives of all prior releases</link></li>
</ul>
<p>
Apache POI releases are available under the <link href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0.</link>
See the NOTICE file contained in each release artifact for applicable copyright attribution notices.
</p>
<p>
To insure that you have downloaded the true release you should <link href="download.html#verify">verify the integrity</link>
of the files using the signatures and checksums available from this page.
</p>
</section>
<section id="POI-3.10-FINAL"><title>23 January 2013 - POI 3.10-FINAL available</title>
<p>The Apache POI team is pleased to announce the release of 3.10-FINAL.
This includes a large number of bug fixes and enhancements.
</p>
<p>A full list of changes is available in the <link href="changes.html">change log</link>.
People interested should also follow the <link href="mailinglists.html">dev list</link> to track progress.</p>
<p>
The POI source release as well as the pre-built binary deployment packages are listed below.
Pre-built versions of all <link href="index.html#components">POI components</link> are available in the central Maven repository
under Group ID "org.apache.poi" and Version "3.10-FINAL".
</p>
<section><title>Binary Distribution</title>
<ul>
<li><link href="http://www.apache.org/dyn/closer.cgi/poi/release/bin/poi-bin-3.10-FINAL-20140208.tar.gz">poi-bin-3.10-FINAL-20140208.tar.gz</link> (
16MB, <link href="http://www.apache.org/dist/poi/release/bin/poi-bin-3.10-FINAL-20140208.tar.gz.asc">signed</link>)
<br/>
MD5 checksum: <link href="http://www.apache.org/dist/poi/release/bin/poi-bin-3.10-FINAL-20140208.tar.gz.md5">
818d1e99a2efe539ba49f622b554950c</link>
<br/>
SHA1 checksum: <link href="http://www.apache.org/dist/poi/release/bin/poi-bin-3.10-FINAL-20140208.tar.gz.sha1">
38b61905d780e09604fb8053fd46ab1b8b18392f</link>
</li>
<li><link href="http://www.apache.org/dyn/closer.cgi/poi/release/bin/poi-bin-3.10-FINAL-20140208.zip">poi-bin-3.10-FINAL-20140208.zip</link> (
23MB, <link href="http://www.apache.org/dist/poi/release/bin/poi-bin-3.10-FINAL-20140208.zip.asc">signed</link>)
<br/>
MD5 checksum: <link href="http://www.apache.org/dist/poi/release/bin/poi-bin-3.10-FINAL-20140208.zip.md5">
e304be0a3169697d31e029f63458a963</link>
<br/>
SHA1 checksum: <link href="http://www.apache.org/dist/poi/release/bin/poi-bin-3.10-FINAL-20140208.zip.sha1">
704f103bca893e3d4df5c2cc95d275b0cd5d0b33</link>
</li>
</ul>
</section>
<section><title>Source Distribution</title>
<ul>
<li><link href="http://www.apache.org/dyn/closer.cgi/poi/release/src/poi-bin-3.10-FINAL-20140208.tar.gz">poi-src-3.10-FINAL-20140208.tar.gz</link> (
48MB, <link href="http://www.apache.org/dist/poi/release/src/poi-src-3.10-FINAL-20140208.tar.gz.asc">signed</link>)
<br/>
MD5 checksum: <link href="http://www.apache.org/dist/poi/release/src/poi-src-3.10-FINAL-20140208.tar.gz.md5">
438157bfee9fe74869abd898820c7dae</link>
<br/>
SHA1 checksum: <link href="http://www.apache.org/dist/poi/release/src/poi-src-3.10-FINAL-20140208.tar.gz.sha1">
d0d5f596a649d1a852916fbadec4bdd9bdf70b9e</link>
</li>
<li><link href="http://www.apache.org/dyn/closer.cgi/poi/release/src/poi-src-3.10-FINAL-20140208.zip">poi-src-3.10-FINAL-20140208.zip</link> (
58MB, <link href="http://www.apache.org/dist/poi/release/src/poi-src-3.10-FINAL-20140208.zip.asc">signed</link>)
<br/>
MD5 checksum: <link href="http://www.apache.org/dist/poi/release/src/poi-src-3.10-FINAL-20140208.zip.md5">
95536ea16e0e97a3f02f0294a1835b74</link>
<br/>
SHA1 checksum: <link href="http://www.apache.org/dist/poi/release/src/poi-src-3.10-FINAL-20140208.zip.sha1">
8cc6ad470852295a8af7f08848a8ad9c84f177d1</link>
</li>
</ul>
</section>
</section>
<section><title>Nightly Builds</title>
<p>The POI nightly builds are run on <link href="https://builds.apache.org/job/POI/">Jenkins</link> continuous integration server.
Note that these are no official builds and they are not endorsed or even supported by the POI team.
<br/>
<strong>These builds should not be used in production</strong>: they are only intended for use by developers
to help with resolving bugs and evaluating new features.
</p>
<ul>
<li><link href="https://builds.apache.org/job/POI/lastSuccessfulBuild/artifact/build/dist/">
Last Successful Jenkins build for POI-trunk</link></li>
</ul>
</section>
<section id="verify"><title>Verify</title>
<p>
It is essential that you verify the integrity of the downloaded files using the PGP or MD5 signatures.
Please read <link href="http://httpd.apache.org/dev/verification.html">Verifying Apache HTTP Server Releases</link>
for more information on why you should verify our releases. This page provides detailed instructions which you can use for POI artifacts.
</p>
<p>
The PGP signatures can be verified using PGP or GPG. First download the KEYS file as well as the .asc signature files
for the relevant release packages. Make sure you get these files from the main distribution directory,
rather than from a mirror. Then verify the signatures using
</p>
<source>
% pgpk -a KEYS
% pgpv poi-X.Y.Z.jar.asc
</source>
<p>or</p>
<source>
% pgp -ka KEYS
% pgp poi-X.Y.Z.jar.asc
</source>
<p>or</p>
<source>
% gpg --import KEYS
% gpg --verify poi-X.Y.Z.jar.asc
</source>
<p>Sample verification of poi-bin-3.5-FINAL-20090928.tar.gz</p>
<source>
% gpg --import KEYS
gpg: key 12DAE9BE: "Glen Stampoultzis &lt;glens at apache dot org&gt;" not changed
gpg: key 4CEED75F: "Nick Burch &lt;nick at gagravarr dot org&gt;" not changed
gpg: key 84B5A42E: "Rainer Klute &lt;rainer.klute at gmx dot de&gt;" not changed
gpg: key F5BB52CD: "Yegor Kozlov &lt;yegor.kozlov at gmail dot com&gt;" not changed
gpg: Total number processed: 4
gpg: unchanged: 4
% gpg --verify poi-bin-3.5-FINAL-20090928.tar.gz.asc
gpg: Signature made Mon Sep 28 10:28:25 2009 PDT using DSA key ID F5BB52CD
gpg: Good signature from "Yegor Kozlov &lt;yegor.kozlov at gmail dot com&gt;"
gpg: aka "Yegor Kozlov &lt;yegor at dinom dot ru&gt;"
gpg: aka "Yegor Kozlov &lt;yegor at apache dot org&gt;"
Primary key fingerprint: 7D77 0C77 6CE7 754E E6AF 23AA 6934 0A02 F5BB 52CD
% gpg --fingerprint F5BB52CD
pub 1024D/F5BB52CD 2007-06-18 [expires: 2012-06-16]
Key fingerprint = 7D77 0C77 6CE7 754E E6AF 23AA 6934 0A02 F5BB 52CD
uid Yegor Kozlov &lt;yegor.kozlov at gmail dot com&gt;
uid Yegor Kozlov &lt;yegor at dinom dot ru&gt;
uid Yegor Kozlov &lt;yegor at apache dot org&gt;
sub 4096g/7B45A98A 2007-06-18 [expires: 2012-06-16]
</source>
</section>
<section id="archive"><title>Release Archives</title>
<p>
Apache POI became a top level project in June 2007 and POI 3.0 aritfacts were re-released.
Prior to that date POI was a sub-project of <link href="http://jakarta.apache.org/">Apache Jakarta.</link>
</p>
<ul>
<li><link href="http://archive.apache.org/dist/poi/release/bin/">Binary Artifacts</link></li>
<li><link href="http://archive.apache.org/dist/poi/release/src/">Source Artifacts</link></li>
<li><link href="http://archive.apache.org/dist/poi/">Keys</link></li>
<li><link href="http://archive.apache.org/dist/jakarta/poi/release/">Artifacts from prior to 3.0</link></li>
</ul>
</section>
</body>
<footer>
<legal>
Copyright (c) @year@ The Apache Software Foundation. All rights reserved.
<br />
Apache POI, POI, Apache, the Apache feather logo, and the Apache
POI project logo are trademarks of The Apache Software Foundation.
</legal>
</footer>
</document>

34
src/documentation/content/xdocs/dtd/ISOdia.pen Normal file
View File

@ -0,0 +1,34 @@
<!-- (C) International Organization for Standardization 1986
Permission to copy in any form is granted for use with
conforming SGML systems and applications as defined in
ISO 8879, provided this notice is included in all copies.
-->
<!-- Character entity set. Typical invocation:
<!ENTITY % ISOdia PUBLIC
"ISO 8879:1986//ENTITIES Diacritical Marks//EN//XML">
%ISOdia;
-->
<!-- This version of the entity set can be used with any SGML document
which uses ISO 10646 as its document character set.
This includes XML documents and ISO HTML documents.
This entity set uses hexadecimal numeric character references.
Creator: Rick Jelliffe, Allette Systems
Version: 1997-07-07
-->
<!ENTITY acute "&#180;" ><!--=acute accent-->
<!ENTITY breve "&#x2D8;" ><!--=breve-->
<!ENTITY caron "&#x2C7;" ><!--=caron-->
<!ENTITY cedil "&#184;" ><!--=cedilla-->
<!ENTITY circ "^" ><!--=circumflex accent-->
<!ENTITY dblac "&#x2DD;" ><!--=double acute accent-->
<!ENTITY die "&#168;" ><!--=dieresis-->
<!ENTITY dot "&#x2D9;" ><!--=dot above-->
<!ENTITY grave "`" ><!--=grave accent-->
<!ENTITY macr "&#175;" ><!--=macron-->
<!ENTITY ogon "&#x2DB;" ><!--=ogonek-->
<!ENTITY ring "&#x2DA;" ><!--=ring-->
<!ENTITY tilde "&#x2DC;" ><!--=tilde-->
<!ENTITY uml "&#168;" ><!--=umlaut mark-->

79
src/documentation/content/xdocs/dtd/ISOlat1.pen Normal file
View File

@ -0,0 +1,79 @@
<!-- (C) International Organization for Standardization 1986
Permission to copy in any form is granted for use with
conforming SGML systems and applications as defined in
ISO 8879, provided this notice is included in all copies.
-->
<!-- Character entity set. Typical invocation:
<!ENTITY % ISOlat1 PUBLIC
"ISO 8879:1986//ENTITIES Added Latin 1//EN//XML">
%ISOlat1;
-->
<!-- This version of the entity set can be used with any SGML document
which uses ISO 8859-1 or ISO 10646 as its document character
set. This includes XML documents and ISO HTML documents.
-->
<!ENTITY Agrave "&#192;" ><!-- capital A, grave accent -->
<!ENTITY Aacute "&#193;" ><!-- capital A, acute accent -->
<!ENTITY Acirc "&#194;" ><!-- capital A, circumflex accent -->
<!ENTITY Atilde "&#195;" ><!-- capital A, tilde -->
<!ENTITY Auml "&#196;" ><!-- capital A, dieresis or umlaut mark -->
<!ENTITY Aring "&#197;" ><!-- capital A, ring -->
<!ENTITY AElig "&#198;" ><!-- capital AE diphthong (ligature) -->
<!ENTITY Ccedil "&#199;" ><!-- capital C, cedilla -->
<!ENTITY Egrave "&#200;" ><!-- capital E, grave accent -->
<!ENTITY Eacute "&#201;" ><!-- capital E, acute accent -->
<!ENTITY Ecirc "&#202;" ><!-- capital E, circumflex accent -->
<!ENTITY Euml "&#203;" ><!-- capital E, dieresis or umlaut mark -->
<!ENTITY Igrave "&#204;" ><!-- capital I, grave accent -->
<!ENTITY Iacute "&#205;" ><!-- capital I, acute accent -->
<!ENTITY Icirc "&#206;" ><!-- capital I, circumflex accent -->
<!ENTITY Iuml "&#207;" ><!-- capital I, dieresis or umlaut mark -->
<!ENTITY ETH "&#208;" ><!-- capital Eth, Icelandic -->
<!ENTITY Ntilde "&#209;" ><!-- capital N, tilde -->
<!ENTITY Ograve "&#210;" ><!-- capital O, grave accent -->
<!ENTITY Oacute "&#211;" ><!-- capital O, acute accent -->
<!ENTITY Ocirc "&#212;" ><!-- capital O, circumflex accent -->
<!ENTITY Otilde "&#213;" ><!-- capital O, tilde -->
<!ENTITY Ouml "&#214;" ><!-- capital O, dieresis or umlaut mark -->
<!ENTITY Oslash "&#216;" ><!-- capital O, slash -->
<!ENTITY Ugrave "&#217;" ><!-- capital U, grave accent -->
<!ENTITY Uacute "&#218;" ><!-- capital U, acute accent -->
<!ENTITY Ucirc "&#219;" ><!-- capital U, circumflex accent -->
<!ENTITY Uuml "&#220;" ><!-- capital U, dieresis or umlaut mark -->
<!ENTITY Yacute "&#221;" ><!-- capital Y, acute accent -->
<!ENTITY THORN "&#222;" ><!-- capital THORN, Icelandic -->
<!ENTITY szlig "&#223;" ><!-- small sharp s, German (sz ligature) -->
<!ENTITY agrave "&#224;" ><!-- small a, grave accent -->
<!ENTITY aacute "&#225;" ><!-- small a, acute accent -->
<!ENTITY acirc "&#226;" ><!-- small a, circumflex accent -->
<!ENTITY atilde "&#227;" ><!-- small a, tilde -->
<!ENTITY auml "&#228;" ><!-- small a, dieresis or umlaut mark -->
<!ENTITY aring "&#229;" ><!-- small a, ring -->
<!ENTITY aelig "&#230;" ><!-- small ae diphthong (ligature) -->
<!ENTITY ccedil "&#231;" ><!-- small c, cedilla -->
<!ENTITY egrave "&#232;" ><!-- small e, grave accent -->
<!ENTITY eacute "&#233;" ><!-- small e, acute accent -->
<!ENTITY ecirc "&#234;" ><!-- small e, circumflex accent -->
<!ENTITY euml "&#235;" ><!-- small e, dieresis or umlaut mark -->
<!ENTITY igrave "&#236;" ><!-- small i, grave accent -->
<!ENTITY iacute "&#237;" ><!-- small i, acute accent -->
<!ENTITY icirc "&#238;" ><!-- small i, circumflex accent -->
<!ENTITY iuml "&#239;" ><!-- small i, dieresis or umlaut mark -->
<!ENTITY eth "&#240;" ><!-- small eth, Icelandic -->
<!ENTITY ntilde "&#241;" ><!-- small n, tilde -->
<!ENTITY ograve "&#242;" ><!-- small o, grave accent -->
<!ENTITY oacute "&#243;" ><!-- small o, acute accent -->
<!ENTITY ocirc "&#244;" ><!-- small o, circumflex accent -->
<!ENTITY otilde "&#245;" ><!-- small o, tilde -->
<!ENTITY ouml "&#246;" ><!-- small o, dieresis or umlaut mark -->
<!ENTITY oslash "&#248;" ><!-- small o, slash -->
<!ENTITY ugrave "&#249;" ><!-- small u, grave accent -->
<!ENTITY uacute "&#250;" ><!-- small u, acute accent -->
<!ENTITY ucirc "&#251;" ><!-- small u, circumflex accent -->
<!ENTITY uuml "&#252;" ><!-- small u, dieresis or umlaut mark -->
<!ENTITY yacute "&#253;" ><!-- small y, acute accent -->
<!ENTITY thorn "&#254;" ><!-- small thorn, Icelandic -->
<!ENTITY yuml "&#255;" ><!-- small y, dieresis or umlaut mark -->

109
src/documentation/content/xdocs/dtd/ISOnum.pen Normal file
View File

@ -0,0 +1,109 @@
<!-- (C) International Organization for Standardization 1986
Permission to copy in any form is granted for use with
conforming SGML systems and applications as defined in
ISO 8879, provided this notice is included in all copies.
-->
<!-- Character entity set. Typical invocation:
<!ENTITY % ISOnum PUBLIC
"ISO 8879:1986//ENTITIES Numeric and Special Graphic//EN//XML">
%ISOnum;
-->
<!-- This version of the entity set can be used with any SGML document
which uses ISO 10646 as its document character set.
This includes XML documents and ISO HTML documents.
This entity set uses hexadecimal numeric character references.
Creator: Rick Jelliffe, Allette Systems
Version: 1997-07-07
-->
<!ENTITY half "&#189;" ><!--=fraction one-half-->
<!ENTITY frac12 "&#189;" ><!--=fraction one-half-->
<!ENTITY frac14 "&#188;" ><!--=fraction one-quarter-->
<!ENTITY frac34 "&#190;" ><!--=fraction three-quarters-->
<!ENTITY frac18 "&#x215B;" >
<!-- or "&#xB1;&#x202;&#x2044;&#x2088;" --><!--=fraction one-eighth-->
<!ENTITY frac38 "&#x215C;" >
<!-- or "&#xB3;&#x2044;&#x2088;" --><!--=fraction three-eighths-->
<!ENTITY frac58 "&#x215D;" >
<!-- or "&#x2075;&#x2044;&#x2088;" --><!--=fraction five-eighths-->
<!ENTITY frac78 "&#x215E;" >
<!-- or "&#x2077;&#x2044;&#x2088;" --><!--=fraction seven-eighths-->
<!ENTITY sup1 "&#185;" ><!--=superscript one-->
<!ENTITY sup2 "&#178;" ><!--=superscript two-->
<!ENTITY sup3 "&#179;" ><!--=superscript three-->
<!ENTITY plus "+" ><!--=plus sign B:-->
<!ENTITY plusmn "&#xB1;" ><!--/pm B: =plus-or-minus sign-->
<!ENTITY lt "&#38;#60;" ><!--=less-than sign R:-->
<!ENTITY equals "=" ><!--=equals sign R:-->
<!ENTITY gt ">" ><!--=greater-than sign R:-->
<!ENTITY divide "&#247;" ><!--/div B: =divide sign-->
<!ENTITY times "&#215;" ><!--/times B: =multiply sign-->
<!ENTITY curren "&#164;" ><!--=general currency sign-->
<!ENTITY pound "&#163;" ><!--=pound sign-->
<!ENTITY dollar "$" ><!--=dollar sign-->
<!ENTITY cent "&#162;" ><!--=cent sign-->
<!ENTITY yen "&#165;" ><!--/yen =yen sign-->
<!ENTITY num "#" ><!--=number sign-->
<!ENTITY percnt "&#37;" ><!--=percent sign-->
<!ENTITY amp "&#38;#38;" ><!--=ampersand-->
<!ENTITY ast "*" ><!--/ast B: =asterisk-->
<!ENTITY commat "@" ><!--=commercial at-->
<!ENTITY lsqb "[" ><!--/lbrack O: =left square bracket-->
<!ENTITY bsol "\" ><!--/backslash =reverse solidus-->
<!ENTITY rsqb "]" ><!--/rbrack C: =right square bracket-->
<!ENTITY lcub "{" ><!--/lbrace O: =left curly bracket-->
<!ENTITY horbar "&#x2015;" ><!--=horizontal bar-->
<!ENTITY verbar "|" ><!--/vert =vertical bar-->
<!ENTITY rcub "}" ><!--/rbrace C: =right curly bracket-->
<!ENTITY micro "&#181;" ><!--=micro sign-->
<!ENTITY ohm "&#2126;" ><!--=ohm sign-->
<!ENTITY deg "&#176;" ><!--=degree sign-->
<!ENTITY ordm "&#186;" ><!--=ordinal indicator, masculine-->
<!ENTITY ordf "&#170;" ><!--=ordinal indicator, feminine-->
<!ENTITY sect "&#167;" ><!--=section sign-->
<!ENTITY para "&#182;" ><!--=pilcrow (paragraph sign)-->
<!ENTITY middot "&#183;" ><!--/centerdot B: =middle dot-->
<!ENTITY larr "&#x2190;" ><!--/leftarrow /gets A: =leftward arrow-->
<!ENTITY rarr "&#x2192;" ><!--/rightarrow /to A: =rightward arrow-->
<!ENTITY uarr "&#x2191;" ><!--/uparrow A: =upward arrow-->
<!ENTITY darr "&#x2193;" ><!--/downarrow A: =downward arrow-->
<!ENTITY copy "&#169;" ><!--=copyright sign-->
<!ENTITY reg "&#174;" ><!--/circledR =registered sign-->
<!ENTITY trade "&#8482;" ><!--=trade mark sign-->
<!ENTITY brvbar "&#xA6;" ><!--=bren (vertical) bar-->
<!ENTITY not "&#xAC;" ><!--/neg /lnot =not sign-->
<!ENTITY sung "&#x266A;" ><!--=music note (sung text sign)-->
<!ENTITY excl "!" ><!--=exclamation mark-->
<!ENTITY iexcl "&#xA1;" ><!--=inverted exclamation mark-->
<!ENTITY quot '"' ><!--=quotation mark-->
<!ENTITY apos "'" ><!--=apostrophe-->
<!ENTITY lpar "(" ><!--O: =left parenthesis-->
<!ENTITY rpar ")" ><!--C: =right parenthesis-->
<!ENTITY comma "," ><!--P: =comma-->
<!ENTITY lowbar "_" ><!--=low line-->
<!ENTITY hyphen "&#x2010;" ><!--=hyphen-->
<!ENTITY period "." ><!--=full stop, period-->
<!ENTITY sol "/" ><!--=solidus-->
<!ENTITY colon ":" ><!--/colon P:-->
<!ENTITY semi ";" ><!--=semicolon P:-->
<!ENTITY quest "?" ><!--=question mark-->
<!ENTITY iquest "&#xBF;" ><!--=inverted question mark-->
<!ENTITY laquo "&#x2039;" ><!--=angle quotation mark, left
But note that Unicode 1 & Maler & el Andaloussi give &#xAB; -->
<!ENTITY raquo "&#x203A;" ><!--=angle quotation mark, right
But note that Unicode 1 & Maler & el Andaloussi give &#xBB; -->
<!ENTITY lsquo "&#x2018;" ><!--=single quotation mark, left-->
<!ENTITY rsquo "&#x2019;" ><!--=single quotation mark, right-->
<!ENTITY ldquo "&#x201C;" ><!--=double quotation mark, left-->
<!ENTITY rdquo "&#x201D;" ><!--=double quotation mark, right-->
<!ENTITY nbsp "&#160;" ><!--=no break (required) space-->
<!ENTITY shy "&#173;" ><!--=soft hyphen-->

110
src/documentation/content/xdocs/dtd/ISOpub.pen Normal file
View File

@ -0,0 +1,110 @@
<!-- (C) International Organization for Standardization 1986
Permission to copy in any form is granted for use with
conforming SGML systems and applications as defined in
ISO 8879, provided this notice is included in all copies.
-->
<!-- Character entity set. Typical invocation:
<!ENTITY % ISOpub PUBLIC
"ISO 8879:1986//ENTITIES Publishing//EN//XML">
%ISOpub;
-->
<!-- This version of the entity set can be used with any SGML document
which uses ISO 10646 as its document character set.
This includes XML documents and ISO HTML documents.
This entity set uses hexadecimal numeric character references.
Creator: Rick Jelliffe, Allette Systems
Version: 1997-07-07
-->
<!ENTITY emsp "&#x2003;" ><!--=em space-->
<!ENTITY ensp "&#x2002;" ><!--=en space (1/2-em)-->
<!ENTITY emsp13 "&#x2004;" ><!--=1/3-em space-->
<!ENTITY emsp14 "&#x2005;" ><!--=1/4-em space-->
<!ENTITY numsp "&#x2007;" ><!--=digit space (width of a number)-->
<!ENTITY puncsp "&#x2008;" ><!--=punctuation space (width of comma)-->
<!ENTITY thinsp "&#x2009;" ><!--=thin space (1/6-em)-->
<!ENTITY hairsp "&#x200A;" ><!--=hair space-->
<!ENTITY mdash "&#x2014;" ><!--=em dash-->
<!ENTITY ndash "&#x2013;" ><!--=en dash-->
<!ENTITY dash "&#x2010;" ><!--=hyphen (true graphic)-->
<!ENTITY blank "&#x2423;" ><!--=significant blank symbol-->
<!ENTITY hellip "&#x2026;" ><!--=ellipsis (horizontal)-->
<!ENTITY nldr "&#x2025;" ><!--=double baseline dot (en leader)-->
<!ENTITY frac13 "&#x2153;" ><!--=fraction one-third-->
<!ENTITY frac23 "&#x2154;" ><!--=fraction two-thirds-->
<!ENTITY frac15 "&#x2155;" ><!--=fraction one-fifth-->
<!ENTITY frac25 "&#x2156;" ><!--=fraction two-fifths-->
<!ENTITY frac35 "&#x2157;" ><!--=fraction three-fifths-->
<!ENTITY frac45 "&#x2158;" ><!--=fraction four-fifths-->
<!ENTITY frac16 "&#x2159;" ><!--=fraction one-sixth-->
<!ENTITY frac56 "&#x215a;" ><!--=fraction five-sixths-->
<!ENTITY incare "&#x2105;" ><!--=in-care-of symbol-->
<!ENTITY block "&#x2588;" ><!--=full block-->
<!ENTITY uhblk "&#x2580;" ><!--=upper half block-->
<!ENTITY lhblk "&#x2584;" ><!--=lower half block-->
<!ENTITY blk14 "&#x2591;" ><!--=25% shaded block-->
<!ENTITY blk12 "&#x2592;" ><!--=50% shaded block-->
<!ENTITY blk34 "&#x2593;" ><!--=75% shaded block-->
<!ENTITY marker "&#x25AE;" ><!--=histogram marker-->
<!ENTITY cir "&#x25CB;" ><!--/circ B: =circle, open-->
<!ENTITY squ "&#x25A1;" ><!--=square, open-->
<!ENTITY rect "&#x25AD;" ><!--=rectangle, open-->
<!ENTITY utri "&#x25B5;" ><!--/triangle =up triangle, open-->
<!ENTITY dtri "&#x25BF;" ><!--/triangledown =down triangle, open-->
<!ENTITY star "&#x2606;" ><!--=star, open-->
<!ENTITY bull "&#x2022;" ><!--/bullet B: =round bullet, filled-->
<!ENTITY squf "&#x25AA;" ><!--/blacksquare =sq bullet, filled-->
<!ENTITY utrif "&#x25B4;" ><!--/blacktriangle =up tri, filled-->
<!ENTITY dtrif "&#x25BE;" ><!--/blacktriangledown =dn tri, filled-->
<!ENTITY ltrif "&#x25C2;" ><!--/blacktriangleleft R: =l tri, filled-->
<!ENTITY rtrif "&#x25B8;" ><!--/blacktriangleright R: =r tri, filled-->
<!ENTITY clubs "&#x2663;" ><!--/clubsuit =club suit symbol-->
<!ENTITY diams "&#x2662;" ><!--/diamondsuit =diamond suit symbol-->
<!ENTITY hearts "&#x2661;" ><!--/heartsuit =heart suit symbol-->
<!ENTITY spades "&#x2660;" ><!--/spadesuit =spades suit symbol-->
<!ENTITY malt "&#x2720;" ><!--/maltese =maltese cross-->
<!ENTITY dagger "&#x2020;" ><!--/dagger B: =dagger-->
<!ENTITY Dagger "&#x2021;" ><!--/ddagger B: =double dagger-->
<!ENTITY check "&#x2713;" ><!--/checkmark =tick, check mark-->
<!ENTITY cross "&#x2717;" ><!--=ballot cross-->
<!ENTITY sharp "&#x266F;" ><!--/sharp =musical sharp-->
<!ENTITY flat "&#x266D;" ><!--/flat =musical flat-->
<!ENTITY male "&#x2642;" ><!--=male symbol-->
<!ENTITY female "&#x2640;" ><!--=female symbol-->
<!ENTITY phone "&#x26E0;" ><!--=telephone symbol-->
<!ENTITY telrec "&#x2315;" ><!--=telephone recorder symbol-->
<!ENTITY copysr "&#x2117;" ><!--=sound recording copyright sign-->
<!ENTITY caret "&#x2041;" ><!--=caret (insertion mark)-->
<!ENTITY lsquor "&#x201A;" ><!--=rising single quote, left (low)-->
<!ENTITY ldquor "&#x201E;" ><!--=rising dbl quote, left (low)-->
<!ENTITY fflig "&#xFB00;" ><!--small ff ligature-->
<!ENTITY filig "&#xFB01;" ><!--small fi ligature-->
<!ENTITY fjlig "fj" ><!--small fj ligature-->
<!ENTITY ffilig "&#xFB03;" ><!--small ffi ligature-->
<!ENTITY ffllig "&#xFB04;" ><!--small ffl ligature-->
<!ENTITY fllig "&#xFB02;" ><!--small fl ligature-->
<!ENTITY mldr "&#x2025;" ><!--em leader-->
<!ENTITY rdquor "&#x201D;" ><!--rising dbl quote, right (high)-->
<!ENTITY rsquor "&#x2019;" ><!--rising single quote, right (high)-->
<!ENTITY vellip "&#x22EE;" ><!--vertical ellipsis-->
<!ENTITY hybull "&#x2043;" ><!--rectangle, filled (hyphen bullet)-->
<!ENTITY loz "&#x2727;" ><!--/lozenge - lozenge or total mark-->
<!ENTITY lozf "&#x2726;" ><!--/blacklozenge - lozenge, filled-->
<!ENTITY ltri "&#x25C3;" ><!--/triangleleft B: l triangle, open-->
<!ENTITY rtri "&#x25B9;" ><!--/triangleright B: r triangle, open-->
<!ENTITY starf "&#x2605;" ><!--/bigstar - star, filled-->
<!ENTITY natur "&#x266E;" ><!--/natural - music natural-->
<!ENTITY rx "&#x211E;" ><!--pharmaceutical prescription (Rx)-->
<!ENTITY sext "&#x2736;" ><!--sextile (6-pointed star)-->
<!ENTITY target "&#x2316;" ><!--register mark or target-->
<!ENTITY dlcrop "&#x230D;" ><!--downward left crop mark -->
<!ENTITY drcrop "&#x230C;" ><!--downward right crop mark -->
<!ENTITY ulcrop "&#x230F;" ><!--upward left crop mark -->
<!ENTITY urcrop "&#x230E;" ><!--upward right crop mark -->

85
src/documentation/content/xdocs/dtd/ISOtech.pen Normal file
View File

@ -0,0 +1,85 @@
<!-- (C) International Organization for Standardization 1986
Permission to copy in any form is granted for use with
conforming SGML systems and applications as defined in
ISO 8879, provided this notice is included in all copies.
-->
<!-- Character entity set. Typical invocation:
<!ENTITY % ISOtech PUBLIC
"ISO 8879:1986//ENTITIES General Technical//EN//XML"
"ISOtech.pen">
%ISOtech;
-->
<!-- This version of the entity set can be used with any SGML document
which uses ISO 10646 as its document character set.
This includes XML documents and ISO HTML documents.
This entity set uses hexadecimal numeric character references.
Creator: Rick Jelliffe, Allette Systems
Version: 1997-07-07
-->
<!ENTITY aleph "&#x2135;" ><!--/aleph =aleph, Hebrew-->
<!ENTITY and "&#x2227;" ><!--/wedge /land B: =logical and-->
<!ENTITY ang90 "&#x221F;" ><!--=right (90 degree) angle-->
<!ENTITY angsph "&#x2222;" ><!--/sphericalangle =angle-spherical-->
<!ENTITY ap "&#x2249;" ><!--/approx R: =approximate-->
<!ENTITY becaus "&#x2235;" ><!--/because R: =because-->
<!ENTITY bottom "&#x22A5;" ><!--/bot B: =perpendicular-->
<!ENTITY cap "&#x2229;" ><!--/cap B: =intersection-->
<!ENTITY cong "&#x2245;" ><!--/cong R: =congruent with-->
<!ENTITY conint "&#x222E;" ><!--/oint L: =contour integral operator-->
<!ENTITY cup "&#x222A;" ><!--/cup B: =union or logical sum-->
<!ENTITY equiv "&#x2261;" ><!--/equiv R: =identical with-->
<!ENTITY exist "&#x2203;" ><!--/exists =at least one exists-->
<!ENTITY forall "&#x2200;" ><!--/forall =for all-->
<!ENTITY fnof "&#x192;" ><!--=function of (italic small f)-->
<!ENTITY ge "&#x2265;" ><!--/geq /ge R: =greater-than-or-equal-->
<!ENTITY iff "&#x21D4;" ><!--/iff =if and only if-->
<!ENTITY infin "&#x221E;" ><!--/infty =infinity-->
<!ENTITY int "&#x222B;" ><!--/int L: =integral operator-->
<!ENTITY isin "&#x2208;" ><!--/in R: =set membership-->
<!ENTITY lang "&#x2329;" ><!--/langle O: =left angle bracket-->
<!ENTITY lArr "&#x21D0;" ><!--/Leftarrow A: =is implied by-->
<!ENTITY le "&#x2264;" ><!--/leq /le R: =less-than-or-equal-->
<!ENTITY minus "-" ><!--B: =minus sign-->
<!ENTITY mnplus "&#x2213;" ><!--/mp B: =minus-or-plus sign-->
<!ENTITY nabla "&#x2207;" ><!--/nabla =del, Hamilton operator-->
<!ENTITY ne "&#x2260;" ><!--/ne /neq R: =not equal-->
<!ENTITY ni "&#x220B;" ><!--/ni /owns R: =contains-->
<!ENTITY or "&#x2228;" ><!--/vee /lor B: =logical or-->
<!ENTITY par "&#x2225;" ><!--/parallel R: =parallel-->
<!ENTITY part "&#x2202;" ><!--/partial =partial differential-->
<!ENTITY permil "&#x2030;" ><!--=per thousand-->
<!ENTITY perp "&#x22A5;" ><!--/perp R: =perpendicular-->
<!ENTITY prime "&#x2032;" ><!--/prime =prime or minute-->
<!ENTITY Prime "&#x2033;" ><!--=double prime or second-->
<!ENTITY prop "&#x221D;" ><!--/propto R: =is proportional to-->
<!ENTITY radic "&#x221A;" ><!--/surd =radical-->
<!ENTITY rang "&#x232A;" ><!--/rangle C: =right angle bracket-->
<!ENTITY rArr "&#x21D2;" ><!--/Rightarrow A: =implies-->
<!ENTITY sim "&#x223C;" ><!--/sim R: =similar-->
<!ENTITY sime "&#x2243;" ><!--/simeq R: =similar, equals-->
<!ENTITY square "&#x25A1;" ><!--/square B: =square-->
<!ENTITY sub "&#x2282;" ><!--/subset R: =subset or is implied by-->
<!ENTITY sube "&#x2286;" ><!--/subseteq R: =subset, equals-->
<!ENTITY sup "&#x2283;" ><!--/supset R: =superset or implies-->
<!ENTITY supe "&#x2287;" ><!--/supseteq R: =superset, equals-->
<!ENTITY there4 "&#x2234;" ><!--/therefore R: =therefore-->
<!ENTITY Verbar "&#x2016;" ><!--/Vert =dbl vertical bar-->
<!ENTITY angst "&#x212B;" ><!--Angstrom =capital A, ring-->
<!ENTITY bernou "&#x212C;" ><!--Bernoulli function (script capital B)-->
<!ENTITY compfn "&#x2218;" ><!--B: composite function (small circle)-->
<!ENTITY Dot "&#xA8;" ><!--=dieresis or umlaut mark-->
<!ENTITY DotDot "&#x20DC;" ><!--four dots above-->
<!ENTITY hamilt "&#x210B;" ><!--Hamiltonian (script capital H)-->
<!ENTITY lagran "&#x2112;" ><!--Lagrangian (script capital L)-->
<!ENTITY lowast "&#x2217;" ><!--low asterisk-->
<!ENTITY notin "&#x2209;" ><!--N: negated set membership-->
<!ENTITY order "&#x2134;" ><!--order of (script small o)-->
<!ENTITY phmmat "&#x2133;" ><!--physics M-matrix (script capital M)-->
<!ENTITY tdot "&#x20DB;" ><!--three dots above-->
<!ENTITY tprime "&#x2034;" ><!--triple prime-->
<!ENTITY wedgeq "&#x2259;" ><!--R: corresponds to (wedge, equals)-->

70
src/documentation/content/xdocs/dtd/book-cocoon-v10.dtd Normal file
View File

@ -0,0 +1,70 @@
<!-- ===================================================================
Apache Cocoon Documentation Book DTD (Version 1.0)
PURPOSE:
This DTD defines the */book.xml documentation configuration files.
TYPICAL INVOCATION:
<!DOCTYPE book PUBLIC
"-//APACHE//DTD Cocoon Documentation Book Vx.yz//EN"
"book-cocoon-vxyz.dtd">
where
x := major version
y := minor version
z := status identifier (optional)
NOTES:
We need to replace this DTD with the proper one.
We are only using this DTD to enable validation during "build docs"
because every XML instance must declare its ruleset.
This initial minimal DTD has been reverse-engineered from the structure
of the current documents, e.g.
documentation/xdocs/book.xml
AUTHORS:
David Crossley <crossley@apache.org>
FIXME:
- find the proper DTD for book.xml
CHANGE HISTORY:
20011031 Initial version. (DC)
COPYRIGHT:
Copyright (c) @year@ The Apache Software Foundation.
Permission to copy in any form is granted provided this notice is
included in all copies. Permission to redistribute is granted
provided this file is distributed untouched in all its parts and
included files.
==================================================================== -->
<!ELEMENT book (menu+)>
<!ELEMENT menu (menu-item|external)*>
<!ELEMENT menu-item EMPTY>
<!ELEMENT external EMPTY>
<!ATTLIST book software CDATA #REQUIRED
title CDATA #REQUIRED
copyright CDATA #REQUIRED
xmlns:xlink CDATA #IMPLIED
>
<!ATTLIST menu label CDATA #REQUIRED
>
<!ATTLIST menu-item label CDATA #REQUIRED
href CDATA #REQUIRED
type (visible|hidden) "visible"
>
<!ATTLIST external label CDATA #REQUIRED
href CDATA #REQUIRED
type (visible|hidden) "visible"
>
<!-- =============================================================== -->
<!-- End of DTD -->
<!-- =============================================================== -->

93
src/documentation/content/xdocs/dtd/changes-v11.dtd Normal file
View File

@ -0,0 +1,93 @@
<!-- ===================================================================
Apache Changes DTD (Version 1.1)
PURPOSE:
This DTD was developed to create a simple yet powerful document
type for software development changes for use with the Apache projects.
It is an XML-compliant DTD and it's maintained by the Apache XML
project.
TYPICAL INVOCATION:
<!DOCTYPE document PUBLIC
"-//APACHE//DTD Changes Vx.y//EN"
"changes-vxy.dtd">
where
x := major version
y := minor version
NOTES:
It is important, expecially in open developped software projects, to keep
track of software changes both to give users indications of bugs that might
have been resolved, as well, and not less important, to provide credits
for the support given to the project. It is considered vital to provide
adequate payback using recognition and credits to let users and developers
feel part of the community, thus increasing development power.
AUTHORS:
Stefano Mazzocchi <stefano@apache.org>
FIXME:
CHANGE HISTORY:
[Version 1.0]
19991129 Initial version. (SM)
20000316 Added bugfixing attribute. (SM)
[Version 1.1]
20011212 Used public identifiers for external entities (SM)
COPYRIGHT:
Copyright (c) @year@ The Apache Software Foundation.
Permission to copy in any form is granted provided this notice is
included in all copies. Permission to redistribute is granted
provided this file is distributed untouched in all its parts and
included files.
==================================================================== -->
<!-- =============================================================== -->
<!-- Include the Documentation DTD -->
<!-- =============================================================== -->
<!ENTITY % document PUBLIC
"-//APACHE//DTD Documentation V1.1//EN"
"document-v11.dtd">
%document;
<!-- =============================================================== -->
<!-- Common entities -->
<!-- =============================================================== -->
<!ENTITY % types "add|remove|update|fix|unknown">
<!-- =============================================================== -->
<!-- Document Type Definition -->
<!-- =============================================================== -->
<!ELEMENT changes (devs, release*)>
<!ATTLIST changes %common.att;
%title.att;>
<!ELEMENT devs (person+)>
<!ATTLIST devs %common.att;>
<!ELEMENT release (action+)>
<!ATTLIST release %common.att;
version CDATA #REQUIRED
date CDATA #REQUIRED>
<!ELEMENT action (%content.mix;)*>
<!ATTLIST action %common.att;
dev IDREF #REQUIRED
type (%types;) #IMPLIED
due-to CDATA #IMPLIED
due-to-email CDATA #IMPLIED
fixes-bug CDATA #IMPLIED>
<!-- =============================================================== -->
<!-- End of DTD -->
<!-- =============================================================== -->

71
src/documentation/content/xdocs/dtd/changes-v11.mod Normal file
View File

@ -0,0 +1,71 @@
<!--
Copyright 1999-2004 The Apache Software Foundation
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<!-- ===================================================================
Apache Changes Module (Version 1.1)
PURPOSE:
This DTD was developed to create a simple yet powerful document
type for software development changes for use with the Apache projects.
It is an XML-compliant DTD and it's maintained by the Apache XML
project.
TYPICAL INVOCATION:
<!ENTITY % changes PUBLIC
"-//APACHE//ENTITIES Changes Vxy//EN"
"changes-vxy.mod">
%changes;
where
x := major version
y := minor version
NOTES:
It is important, expecially in open developped software projects, to keep
track of software changes both to give users indications of bugs that might
have been resolved, as well, and not less important, to provide credits
for the support given to the project. It is considered vital to provide
adequate payback using recognition and credits to let users and developers
feel part of the community, thus increasing development power.
FIXME:
CHANGE HISTORY:
[Version 1.0]
19991129 Initial version. (SM)
20000316 Added bugfixing attribute. (SM)
[Version 1.1]
20011212 Used public identifiers for external entities (SM)
==================================================================== -->
<!-- =============================================================== -->
<!-- Document Type Definition -->
<!-- =============================================================== -->
<!ELEMENT changes (title?, devs?, release+)>
<!ATTLIST changes %common.att;>
<!ELEMENT release (action+)>
<!ATTLIST release %common.att;
version CDATA #REQUIRED
date CDATA #REQUIRED>
<!-- =============================================================== -->
<!-- End of DTD -->
<!-- =============================================================== -->

95
src/documentation/content/xdocs/dtd/changes-v13.dtd Normal file
View File

@ -0,0 +1,95 @@
<!--
Copyright 2002-2004 The Apache Software Foundation
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<!-- ===================================================================
Apache Changes DTD (Version 1.2)
PURPOSE:
This DTD was developed to create a simple yet powerful document
type for software development changes for use with the Apache projects.
It is an XML-compliant DTD and it's maintained by the Apache XML
project.
TYPICAL INVOCATION:
<!DOCTYPE document PUBLIC
"-//APACHE//DTD Changes Vx.y//EN"
"changes-vxy.dtd">
where
x := major version
y := minor version
NOTES:
It is important, expecially in open developped software projects, to keep
track of software changes both to give users indications of bugs that might
have been resolved, as well, and not less important, to provide credits
for the support given to the project. It is considered vital to provide
adequate payback using recognition and credits to let users and developers
feel part of the community, thus increasing development power.
FIXME:
CHANGE HISTORY:
[Version 1.0]
20020611 Initial version. (SN)
20020613 Include the module of ISO character entity sets (DC)
[Version 1.2]
20030424 Adopt the loosened content model from document-v12 (JT)
20040614 Stay current with latest document-v13 (class attribute)
==================================================================== -->
<!-- =============================================================== -->
<!-- Include the Documentation DTD -->
<!-- =============================================================== -->
<!ENTITY % document PUBLIC
"-//APACHE//ENTITIES Documentation V1.3//EN"
"document-v13.mod">
%document;
<!-- =============================================================== -->
<!-- Include the Common ISO Character Entity Sets -->
<!-- =============================================================== -->
<!ENTITY % common-charents PUBLIC
"-//APACHE//ENTITIES Common Character Entity Sets V1.0//EN"
"common-charents-v10.mod">
%common-charents;
<!-- =============================================================== -->
<!-- Include the Common elements -->
<!-- =============================================================== -->
<!ENTITY % common PUBLIC
"-//APACHE//ENTITIES Common Elements V1.0//EN"
"common-elems-v10.mod">
%common;
<!-- =============================================================== -->
<!-- Include the Changes module -->
<!-- =============================================================== -->
<!ENTITY % changes PUBLIC
"-//APACHE//ENTITIES Changes V1.1//EN"
"changes-v11.mod">
%changes;
<!-- =============================================================== -->
<!-- End of DTD -->
<!-- =============================================================== -->

74
src/documentation/content/xdocs/dtd/common-charents-v10.mod Normal file
View File

@ -0,0 +1,74 @@
<!--
Copyright 2002-2004 The Apache Software Foundation
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<!-- ===================================================================
Apache Common Character Entity Sets (Version 1.0)
PURPOSE:
Common elements across all DTDs.
TYPICAL INVOCATION:
<!ENTITY % common-charents PUBLIC
"-//APACHE//ENTITIES Common Character Entity Sets Vx.y//EN"
"common-charents-vxy.mod">
%common-charents;
where
x := major version
y := minor version
FIXME:
CHANGE HISTORY:
[Version 1.0]
20020613 Initial version. (DC)
==================================================================== -->
<!-- =============================================================== -->
<!-- Common ISO character entity sets -->
<!-- =============================================================== -->
<!ENTITY % ISOlat1 PUBLIC
"ISO 8879:1986//ENTITIES Added Latin 1//EN//XML"
"../entity/ISOlat1.pen">
%ISOlat1;
<!ENTITY % ISOpub PUBLIC
"ISO 8879:1986//ENTITIES Publishing//EN//XML"
"../entity/ISOpub.pen">
%ISOpub;
<!ENTITY % ISOtech PUBLIC
"ISO 8879:1986//ENTITIES General Technical//EN//XML"
"../entity/ISOtech.pen">
%ISOtech;
<!ENTITY % ISOnum PUBLIC
"ISO 8879:1986//ENTITIES Numeric and Special Graphic//EN//XML"
"../entity/ISOnum.pen">
%ISOnum;
<!ENTITY % ISOdia PUBLIC
"ISO 8879:1986//ENTITIES Diacritical Marks//EN//XML"
"../entity/ISOdia.pen">
%ISOdia;
<!-- =============================================================== -->
<!-- End of DTD -->
<!-- =============================================================== -->

68
src/documentation/content/xdocs/dtd/common-elems-v10.mod Normal file
View File

@ -0,0 +1,68 @@
<!--
Copyright 2002-2004 The Apache Software Foundation
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<!-- ===================================================================
Apache Common Elements (Version 1.0)
PURPOSE:
Common elements across DTDs
TYPICAL INVOCATION:
<!ENTITY % common PUBLIC
"-//APACHE//ENTITIES Common elements Vx.y//EN"
"common-elems-vxy.mod">
%common;
where
x := major version
y := minor version
FIXME:
CHANGE HISTORY:
[Version 1.0]
20020611 Initial version. (SN)
==================================================================== -->
<!-- =============================================================== -->
<!-- Common entities -->
<!-- =============================================================== -->
<!ENTITY % types "add|remove|update|fix">
<!ENTITY % contexts "build|docs|code|admin|design">
<!-- =============================================================== -->
<!-- Common elements -->
<!-- =============================================================== -->
<!ELEMENT devs (person+)>
<!ATTLIST devs %common.att;>
<!ELEMENT action (%content.mix;)*>
<!ATTLIST action %common.att;
dev IDREF #REQUIRED
type (%types;) #IMPLIED
context (%contexts;) #IMPLIED
due-to CDATA #IMPLIED
due-to-email CDATA #IMPLIED
fixes-bug CDATA #IMPLIED>
<!-- =============================================================== -->
<!-- End of DTD -->
<!-- =============================================================== -->

541
src/documentation/content/xdocs/dtd/document-v11.dtd Normal file
View File

@ -0,0 +1,541 @@
<!-- ===================================================================
Apache Documentation DTD (Version 1.1)
PURPOSE:
This DTD was developed to create a simple yet powerful document
type for software documentation for use with the Apache projects.
It is an XML-compliant DTD and it's maintained by the Apache XML
project.
TYPICAL INVOCATION:
<!DOCTYPE document PUBLIC
"-//APACHE//DTD Documentation Vx.y//EN"
"document-vxy.dtd">
where
x := major version
y := minor version
NOTES:
Many of the design patterns used in this DTD were take from the
W3C XML Specification DTD edited by Eve Maler <elm@arbortext.com>.
Where possible, great care has been used to reuse HTML tag
names to reduce learning efforts and to allow HTML editors to be
used for complex authorings like tables and lists.
EXTENSIBILITY:
This DTD includes several empty placeholders that can be used to
extend it. These placeholders are implemented with empty entities. Here
is the list of those empty entities and what they are used for:
- local.inline: this entity should contain extended definitions of
elements that can be used 'inline', or directly inside
the content. An example for this entity could be
<!ENTITY % local.inline "|citation">
- local.blocks: this entity should contain extended definitions of
elements that behave as 'blocks', thus can be visually
rendered as areas on the canvas. An example for this
entity could be:
<!ENTITY % local.blocks "|poem">
- local.sections: this entity should contain extended definitions of
elements that behave as 'sections', thus can be considered
containers of block-level elements. An example for
this entity could be:
<!ENTITY % local.sections "|chapter">
- local.headers: this entity should contain extended definitions of
elements that behave as parts of the document header.
An example for this header could be:
<!ENTITY % local.headers ", notes?">
- local.footers: this entity should contain extended definitions of
elements that behave as parts of the document footer.
An example for this header could be:
<!ENTITY % local.footers ", annotations*">
AUTHORS:
Stefano Mazzocchi <stefano@apache.org>
Steven Noels <stevenn@outerthought.org>
FIXME:
- should "form" tags be included?
CHANGE HISTORY:
[Version 1.0]
19991121 Initial version. (SM)
19991123 Replaced "res" with more standard "strong" for emphasis. (SM)
19991124 Added "fork" element for window forking behavior. (SM)
19991124 Added "img-inline" element to separate from "img". (SM)
19991129 Removed "affiliation" from "author". (SM)
19991129 Made "author" empty and moved "name|email" as attributes. (SM)
19991215 Simplified table section. (SM)
19991215 Changed "img-block" in more friendly "figure". (SM)
20000125 Added the "icon" image. (SM)
20000126 Allowed "anchor" in all levels. (SM)
20000404 Removed the "role" attribute from common-xxx.att. (SM)
20000815 Allowed "code" inside "strong" and "em". (SM)
[Version 1.1]
20011212 Used public identifiers for external entities. (SM)
20011212 Removed xlink attributes since not used. (SM)
20011212 Removed "connect" since not required at this level. (SM)
20011218 Added "warning" as a block level object. (SM)
20011218 Removed explicitly numbered sections ("s1|s2|s3|s4"). (SM)
20011218 Added "section" element. (SM)
20011218 Allowed "body" to have blocks without a section. (SM)
20011218 Removed "sl" since not really different from "ul". (SM)
20020214 Moved empty placeholder entity declarations up front (SNS)
20020214 Corrected content model of content.mix parameter entity (SNS)
COPYRIGHT:
Copyright (c) @year@ The Apache Software Foundation.
Permission to copy in any form is granted provided this notice is
included in all copies. Permission to redistribute is granted
provided this file is distributed untouched in all its parts and
included files.
==================================================================== -->
<!-- =============================================================== -->
<!-- Common character entities (included from external file) -->
<!-- =============================================================== -->
<!ENTITY % ISOlat1 PUBLIC
"ISO 8879:1986//ENTITIES Added Latin 1//EN//XML"
"ISOlat1.pen">
%ISOlat1;
<!ENTITY % ISOpub PUBLIC
"ISO 8879:1986//ENTITIES Publishing//EN//XML"
"ISOpub.pen">
%ISOpub;
<!ENTITY % ISOtech PUBLIC
"ISO 8879:1986//ENTITIES General Technical//EN//XML"
"ISOtech.pen">
%ISOtech;
<!ENTITY % ISOnum PUBLIC
"ISO 8879:1986//ENTITIES Numeric and Special Graphic//EN//XML"
"ISOnum.pen">
%ISOnum;
<!ENTITY % ISOdia PUBLIC
"ISO 8879:1986//ENTITIES Diacritical Marks//EN//XML"
"ISOdia.pen">
%ISOdia;
<!-- =============================================================== -->
<!-- Useful entities for increased DTD readability -->
<!-- =============================================================== -->
<!ENTITY % text "#PCDATA">
<!-- Entities referred to later on are defined up front -->
<!ENTITY % markup "strong|em|code|sub|sup">
<!ENTITY % special-inline "br|img|icon">
<!ENTITY % links "link|jump|fork">
<!ENTITY % paragraphs "p|source|note|warning|fixme">
<!ENTITY % tables "table">
<!ENTITY % lists "ol|ul|dl">
<!ENTITY % special-blocks "figure|anchor">
<!-- =============================================================== -->
<!-- Entities for general XML compliance -->
<!-- =============================================================== -->
<!-- Common attributes
Every element has an ID attribute (sometimes required,
but usually optional) for links. %common.att;
is for common attributes where the ID is optional, and
%common-idreq.att; is for common attributes where the
ID is required.
-->
<!ENTITY % common.att
'id ID #IMPLIED
xml:lang NMTOKEN #IMPLIED'>
<!ENTITY % common-idreq.att
'id ID #REQUIRED
xml:lang NMTOKEN #IMPLIED'>
<!-- xml:space attribute ===============================================
Indicates that the element contains white space
that the formatter or other application should retain,
as appropriate to its function.
==================================================================== -->
<!ENTITY % xmlspace.att
'xml:space (default|preserve) #FIXED "preserve"'>
<!-- def attribute =====================================================
Points to the element where the relevant definition can be
found, using the IDREF mechanism. %def.att; is for optional
def attributes, and %def-req.att; is for required def
attributes.
==================================================================== -->
<!ENTITY % def.att
'def IDREF #IMPLIED'>
<!ENTITY % def-req.att
'def IDREF #REQUIRED'>
<!-- ref attribute =====================================================
Points to the element where more information can be found,
using the IDREF mechanism. %ref.att; is for optional
ref attributes, and %ref-req.att; is for required ref
attributes.
================================================================== -->
<!ENTITY % ref.att
'ref IDREF #IMPLIED'>
<!ENTITY % ref-req.att
'ref IDREF #REQUIRED'>
<!-- =============================================================== -->
<!-- Entities for general usage -->
<!-- =============================================================== -->
<!-- Key attribute =====================================================
Optionally provides a sorting or indexing key, for cases when
the element content is inappropriate for this purpose.
==================================================================== -->
<!ENTITY % key.att
'key CDATA #IMPLIED'>
<!-- Title attributes ==================================================
Indicates that the element requires to have a title attribute.
==================================================================== -->
<!ENTITY % title.att
'title CDATA #REQUIRED'>
<!-- Name attributes ==================================================
Indicates that the element requires to have a name attribute.
==================================================================== -->
<!ENTITY % name.att
'name CDATA #REQUIRED'>
<!-- Email attributes ==================================================
Indicates that the element requires to have an email attribute.
==================================================================== -->
<!ENTITY % email.att
'email CDATA #REQUIRED'>
<!-- Link attributes ===================================================
Indicates that the element requires to have hyperlink attributes.
==================================================================== -->
<!ENTITY % link.att
'href CDATA #IMPLIED
role CDATA #IMPLIED
title CDATA #IMPLIED '>
<!-- =============================================================== -->
<!-- General definitions -->
<!-- =============================================================== -->
<!-- A person is a general human entity -->
<!ELEMENT person EMPTY>
<!ATTLIST person %common.att;
%name.att;
%email.att;>
<!-- =============================================================== -->
<!-- Content definitions -->
<!-- =============================================================== -->
<!ENTITY % local.inline "">
<!ENTITY % link-content.mix "%text;|%markup;|%special-inline; %local.inline;">
<!ENTITY % content.mix "%link-content.mix;|%links;">
<!-- ==================================================== -->
<!-- Phrase Markup -->
<!-- ==================================================== -->
<!-- Strong (typically bold) -->
<!ELEMENT strong (%text;|code)*>
<!ATTLIST strong %common.att;>
<!-- Emphasis (typically italic) -->
<!ELEMENT em (%text;|code)*>
<!ATTLIST em %common.att;>
<!-- Code (typically monospaced) -->
<!ELEMENT code (%text;)>
<!ATTLIST code %common.att;>
<!-- Superscript (typically smaller and higher) -->
<!ELEMENT sup (%text;)>
<!ATTLIST sup %common.att;>
<!-- Subscript (typically smaller and lower) -->
<!ELEMENT sub (%text;)>
<!ATTLIST sub %common.att;>
<!-- ==================================================== -->
<!-- Hypertextual Links -->
<!-- ==================================================== -->
<!-- hyperlink (equivalent of <a ...>) -->
<!ELEMENT link (%link-content.mix;)*>
<!ATTLIST link %common.att;
%link.att;>
<!-- windows-replacing link (equivalent of <a ... target="_top">) -->
<!ELEMENT jump (%link-content.mix;)*>
<!ATTLIST jump %common.att;
%link.att;>
<!-- window-forking link (equivalent of <a ... target="_new">) -->
<!ELEMENT fork (%link-content.mix;)*>
<!ATTLIST fork %common.att;
%link.att;>
<!-- ==================================================== -->
<!-- Specials -->
<!-- ==================================================== -->
<!-- Breakline Object (typically forces line break) -->
<!ELEMENT br EMPTY>
<!ATTLIST br %common.att;>
<!-- Image Object (typically an inlined image) -->
<!ELEMENT img EMPTY>
<!ATTLIST img src CDATA #REQUIRED
alt CDATA #REQUIRED
height CDATA #IMPLIED
width CDATA #IMPLIED
usemap CDATA #IMPLIED
ismap (ismap) #IMPLIED
%common.att;>
<!-- Image Icon (typically an inlined image placed as graphical item) -->
<!ELEMENT icon EMPTY>
<!ATTLIST icon src CDATA #REQUIRED
alt CDATA #REQUIRED
height CDATA #IMPLIED
width CDATA #IMPLIED
%common.att;>
<!-- =============================================================== -->
<!-- Blocks definitions -->
<!-- =============================================================== -->
<!ENTITY % local.blocks "">
<!ENTITY % blocks "%paragraphs;|%tables;|%lists;|%special-blocks; %local.blocks;">
<!-- ==================================================== -->
<!-- Paragraphs -->
<!-- ==================================================== -->
<!-- Text Paragraph (normally vertically space delimited) -->
<!ELEMENT p (%content.mix;)*>
<!ATTLIST p %common.att;>
<!-- Source Paragraph (normally space is preserved) -->
<!ELEMENT source (%content.mix;)*>
<!ATTLIST source %common.att;
%xmlspace.att;>
<!-- Note Paragraph (normally shown encapsulated) -->
<!ELEMENT note (%content.mix;)*>
<!ATTLIST note %common.att;>
<!-- Warning Paragraph (normally shown with eye-catching colors) -->
<!ELEMENT warning (%content.mix;)*>
<!ATTLIST warning %common.att;>
<!-- Fixme Paragraph (normally not shown) -->
<!ELEMENT fixme (%content.mix;)*>
<!ATTLIST fixme author CDATA #REQUIRED
%common.att;>
<!-- ==================================================== -->
<!-- Tables -->
<!-- ==================================================== -->
<!-- Attributes that indicate the spanning of the table cell -->
<!ENTITY % cell.span
'colspan CDATA "1"
rowspan CDATA "1"'>
<!-- Table element -->
<!ELEMENT table (caption?, tr+)>
<!ATTLIST table %common.att;>
<!-- The table title -->
<!ELEMENT caption (%content.mix;)*>
<!ATTLIST caption %common.att;>
<!-- The table row element -->
<!ELEMENT tr (th|td)+>
<!ATTLIST tr %common.att;>
<!-- The table row header element -->
<!ELEMENT th (%content.mix;)*>
<!ATTLIST th %common.att;
%cell.span;>
<!-- The table row description element -->
<!ELEMENT td (%content.mix;)*>
<!ATTLIST td %common.att;
%cell.span;>
<!-- ==================================================== -->
<!-- Lists -->
<!-- ==================================================== -->
<!-- List item -->
<!ELEMENT li (%content.mix;|%lists;)*>
<!ATTLIST li %common.att;>
<!-- Unordered list (typically bulleted) -->
<!ELEMENT ul (li|%lists;)+>
<!-- spacing attribute:
Use "normal" to get normal vertical spacing for items;
use "compact" to get less spacing. The default is dependent
on the stylesheet. -->
<!ATTLIST ul
%common.att;
spacing (normal|compact) #IMPLIED>
<!-- Ordered list (typically numbered) -->
<!ELEMENT ol (li|%lists;)+>
<!-- spacing attribute:
Use "normal" to get normal vertical spacing for items;
use "compact" to get less spacing. The default is dependent
on the stylesheet. -->
<!ATTLIST ol
%common.att;
spacing (normal|compact) #IMPLIED>
<!-- Definition list (typically two-column) -->
<!ELEMENT dl (dt,dd)+>
<!ATTLIST dl %common.att;>
<!-- Definition term -->
<!ELEMENT dt (%content.mix;)*>
<!ATTLIST dt %common.att;>
<!-- Definition description -->
<!ELEMENT dd (%content.mix;)*>
<!ATTLIST dd %common.att;>
<!-- ==================================================== -->
<!-- Special Blocks -->
<!-- ==================================================== -->
<!-- Image Block (typically a separated and centered image) -->
<!ELEMENT figure EMPTY>
<!ATTLIST figure src CDATA #REQUIRED
alt CDATA #REQUIRED
height CDATA #IMPLIED
width CDATA #IMPLIED
usemap CDATA #IMPLIED
ismap (ismap) #IMPLIED
%common.att;>
<!-- anchor point (equivalent of <a name="...">, typically not rendered) -->
<!ELEMENT anchor EMPTY>
<!ATTLIST anchor %common-idreq.att;>
<!-- =============================================================== -->
<!-- Document -->
<!-- =============================================================== -->
<!ELEMENT document (header?, body, footer?)>
<!ATTLIST document %common.att;>
<!-- ==================================================== -->
<!-- Header -->
<!-- ==================================================== -->
<!ENTITY % local.headers "">
<!ELEMENT header (title, subtitle?, version?, type?, authors,
notice*, abstract? %local.headers;)>
<!ATTLIST header %common.att;>
<!ELEMENT title (%text;)>
<!ATTLIST title %common.att;>
<!ELEMENT subtitle (%text;)>
<!ATTLIST subtitle %common.att;>
<!ELEMENT version (%text;)>
<!ATTLIST version %common.att;>
<!ELEMENT type (%text;)>
<!ATTLIST type %common.att;>
<!ELEMENT authors (person+)>
<!ATTLIST authors %common.att;>
<!ELEMENT notice (%content.mix;)*>
<!ATTLIST notice %common.att;>
<!ELEMENT abstract (%content.mix;)*>
<!ATTLIST abstract %common.att;>
<!-- ==================================================== -->
<!-- Body -->
<!-- ==================================================== -->
<!ENTITY % local.sections "">
<!ENTITY % sections "section %local.sections;">
<!ELEMENT body (%sections;|%blocks;)+>
<!ATTLIST body %common.att;>
<!ELEMENT section (%sections;|%blocks;)*>
<!ATTLIST section %title.att; %common.att;>
<!-- ==================================================== -->
<!-- Footer -->
<!-- ==================================================== -->
<!ENTITY % local.footers "">
<!ELEMENT footer (legal %local.footers;)>
<!ELEMENT legal (%content.mix;)*>
<!ATTLIST legal %common.att;>
<!-- =============================================================== -->
<!-- End of DTD -->
<!-- =============================================================== -->

145
src/documentation/content/xdocs/dtd/document-v13.dtd Normal file
View File

@ -0,0 +1,145 @@
<!--
Copyright 1999-2004 The Apache Software Foundation
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<!-- ===================================================================
Apache Documentation DTD (Version 1.2)
PURPOSE:
This DTD was developed to create a simple yet powerful document
type for software documentation for use with the Apache projects.
It is an XML-compliant DTD and it's maintained by the Apache XML
project.
TYPICAL INVOCATION:
<!DOCTYPE document PUBLIC
"-//APACHE//DTD Documentation Vx.y//EN"
"document-vxy.dtd">
where
x := major version
y := minor version
NOTES:
Many of the design patterns used in this DTD were take from the
W3C XML Specification DTD edited by Eve Maler <elm@arbortext.com>.
Where possible, great care has been used to reuse HTML tag
names to reduce learning efforts and to allow HTML editors to be
used for complex authorings like tables and lists.
EXTENSIBILITY:
This DTD includes several empty placeholders that can be used to
extend it. These placeholders are implemented with empty entities. Here
is the list of those empty entities and what they are used for:
- local.inline: this entity should contain extended definitions of
elements that can be used 'inline', or directly inside
the content. An example for this entity could be
<!ENTITY % local.inline "|citation">
- local.blocks: this entity should contain extended definitions of
elements that behave as 'blocks', thus can be visually
rendered as areas on the canvas. An example for this
entity could be:
<!ENTITY % local.blocks "|poem">
- local.sections: this entity should contain extended definitions of
elements that behave as 'sections', thus can be considered
containers of block-level elements. An example for
this entity could be:
<!ENTITY % local.sections "|chapter">
- local.headers: this entity should contain extended definitions of
elements that behave as parts of the document header.
An example for this header could be:
<!ENTITY % local.headers ", notes?">
- local.footers: this entity should contain extended definitions of
elements that behave as parts of the document footer.
An example for this header could be:
<!ENTITY % local.footers ", annotations*">
FIXME:
- should "form" tags be included?
CHANGE HISTORY:
[Version 1.0]
19991121 Initial version. (SM)
19991123 Replaced "res" with more standard "strong" for emphasis. (SM)
19991124 Added "fork" element for window forking behavior. (SM)
19991124 Added "img-inline" element to separate from "img". (SM)
19991129 Removed "affiliation" from "author". (SM)
19991129 Made "author" empty and moved "name|email" as attributes. (SM)
19991215 Simplified table section. (SM)
19991215 Changed "img-block" in more friendly "figure". (SM)
20000125 Added the "icon" image. (SM)
20000126 Allowed "anchor" in all levels. (SM)
20000404 Removed the "role" attribute from common-xxx.att. (SM)
20000815 Allowed "code" inside "strong" and "em". (SM)
[Version 1.1]
20011212 Used public identifiers for external entities. (SM)
20011212 Removed xlink attributes since not used. (SM)
20011212 Removed "connect" since not required at this level. (SM)
20011218 Added "warning" as a block level object. (SM)
20011218 Removed explicitly numbered sections ("s1|s2|s3|s4"). (SM)
20011218 Added "section" element. (SM)
20011218 Allowed "body" to have blocks without a section. (SM)
20011218 Removed "sl" since not really different from "ul". (SM)
20020214 Moved empty placeholder entity declarations up front (SNS)
20020214 Corrected content model of content.mix parameter entity (SNS)
20020519 The DTDs are now modular so various parts can be re-used (SNS)
20020606 Made title into an child element of its parent instead of an attribute (SNS)
20020613 Move the declarations of ISO character entity sets to module (DC)
[Version 1.2]
20030320 Make @href required for link elements. (SNS)
20030320 Allow links (link|jump|fork) and inline elements (br|img|icon|acronym) inside title. (SNS)
20030419 Allow inline content (strong|em|code|sub|sup|br|img|icon|acronym|link|jump|fork) in strong and em. (JT)
20030419 Allow paragraphs (p|source|note|warning|fixme), table and figure|anchor inside li. (JT)
20030419 Allow paragraphs (p|source|note|warning|fixme), lists (ol|ul|dl), table, figure|anchor inside dd. (JT)
20030419 Allow paragraphs (p|source|note|warning|fixme), lists (ol|ul|dl), table, figure|anchor inside tables (td|dh). (JT)
20040614 The attribute "class" is now defined on every element. (RT)
==================================================================== -->
<!-- =============================================================== -->
<!-- Include the Common ISO Character Entity Sets -->
<!-- =============================================================== -->
<!ENTITY % common-charents PUBLIC
"-//APACHE//ENTITIES Common Character Entity Sets V1.0//EN"
"common-charents-v10.mod">
%common-charents;
<!-- =============================================================== -->
<!-- Document -->
<!-- =============================================================== -->
<!ENTITY % document PUBLIC
"-//APACHE//ENTITIES Documentation V1.3//EN"
"document-v13.mod">
%document;
<!-- =============================================================== -->
<!-- End of DTD -->
<!-- =============================================================== -->

432
src/documentation/content/xdocs/dtd/document-v13.mod Normal file
View File

@ -0,0 +1,432 @@
<!--
Copyright 2002-2004 The Apache Software Foundation
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<!-- ===================================================================
Apache Common Documentation elements (Version 1.2)
PURPOSE:
This DTD was developed to create a simple yet powerful document
type for software documentation for use with the Apache projects.
TYPICAL INVOCATION:
<!ENTITY % document PUBLIC
"-//APACHE//ENTITIES Documentation Vxy//EN"
"document-vxy.mod">
%document;
where
x := major version
y := minor version
NOTES:
FIXME:
CHANGE HISTORY:
[Version 1.0]
20020608 Initial version. (SN)
==================================================================== -->
<!-- =============================================================== -->
<!-- Useful entities for increased DTD readability -->
<!-- =============================================================== -->
<!ENTITY % text "#PCDATA">
<!-- Entities referred to later on are defined up front -->
<!ENTITY % markup "strong|em|code|sub|sup">
<!ENTITY % special-inline "br|img|icon|acronym">
<!ENTITY % links "link|jump|fork">
<!ENTITY % paragraphs "p|source|note|warning|fixme">
<!ENTITY % tables "table">
<!ENTITY % lists "ol|ul|dl">
<!ENTITY % special-blocks "figure|anchor">
<!-- =============================================================== -->
<!-- Entities for general XML compliance -->
<!-- =============================================================== -->
<!-- Common attributes
Every element has an ID attribute (sometimes required,
but usually optional) for links. %common.att;
is for common attributes where the ID is optional, and
%common-idreq.att; is for common attributes where the
ID is required.
-->
<!ENTITY % common.att 'id ID #IMPLIED
class NMTOKEN #IMPLIED
xml:lang NMTOKEN #IMPLIED'>
<!ENTITY % common-idreq.att 'id ID #REQUIRED
class NMTOKEN #IMPLIED
xml:lang NMTOKEN #IMPLIED'>
<!-- xml:space attribute ===============================================
Indicates that the element contains white space
that the formatter or other application should retain,
as appropriate to its function.
==================================================================== -->
<!ENTITY % xmlspace.att 'xml:space (default|preserve) #FIXED "preserve"'>
<!-- def attribute =====================================================
Points to the element where the relevant definition can be
found, using the IDREF mechanism. %def.att; is for optional
def attributes, and %def-req.att; is for required def
attributes.
==================================================================== -->
<!ENTITY % def.att 'def IDREF #IMPLIED'>
<!ENTITY % def-req.att 'def IDREF #REQUIRED'>
<!-- ref attribute =====================================================
Points to the element where more information can be found,
using the IDREF mechanism. %ref.att; is for optional
ref attributes, and %ref-req.att; is for required ref
attributes.
================================================================== -->
<!ENTITY % ref.att 'ref IDREF #IMPLIED'>
<!ENTITY % ref-req.att 'ref IDREF #REQUIRED'>
<!-- =============================================================== -->
<!-- Entities for general usage -->
<!-- =============================================================== -->
<!-- Key attribute =====================================================
Optionally provides a sorting or indexing key, for cases when
the element content is inappropriate for this purpose.
==================================================================== -->
<!ENTITY % key.att 'key CDATA #IMPLIED'>
<!-- Title attributes ==================================================
Indicates that the element requires to have a title attribute.
==================================================================== -->
<!ENTITY % title.att 'title CDATA #REQUIRED'>
<!-- Name attributes ==================================================
Indicates that the element requires to have a name attribute.
==================================================================== -->
<!ENTITY % name.att 'name CDATA #REQUIRED'>
<!-- Email attributes ==================================================
Indicates that the element requires to have an email attribute.
==================================================================== -->
<!ENTITY % email.att 'email CDATA #REQUIRED'>
<!-- Link attributes ===================================================
Indicates that the element requires to have hyperlink attributes.
==================================================================== -->
<!ENTITY % link.att 'href CDATA #REQUIRED
role CDATA #IMPLIED
title CDATA #IMPLIED '>
<!-- =============================================================== -->
<!-- General definitions -->
<!-- =============================================================== -->
<!-- A person is a general unparsed human entity -->
<!ELEMENT person EMPTY>
<!ATTLIST person
%common.att;
%name.att;
%email.att;
>
<!-- =============================================================== -->
<!-- Content definitions -->
<!-- =============================================================== -->
<!ENTITY % local.inline "">
<!ENTITY % link-content.mix "%text;|%markup;|%special-inline; %local.inline;">
<!ENTITY % content.mix "%link-content.mix;|%links;">
<!-- ==================================================== -->
<!-- Phrase Markup -->
<!-- ==================================================== -->
<!-- Strong (typically bold) -->
<!ELEMENT strong (%content.mix;)*>
<!ATTLIST strong
%common.att;
>
<!-- Emphasis (typically italic) -->
<!ELEMENT em (%content.mix;)*>
<!ATTLIST em
%common.att;
>
<!-- Code (typically monospaced) -->
<!ELEMENT code (%text;)>
<!ATTLIST code
%common.att;
>
<!-- Superscript (typically smaller and higher) -->
<!ELEMENT sup (%text;)>
<!ATTLIST sup
%common.att;
>
<!-- Subscript (typically smaller and lower) -->
<!ELEMENT sub (%text;)>
<!ATTLIST sub
%common.att;
>
<!-- ==================================================== -->
<!-- Hypertextual Links -->
<!-- ==================================================== -->
<!-- hyperlink (equivalent of <a ...>) -->
<!ELEMENT link (%link-content.mix;)*>
<!ATTLIST link
%common.att;
%link.att;
>
<!-- windows-replacing link (equivalent of <a ... target="_top">) -->
<!ELEMENT jump (%link-content.mix;)*>
<!ATTLIST jump
%common.att;
%link.att;
>
<!-- window-forking link (equivalent of <a ... target="_blank">) -->
<!ELEMENT fork (%link-content.mix;)*>
<!ATTLIST fork
%common.att;
%link.att;
>
<!-- ==================================================== -->
<!-- Specials -->
<!-- ==================================================== -->
<!-- Breakline Object (typically forces line break) -->
<!ELEMENT br EMPTY>
<!ATTLIST br
%common.att;
>
<!-- Image Object (typically an inlined image) -->
<!ELEMENT img EMPTY>
<!ATTLIST img
src CDATA #REQUIRED
alt CDATA #REQUIRED
height CDATA #IMPLIED
width CDATA #IMPLIED
usemap CDATA #IMPLIED
ismap (ismap) #IMPLIED
%common.att;
>
<!-- Image Icon (typically an inlined image placed as graphical item) -->
<!ELEMENT icon EMPTY>
<!ATTLIST icon
src CDATA #REQUIRED
alt CDATA #REQUIRED
height CDATA #IMPLIED
width CDATA #IMPLIED
%common.att;
>
<!-- Acronym (in modern browsers, will have rollover text) -->
<!ELEMENT acronym (%text;)*>
<!ATTLIST acronym
title CDATA #REQUIRED
%common.att;
>
<!-- =============================================================== -->
<!-- Blocks definitions -->
<!-- =============================================================== -->
<!ENTITY % local.blocks "">
<!ENTITY % blocks "%paragraphs;|%tables;|%lists;|%special-blocks; %local.blocks;">
<!-- Flow mixes block and inline -->
<!ENTITY % flow "%content.mix;|%blocks;">
<!-- ==================================================== -->
<!-- Paragraphs -->
<!-- ==================================================== -->
<!-- Text Paragraph (normally vertically space delimited. Space can be preserved.) -->
<!ELEMENT p (%content.mix;)*>
<!ATTLIST p
%common.att;
xml:space (default|preserve) #IMPLIED
>
<!-- Source Paragraph (normally space is preserved) -->
<!ELEMENT source (%content.mix;)*>
<!ATTLIST source
%common.att;
%xmlspace.att;
>
<!-- Note Paragraph (normally shown encapsulated) -->
<!ELEMENT note (%content.mix;)*>
<!ATTLIST note
label CDATA #IMPLIED
%common.att;
>
<!-- Warning Paragraph (normally shown with eye-catching colors) -->
<!ELEMENT warning (%content.mix;)*>
<!ATTLIST warning
label CDATA #IMPLIED
%common.att;
>
<!-- Fixme Paragraph (normally not shown) -->
<!ELEMENT fixme (%content.mix;)*>
<!ATTLIST fixme
author CDATA #REQUIRED
%common.att;
>
<!-- ==================================================== -->
<!-- Tables -->
<!-- ==================================================== -->
<!-- Attributes that indicate the spanning of the table cell -->
<!ENTITY % cell.span 'colspan CDATA "1"
rowspan CDATA "1"'>
<!-- Table element -->
<!ELEMENT table (caption?, tr+)>
<!ATTLIST table
%common.att;
>
<!-- The table title -->
<!ELEMENT caption (%content.mix;)*>
<!ATTLIST caption
%common.att;
>
<!-- The table row element -->
<!ELEMENT tr (th | td)+>
<!ATTLIST tr
%common.att;
>
<!-- The table row header element -->
<!ELEMENT th (%flow;)*>
<!ATTLIST th
%common.att;
%cell.span;
>
<!-- The table row description element -->
<!ELEMENT td (%flow;)*>
<!ATTLIST td
%common.att;
%cell.span;
>
<!-- ==================================================== -->
<!-- Lists -->
<!-- ==================================================== -->
<!-- List item -->
<!ELEMENT li (%flow;)*>
<!ATTLIST li
%common.att;
>
<!-- Unordered list (typically bulleted) -->
<!ELEMENT ul (li | %lists;)+>
<!-- spacing attribute:
Use "normal" to get normal vertical spacing for items;
use "compact" to get less spacing. The default is dependent
on the stylesheet. -->
<!ATTLIST ul
%common.att;
spacing (normal | compact) #IMPLIED
>
<!-- Ordered list (typically numbered) -->
<!ELEMENT ol (li | %lists;)+>
<!-- spacing attribute:
Use "normal" to get normal vertical spacing for items;
use "compact" to get less spacing. The default is dependent
on the stylesheet. -->
<!ATTLIST ol
%common.att;
spacing (normal | compact) #IMPLIED
>
<!-- Definition list (typically two-column) -->
<!ELEMENT dl (dt, dd)+>
<!ATTLIST dl
%common.att;
>
<!-- Definition term -->
<!ELEMENT dt (%content.mix;)*>
<!ATTLIST dt
%common.att;
>
<!-- Definition description -->
<!ELEMENT dd (%flow; )*>
<!ATTLIST dd
%common.att;
>
<!-- ==================================================== -->
<!-- Special Blocks -->
<!-- ==================================================== -->
<!-- Image Block (typically a separated and centered image) -->
<!ELEMENT figure EMPTY>
<!ATTLIST figure
src CDATA #REQUIRED
alt CDATA #REQUIRED
height CDATA #IMPLIED
width CDATA #IMPLIED
usemap CDATA #IMPLIED
ismap (ismap) #IMPLIED
align CDATA #IMPLIED
%common.att;
>
<!-- anchor point (equivalent of <a name="...">, typically not rendered) -->
<!ELEMENT anchor EMPTY>
<!ATTLIST anchor
%common-idreq.att;
>
<!-- =============================================================== -->
<!-- Document -->
<!-- =============================================================== -->
<!ELEMENT document (header, body, footer?)>
<!ATTLIST document
%common.att;
>
<!-- ==================================================== -->
<!-- Header -->
<!-- ==================================================== -->
<!ENTITY % local.headers "">
<!ELEMENT header (title, subtitle?, version?, type?, authors?,
notice*, abstract? %local.headers;)>
<!ATTLIST header
%common.att;
>
<!ELEMENT title (%text; | %markup; | %links; | %special-inline;)*>
<!ATTLIST title
%common.att;
>
<!ELEMENT subtitle (%text; | %markup;)*>
<!ATTLIST subtitle
%common.att;
>
<!ELEMENT version (%text;)>
<!ATTLIST version
%common.att;
major CDATA #IMPLIED
minor CDATA #IMPLIED
fix CDATA #IMPLIED
tag CDATA #IMPLIED
>
<!ELEMENT type (%text;)>
<!ATTLIST type
%common.att;
>
<!ELEMENT authors (person+)>
<!ATTLIST authors
%common.att;
>
<!ELEMENT notice (%content.mix;)*>
<!ATTLIST notice
%common.att;
>
<!ELEMENT abstract (%content.mix;)*>
<!ATTLIST abstract
%common.att;
>
<!-- ==================================================== -->
<!-- Body -->
<!-- ==================================================== -->
<!ENTITY % local.sections "">
<!ENTITY % sections "section %local.sections;">
<!ELEMENT body (%sections; | %blocks;)+>
<!ATTLIST body
%common.att;
>
<!ELEMENT section (title, (%sections; | %blocks;)*)>
<!ATTLIST section
%common.att;
>
<!-- ==================================================== -->
<!-- Footer -->
<!-- ==================================================== -->
<!ENTITY % local.footers "">
<!ELEMENT footer (legal %local.footers;)>
<!ELEMENT legal (%content.mix;)*>
<!ATTLIST legal
%common.att;
>
<!-- =============================================================== -->
<!-- End of DTD -->
<!-- =============================================================== -->

76
src/documentation/content/xdocs/dtd/faq-v11.dtd Normal file
View File

@ -0,0 +1,76 @@
<!-- ===================================================================
Apache FAQ DTD (Version 1.1)
PURPOSE:
This DTD was developed to create a simple yet powerful document
type for software FAQ's for use with the Apache projects.
It is an XML-compliant DTD and it's maintained by the Apache XML
project.
TYPICAL INVOCATION:
<!DOCTYPE document PUBLIC
"-//APACHE//DTD FAQ Vx.y//EN"
"faq-vxy.dtd">
where
x := major version
y := minor version
NOTES:
FAQs represent a powerful knowledge base and a very good way of solving
common user problems reducing messages on mail lists and reducing the effort
required for software installation and usage. Thid DTD want to be a common
format for FAQ interchange to allow FAQ-O-Matic-type workgroup services to
be published in other formats as well as enhancing data interchange.
AUTHORS:
Stefano Mazzocchi <stefano@apache.org>
FIXME:
CHANGE HISTORY:
19991129 Initial version. (SM)
20011212 Used public identifiers for external entities (SM)
COPYRIGHT:
Copyright (c) @year@ The Apache Software Foundation.
Permission to copy in any form is granted provided this notice is
included in all copies. Permission to redistribute is granted
provided this file is distributed untouched in all its parts and
included files.
==================================================================== -->
<!-- =============================================================== -->
<!-- Include the Documentation DTD -->
<!-- =============================================================== -->
<!ENTITY % document PUBLIC
"-//APACHE//DTD Documentation V1.1//EN"
"document-v11.dtd">
%document;
<!-- =============================================================== -->
<!-- Document Type Definition -->
<!-- =============================================================== -->
<!ELEMENT faqs (authors?, faq)+>
<!ATTLIST faqs %common.att;
%title.att;>
<!ELEMENT faq (question, answer)>
<!ATTLIST faq %common.att;>
<!ELEMENT question (%content.mix;)*>
<!ATTLIST question %common.att;>
<!ELEMENT answer (%blocks;)*>
<!ATTLIST answer author IDREF #IMPLIED>
<!-- =============================================================== -->
<!-- End of DTD -->
<!-- =============================================================== -->

69
src/documentation/content/xdocs/dtd/faq-v12.mod Normal file
View File

@ -0,0 +1,69 @@
<!--
Copyright 2002-2004 The Apache Software Foundation
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<!-- ===================================================================
Apache Faq module (Version 1.1)
TYPICAL INVOCATION:
<!ENTITY % faq PUBLIC
"-//APACHE//ENTITIES FAQ Vxy//EN"
"faq-vxy.mod">
%faq;
where
x := major version
y := minor version
NOTES:
FIXME:
CHANGE HISTORY:
[Version 1.0]
20020608 Initial version. (SN)
[Version 1.2]
20030505 Allow mixed content in <answer>, to match <question> (JT)
==================================================================== -->
<!-- =============================================================== -->
<!-- Element declarations -->
<!-- =============================================================== -->
<!ELEMENT faqs (authors?, (faq|part)+)>
<!ATTLIST faqs %common.att;
%title.att;>
<!ELEMENT part (title, (faq | part)+) >
<!ATTLIST part %common.att;>
<!ELEMENT faq (question, answer)>
<!ATTLIST faq %common.att;>
<!ELEMENT question (%content.mix;|elaboration)*>
<!ATTLIST question %common.att;>
<!ELEMENT elaboration (%content.mix;)*>
<!ATTLIST elaboration %common.att;>
<!ELEMENT answer (%flow;)*>
<!ATTLIST answer author IDREF #IMPLIED>
<!-- =============================================================== -->
<!-- End of DTD -->
<!-- =============================================================== -->

86
src/documentation/content/xdocs/dtd/faq-v13.dtd Normal file
View File

@ -0,0 +1,86 @@
<!--
Copyright 1999-2004 The Apache Software Foundation
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<!-- ===================================================================
Apache FAQ DTD (Version 1.2)
PURPOSE:
This DTD was developed to create a simple yet powerful document
type for software FAQ's for use with the Apache projects.
It is an XML-compliant DTD and it's maintained by the Apache XML
project.
TYPICAL INVOCATION:
<!DOCTYPE faqs PUBLIC
"-//APACHE//DTD FAQ Vx.y//EN"
"faq-vxy.dtd">
where
x := major version
y := minor version
NOTES:
FAQs represent a powerful knowledge base and a very good way of solving
common user problems reducing messages on mail lists and reducing the effort
required for software installation and usage. Thid DTD want to be a common
format for FAQ interchange to allow FAQ-O-Matic-type workgroup services to
be published in other formats as well as enhancing data interchange.
FIXME:
CHANGE HISTORY:
19991129 Initial version. (SM)
20011212 Used public identifiers for external entities (SM)
20020418 Added an (optional) 'part' element to create sections in a faq (SN)
20020613 Include the module of ISO character entity sets (DC)
[Version 1.2]
20030424 Adopt the loosened content model from document-v12 (JT)
20040614 Stay current with latest document-v13 (class attribute)
==================================================================== -->
<!-- =============================================================== -->
<!-- Include the Documentation DTD -->
<!-- =============================================================== -->
<!ENTITY % document PUBLIC
"-//APACHE//ENTITIES Documentation V1.3//EN"
"document-v13.mod">
%document;
<!-- =============================================================== -->
<!-- Include the Common ISO Character Entity Sets -->
<!-- =============================================================== -->
<!ENTITY % common-charents PUBLIC
"-//APACHE//ENTITIES Common Character Entity Sets V1.0//EN"
"common-charents-v10.mod">
%common-charents;
<!-- =============================================================== -->
<!-- Document Type Definition -->
<!-- =============================================================== -->
<!ENTITY % faq PUBLIC
"-//APACHE//ENTITIES FAQ V1.1//EN"
"faq-v12.mod">
%faq;
<!-- =============================================================== -->
<!-- End of DTD -->
<!-- =============================================================== -->

254
src/documentation/content/xdocs/dtd/javadoc-v04draft.dtd Normal file
View File

@ -0,0 +1,254 @@
<!-- ===================================================================
Apache JavaDoc DTD (version 0.4-draft)
PURPOSE:
This DTD is designed to capture the output of JavaDoc as an XML document
through the use of the JavaDocXML Doclet. The hope is that by having the
JavaDoc documentation in an XML format, it will be easier for application
developers working with XML to treat their java source documentation in the
same way they treat any other XML document within their publication framework.
This DTD should reflect the information contained within the RootDoc object
passed to the JavaDocXML Doclet by JavaDoc. The RootDoc object and the rest
of the javaDoc Doclet API is specified at
http://java.sun.com/products/jdk/1.2/docs/tooldocs/javadoc/doclet/index.html
The only information that appears to be difficult to derive from this DTD
that is easy to obtain from the RootDoc object is the information about
serialization. However, this information should be derivable by manually
looking for the correct serialization methods and other related structures.
TYPICAL INVOCATION:
<!DOCTYPE document PUBLIC
"-//APACHE//DTD JavaDoc Vx.yz//EN"
"javadoc-vxyz.dtd">
where
x := major version
y := minor version
z := status identifier (optional)
NOTES:
The authors would like to thank the Cocoon's mail list subscribers for
providing such great support and feedback for this DTD.
AUTHORS:
Kenneth Murphy <murphyk@umsystem.edu>
FIXME:
CHANGE HISTORY:
199909?? Original idea of XML doclet. (KM)
199910?? Initial version of this DTD. (KM)
19991129 Cleaned up DTD. (SM)
COPYRIGHT:
Copyright (c) @year@ The Apache Software Foundation.
Permission to copy in any form is granted provided this notice is
included in all copies. Permission to redistribute is granted
provided this file is distributed untouched in all its parts and
included files.
==================================================================== -->
<!-- =============================================================== -->
<!-- Common Attribute Entities -->
<!-- =============================================================== -->
<!ENTITY % name 'name CDATA #REQUIRED'>
<!ENTITY % dimension 'dimension CDATA #REQUIRED'>
<!ENTITY % abstract 'abstract (true | false) "false"'>
<!ENTITY % anonymous 'anonymous (true | false) "false"'>
<!ENTITY % synthetic 'synthetic (true | false) "false"'>
<!ENTITY % static 'static (true | false) "false"'>
<!ENTITY % final 'final (true | false) "false"'>
<!ENTITY % transient 'transient (true | false) "false"'>
<!ENTITY % volatile 'volatile (true | false) "false"'>
<!ENTITY % native 'native (true | false) "false"'>
<!ENTITY % synchronized 'synchronized (true | false) "false"'>
<!ENTITY % access 'access (private | package | protected | public) "package"'>
<!ENTITY % class.access 'access (package | public) "package"'>
<!ENTITY % extensibility 'extensibility (abstract | final | default) "default"'>
<!-- =============================================================== -->
<!-- Javadoc -->
<!-- =============================================================== -->
<!ELEMENT javadoc (package*, class*, interface*)>
<!-- =============================================================== -->
<!-- Package -->
<!-- =============================================================== -->
<!ELEMENT package (doc?, package*, class*, interface*)>
<!ATTLIST package %name;>
<!-- =============================================================== -->
<!-- Class -->
<!-- =============================================================== -->
<!ELEMENT class (doc?,
extends_class?,
implements?,
field*,
constructor*,
method*,
innerclass*)>
<!ATTLIST class
%name;
%extensibility;
%class.access;>
<!ELEMENT extends_class (classref+)>
<!ELEMENT innerclass (doc?,
extends?,
implements?,
field*,
constructor*,
method*)>
<!ATTLIST innerclass
%name;
%access;
%abstract;
%anonymous;
%final;
%static;>
<!-- =============================================================== -->
<!-- Interface -->
<!-- =============================================================== -->
<!ELEMENT interface (doc?,
extends_interface?,
field*,
method*)>
<!ATTLIST interface
%name;
%access;>
<!ELEMENT extends_interface (interfaceref+)>
<!-- =============================================================== -->
<!-- Elements -->
<!-- =============================================================== -->
<!ELEMENT implements (interfaceref+)>
<!ELEMENT throws (classref)+>
<!ELEMENT classref EMPTY>
<!ATTLIST classref %name;>
<!ELEMENT interfaceref EMPTY>
<!ATTLIST interfaceref %name;>
<!ELEMENT methodref EMPTY>
<!ATTLIST methodref %name;>
<!ELEMENT packageref EMPTY>
<!ATTLIST packageref %name;>
<!ELEMENT primitive EMPTY>
<!ATTLIST primitive
type (void | boolean | int | long | byte | short | double | float | char) #REQUIRED>
<!ELEMENT field (doc?, (classref | interfaceref | primitive))>
<!ATTLIST field
%name;
%access;
%dimension;
%synthetic;
%static;
%final;
%transient;
%volatile;>
<!ELEMENT constructor (doc?, parameter*, throws*)>
<!ATTLIST constructor
%name;
%access;
%synthetic;>
<!ELEMENT method (doc?, returns, parameter*, throws*)>
<!ATTLIST method
%name;
%access;
%extensibility;
%native;
%synthetic;
%static;
%synchronized;>
<!ELEMENT returns (classref | interfaceref | primitive)>
<!ATTLIST returns %dimension;>
<!ELEMENT parameter (classref | interfaceref | primitive)>
<!ATTLIST parameter
%name;
%final;
%dimension;>
<!ELEMENT dimension (#PCDATA)>
<!ELEMENT doc (#PCDATA |
linktag |
authortag |
versiontag |
paramtag |
returntag |
exceptiontag |
throwstag |
seetag |
sincetag |
deprecatedtag |
serialtag |
serialfieldtag |
serialdatatag)*>
<!ELEMENT linktag (#PCDATA)>
<!ATTLIST linktag
src CDATA #REQUIRED>
<!ELEMENT authortag (#PCDATA | linktag)*>
<!ELEMENT versiontag (#PCDATA | linktag)*>
<!ELEMENT paramtag (#PCDATA | linktag)*>
<!ATTLIST paramtag %name;>
<!ELEMENT returntag (#PCDATA | linktag)*>
<!ELEMENT exceptiontag (#PCDATA | classref | linktag)*>
<!ELEMENT throwstag (#PCDATA | classref | linktag)*>
<!ELEMENT seetag (#PCDATA | linktag)*>
<!ATTLIST seetag
src CDATA #REQUIRED>
<!ELEMENT sincetag (#PCDATA | linktag)*>
<!ELEMENT deprecatedtag (#PCDATA | linktag)*>
<!ELEMENT serialtag (#PCDATA | linktag)*>
<!ELEMENT serialfieldtag (#PCDATA | linktag)*>
<!ATTLIST serialfieldtag
fieldname CDATA #REQUIRED
fieldtype CDATA #REQUIRED>
<!ELEMENT serialdatatag (#PCDATA | linktag)*>
<!-- =============================================================== -->
<!-- End of DTD -->
<!-- =============================================================== -->

92
src/documentation/content/xdocs/dtd/specification-v11.dtd Normal file
View File

@ -0,0 +1,92 @@
<!-- ===================================================================
Apache Specification DTD (Version 1.1)
PURPOSE:
This DTD was developed to create a simple yet powerful document
type for software specifications for use with the Apache projects.
It is an XML-compliant DTD and it's maintained by the Apache XML
project.
TYPICAL INVOCATION:
<!DOCTYPE document PUBLIC
"-//APACHE//DTD Specification Vx.y//EN"
"specification-vxy.dtd">
where
x := major version
y := minor version
NOTES:
AUTHORS:
Stefano Mazzocchi <stefano@apache.org>
FIXME:
CHANGE HISTORY:
[Version 1.0]
19991129 Initial version. (SM)
[Version 1.1]
20011212 Used public identifiers for external entities (SM)
COPYRIGHT:
Copyright (c) @year@ The Apache Software Foundation.
Permission to copy in any form is granted provided this notice is
included in all copies. Permission to redistribute is granted
provided this file is distributed untouched in all its parts and
included files.
==================================================================== -->
<!-- =============================================================== -->
<!-- Include the Documentation DTD -->
<!-- =============================================================== -->
<!ENTITY % document PUBLIC
"-//APACHE//DTD Documentation V1.1//EN"
"document-v11.dtd">
%document;
<!-- =============================================================== -->
<!-- Extend the Documentation DTD -->
<!-- =============================================================== -->
<!-- extend the local.xxx entities -->
<!ENTITY % local.blocks "|bl">
<!-- =============================================================== -->
<!-- Document Type Definition -->
<!-- =============================================================== -->
<!ELEMENT specification (header?, body, appendices?, footer?)>
<!ATTLIST specification %common.att;>
<!ELEMENT appendices (%sections;)+>
<!ATTLIST appendices %common.att;>
<!-- =============================================================== -->
<!-- Bibliography List -->
<!-- =============================================================== -->
<!-- Bibliography list -->
<!ELEMENT bl (bi)+>
<!ATTLIST bl %common.att;>
<!-- Book item -->
<!ELEMENT bi EMPTY>
<!ATTLIST bi %common.att;
%name.att;
%title.att;
%link.att;
authors CDATA #REQUIRED
date CDATA #IMPLIED>
<!-- =============================================================== -->
<!-- End of DTD -->
<!-- =============================================================== -->

96
src/documentation/content/xdocs/dtd/todo-v11.dtd Normal file
View File

@ -0,0 +1,96 @@
<!--
Copyright 1999-2004 The Apache Software Foundation
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<!-- ===================================================================
Apache Todos DTD (Version 1.1)
PURPOSE:
This DTD was developed to create a simple yet powerful document
type for software development todo lists for use with the Apache projects.
It is an XML-compliant DTD and it's maintained by the Apache XML
project.
TYPICAL INVOCATION:
<!DOCTYPE todo PUBLIC
"-//APACHE//DTD Todo Vx.y//EN"
"todo-vxy.dtd">
where
x := major version
y := minor version
NOTES:
It is important, expecially in open developped software projects, to keep
track of software changes that need to be done, planned features, development
assignment, etc. in order to allow better work parallelization and create
an entry point for people that want to help. This DTD wants to provide
a solid foundation to provide such information and to allow it to be
published as well as distributed in a common format.
FIXME:
- do we need anymore working contexts? (SM)
CHANGE HISTORY:
[Version 1.0]
19991129 Initial version. (SM)
19991225 Added actions element for better structure (SM)
[Version 1.1]
20011212 Used public identifiers for external entities (SM)
20020613 Include the module of ISO character entity sets (DC)
==================================================================== -->
<!-- =============================================================== -->
<!-- Include the Documentation DTD -->
<!-- =============================================================== -->
<!ENTITY % document PUBLIC
"-//APACHE//ENTITIES Documentation V1.1//EN"
"document-v11.mod">
%document;
<!-- =============================================================== -->
<!-- Include the Common ISO Character Entity Sets -->
<!-- =============================================================== -->
<!ENTITY % common-charents PUBLIC
"-//APACHE//ENTITIES Common Character Entity Sets V1.0//EN"
"common-charents-v10.mod">
%common-charents;
<!-- =============================================================== -->
<!-- Include the Common elements -->
<!-- =============================================================== -->
<!ENTITY % common PUBLIC
"-//APACHE//ENTITIES Common Elements V1.0//EN"
"common-elems-v10.mod">
%common;
<!-- =============================================================== -->
<!-- Include the Todo module -->
<!-- =============================================================== -->
<!ENTITY % todo PUBLIC
"-//APACHE//ENTITIES Todo V1.1//EN"
"todo-v11.mod">
%todo;
<!-- =============================================================== -->
<!-- End of DTD -->
<!-- =============================================================== -->

76
src/documentation/content/xdocs/dtd/todo-v11.mod Normal file
View File

@ -0,0 +1,76 @@
<!--
Copyright 1999-2004 The Apache Software Foundation
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<!-- ===================================================================
Apache Todos module (Version 1.0)
PURPOSE:
This DTD was developed to create a simple yet powerful document
type for software development todo lists for use with the Apache projects.
It is an XML-compliant DTD and it's maintained by the Apache XML
project.
TYPICAL INVOCATION:
<!ENTITY % todo PUBLIC
"-//APACHE//ENTITIES Todo Vxy//EN"
"todo-vxy.mod">
%todo;
where
x := major version
y := minor version
NOTES:
It is important, expecially in open developped software projects, to keep
track of software changes that need to be done, planned features, development
assignment, etc. in order to allow better work parallelization and create
an entry point for people that want to help. This DTD wants to provide
a solid foundation to provide such information and to allow it to be
published as well as distributed in a common format.
FIXME:
- do we need anymore working contexts? (SM)
CHANGE HISTORY:
[Version 1.0]
19991129 Initial version. (SM)
19991225 Added actions element for better structure (SM)
[Version 1.1]
20011212 Used public identifiers for external entities (SM)
==================================================================== -->
<!-- =============================================================== -->
<!-- Common entities -->
<!-- =============================================================== -->
<!ENTITY % priorities "showstopper|high|medium|low|wish|dream">
<!-- =============================================================== -->
<!-- Document Type Definition -->
<!-- =============================================================== -->
<!ELEMENT todo (title?, devs?, actions+)>
<!ATTLIST todo
%common.att;
>
<!ELEMENT actions (action+)>
<!ATTLIST actions
%common.att;
priority (%priorities;) #IMPLIED
>
<!-- =============================================================== -->
<!-- End of DTD -->
<!-- =============================================================== -->

99
src/documentation/content/xdocs/dtd/todo-v13.dtd Normal file
View File

@ -0,0 +1,99 @@
<!--
Copyright 1999-2004 The Apache Software Foundation
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<!-- ===================================================================
Apache Todos DTD (Version 1.2)
PURPOSE:
This DTD was developed to create a simple yet powerful document
type for software development todo lists for use with the Apache projects.
It is an XML-compliant DTD and it's maintained by the Apache XML
project.
TYPICAL INVOCATION:
<!DOCTYPE todo PUBLIC
"-//APACHE//DTD Todo Vx.y//EN"
"todo-vxy.dtd">
where
x := major version
y := minor version
NOTES:
It is important, expecially in open developped software projects, to keep
track of software changes that need to be done, planned features, development
assignment, etc. in order to allow better work parallelization and create
an entry point for people that want to help. This DTD wants to provide
a solid foundation to provide such information and to allow it to be
published as well as distributed in a common format.
FIXME:
- do we need anymore working contexts? (SM)
CHANGE HISTORY:
[Version 1.0]
19991129 Initial version. (SM)
19991225 Added actions element for better structure (SM)
[Version 1.1]
20011212 Used public identifiers for external entities (SM)
20020613 Include the module of ISO character entity sets (DC)
[Version 1.2]
20030424 Adopt the loosened content model from document-v12 (JT)
20040614 Stay current with latest document-v13 (class attribute)
==================================================================== -->
<!-- =============================================================== -->
<!-- Include the Documentation DTD -->
<!-- =============================================================== -->
<!ENTITY % document PUBLIC
"-//APACHE//ENTITIES Documentation V1.3//EN"
"document-v13.mod">
%document;
<!-- =============================================================== -->
<!-- Include the Common ISO Character Entity Sets -->
<!-- =============================================================== -->
<!ENTITY % common-charents PUBLIC
"-//APACHE//ENTITIES Common Character Entity Sets V1.0//EN"
"common-charents-v10.mod">
%common-charents;
<!-- =============================================================== -->
<!-- Include the Common elements -->
<!-- =============================================================== -->
<!ENTITY % common PUBLIC
"-//APACHE//ENTITIES Common Elements V1.0//EN"
"common-elems-v10.mod">
%common;
<!-- =============================================================== -->
<!-- Include the Todo module -->
<!-- =============================================================== -->
<!ENTITY % todo PUBLIC
"-//APACHE//ENTITIES Todo V1.1//EN"
"todo-v11.mod">
%todo;
<!-- =============================================================== -->
<!-- End of DTD -->
<!-- =============================================================== -->

112
src/documentation/content/xdocs/encryption.xml Normal file
View File

@ -0,0 +1,112 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
====================================================================
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
====================================================================
-->
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.3//EN" "./dtd/document-v13.dtd">
<document>
<header>
<title>Apache POI - Encryption support</title>
<authors>
<person id="maxcom" name="Maxim Valyanskiy" email="maxcom@apache.org"/>
</authors>
</header>
<body>
<section><title>Overview</title>
<p>Apache POI contains support for reading few variants of encrypted office files: </p>
<ul>
<li>XLS - RC4 Encryption</li>
<li>XML-based formats (XLSX, DOCX and etc) - AES and Agile Encryption</li>
</ul>
<p>Some "write-protected" files are encrypted with build-in password, POI can read that files too.</p>
</section>
<section><title>XLS</title>
<p>When HSSF receive encrypted file, it tries to decode it with MSOffice build-in password.
Use static method setCurrentUserPassword(String password) of org.apache.poi.hssf.record.crypto.Biff8EncryptionKey to
set password. It sets thread local variable. Do not forget to reset it to null after text extraction.
</p>
</section>
<section><title>XML-based formats - Decryption</title>
<p>XML-based formats are stored in OLE-package stream "EncryptedPackage". Use org.apache.poi.poifs.crypt.Decryptor
to decode file:</p>
<source>
EncryptionInfo info = new EncryptionInfo(filesystem);
Decryptor d = Decryptor.getInstance(info);
try {
if (!d.verifyPassword(password)) {
throw new RuntimeException("Unable to process: document is encrypted");
}
InputStream dataStream = d.getDataStream(filesystem);
// parse dataStream
} catch (GeneralSecurityException ex) {
throw new RuntimeException("Unable to process encrypted document", ex);
}
</source>
<p>If you want to read file encrypted with build-in password, use Decryptor.DEFAULT_PASSWORD.</p>
</section>
<section><title>XML-based formats - Encryption</title>
<p>Encrypting a file is similar to the above decryption process. Basically you'll need to choose between
<link href="http://msdn.microsoft.com/en-us/library/dd952186(v=office.12).aspx">standard and agile encryption</link>.
Apart of the CipherMode, the EncryptionInfo class provides further parameters to specify the cipher and
hashing algorithm to be used.</p>
<source>
POIFSFileSystem fs = new POIFSFileSystem();
EncryptionInfo info = new EncryptionInfo(fs, EncryptionMode.agile);
// EncryptionInfo info = new EncryptionInfo(fs, EncryptionMode.agile, CipherAlgorithm.aes192, HashAlgorithm.sha384, -1, -1, null);
Encryptor enc = info.getEncryptor();
enc.confirmPassword("foobaa");
OPCPackage opc = OPCPackage.open(new File("..."), PackageAccess.READ_WRITE);
OutputStream os = enc.getDataStream(fs);
opc.save(os);
opc.close();
FileOutputStream fos = new FileOutputStream("...");
fs.writeFilesystem(fos);
fos.close();
</source>
</section>
</body>
<footer>
<legal>
Copyright (c) @year@ The Apache Software Foundation. All rights reserved.
<br />
Apache POI, POI, Apache, the Apache feather logo, and the Apache
POI project logo are trademarks of The Apache Software Foundation.
</legal>
</footer>
</document>

34
src/documentation/content/xdocs/entity/ISOdia.pen Normal file
View File

@ -0,0 +1,34 @@
<!-- (C) International Organization for Standardization 1986
Permission to copy in any form is granted for use with
conforming SGML systems and applications as defined in
ISO 8879, provided this notice is included in all copies.
-->
<!-- Character entity set. Typical invocation:
<!ENTITY % ISOdia PUBLIC
"ISO 8879:1986//ENTITIES Diacritical Marks//EN//XML">
%ISOdia;
-->
<!-- This version of the entity set can be used with any SGML document
which uses ISO 10646 as its document character set.
This includes XML documents and ISO HTML documents.
This entity set uses hexadecimal numeric character references.
Creator: Rick Jelliffe, Allette Systems
Version: 1997-07-07
-->
<!ENTITY acute "&#180;" ><!--=acute accent-->
<!ENTITY breve "&#x2D8;" ><!--=breve-->
<!ENTITY caron "&#x2C7;" ><!--=caron-->
<!ENTITY cedil "&#184;" ><!--=cedilla-->
<!ENTITY circ "^" ><!--=circumflex accent-->
<!ENTITY dblac "&#x2DD;" ><!--=double acute accent-->
<!ENTITY die "&#168;" ><!--=dieresis-->
<!ENTITY dot "&#x2D9;" ><!--=dot above-->
<!ENTITY grave "`" ><!--=grave accent-->
<!ENTITY macr "&#175;" ><!--=macron-->
<!ENTITY ogon "&#x2DB;" ><!--=ogonek-->
<!ENTITY ring "&#x2DA;" ><!--=ring-->
<!ENTITY tilde "&#x2DC;" ><!--=tilde-->
<!ENTITY uml "&#168;" ><!--=umlaut mark-->

74
src/documentation/content/xdocs/entity/ISOgrk1.pen Normal file
View File

@ -0,0 +1,74 @@
<!-- (C) International Organization for Standardization 1986
Permission to copy in any form is granted for use with
conforming SGML systems and applications as defined in
ISO 8879, provided this notice is included in all copies.
Creator: version from ISO 8879:1986
Version: 0.21 1992-12-04
-->
<!-- Character entity set. Typical invocation:
<!ENTITY % ISOGRK1 PUBLIC
"ISO 9573-15:1993//ENTITIES Greek Letters//EN//XML">
%ISOGRK1;
-->
<!-- This version of the entity set can be used with any SGML document
which uses ISO 10646 as its document character set.
This includes XML documents and ISO HTML documents.
Creator: Rick Jelliffe, from HTMLlat1
Version: 1997-07-07
-->
<!ENTITY agr "&#945;" ><!--small alpha, Greek, U03B1 -->
<!ENTITY Agr "&#913;" ><!--capital Alpha, Greek, U0391 -->
<!ENTITY bgr "&#946;" ><!--small beta, Greek, U03B2 -->
<!ENTITY Bgr "&#914;" ><!--capital Beta, Greek, U0392 -->
<!ENTITY ggr "&#947;" ><!--small gamma, Greek, U03B3 -->
<!ENTITY Ggr "&#915;" ><!--capital Gamma, Greek, U0393 -->
<!ENTITY dgr "&#948;" ><!--small delta, Greek, U03B4 -->
<!ENTITY Dgr "&#916;" ><!--capital Delta, Greek, U0394 -->
<!ENTITY egr "&#949;" ><!--small epsilon, Greek, U03B5 -->
<!ENTITY Egr "&#917;" ><!--capital Epsilon, Greek, U0395 -->
<!ENTITY zgr "&#950;" ><!--small zeta, Greek, U03B6 -->
<!ENTITY Zgr "&#918;" ><!--capital Zeta, Greek, U0396 -->
<!ENTITY eegr "&#951;" ><!--small eta, Greek, U03B7 -->
<!ENTITY EEgr "&#919;" ><!--capital Eta, Greek, U0397 -->
<!ENTITY thgr "&#952;" ><!--small theta, Greek, U03B8 -->
<!ENTITY THgr "&#920;" ><!--capital Theta, Greek, U0398 -->
<!ENTITY igr "&#953;" ><!--small iota, Greek, U03B9 -->
<!ENTITY Igr "&#921;" ><!--capital Iota, Greek, U0399 -->
<!ENTITY kgr "&#954;" ><!--small kappa, Greek, U03BA -->
<!ENTITY Kgr "&#922;" ><!--capital Kappa, Greek, U039A -->
<!ENTITY lgr "&#955;" ><!--small lambda, Greek, U03BB -->
<!ENTITY Lgr "&#923;" ><!--capital Lambda, Greek, U039B -->
<!ENTITY mgr "&#956;" ><!--small mu, Greek, U03BC -->
<!ENTITY Mgr "&#924;" ><!--capital Mu, Greek, U039C -->
<!ENTITY ngr "&#957;" ><!--small nu, Greek, U03BD -->
<!ENTITY Ngr "&#925;" ><!--capital Nu, Greek, U039D -->
<!ENTITY xgr "&#958;" ><!--small xi, Greek, U03BE -->
<!ENTITY Xgr "&#926;" ><!--capital Xi, Greek, U039E -->
<!ENTITY ogr "&#959;" ><!--small omicron, Greek, U03BF -->
<!ENTITY Ogr "&#927;" ><!--capital Omicron, Greek, U039F -->
<!ENTITY pgr "&#960;" ><!--small pi, Greek, U03C0 -->
<!ENTITY Pgr "&#928;" ><!--capital Pi, Greek, U03A0 -->
<!ENTITY rgr "&#961;" ><!--small rho, Greek, U03C1 -->
<!ENTITY Rgr "&#929;" ><!--capital Rho, Greek, U03A1 -->
<!ENTITY sfgr "&#962;" ><!--final small sigma, Greek, U03C2 -->
<!ENTITY sgr "&#963;" ><!--small sigma, Greek, U03C3 -->
<!ENTITY Sgr "&#931;" ><!--capital Sigma, Greek, U03A3 -->
<!ENTITY tgr "&#964;" ><!--small tau, Greek, U03C4 -->
<!ENTITY Tgr "&#932;" ><!--capital Tau, Greek, U03A4 -->
<!ENTITY ugr "&#965;" ><!--small upsilon, Greek, U03C5 -->
<!ENTITY Ugr "&#933;" ><!--capital Upsilon, Greek, U03A5 -->
<!ENTITY phgr "&#966;" ><!--small phi, Greek, U03C6 -->
<!ENTITY PHgr "&#934;" ><!--capital Phi, Greek, U03A6 -->
<!ENTITY khgr "&#967;" ><!--small chi, Greek, U03C7 -->
<!ENTITY KHgr "&#935;" ><!--capital Chi, Greek, U03A7 -->
<!ENTITY psgr "&#968;" ><!--small psi, Greek, U03C8 -->
<!ENTITY PSgr "&#936;" ><!--capital Psi, Greek, U03A8 -->
<!ENTITY ohgr "&#969;" ><!--small omega, Greek, U03C9 -->
<!ENTITY OHgr "&#937;" ><!--capital Omega, Greek, U03A9 -->

79
src/documentation/content/xdocs/entity/ISOlat1.pen Normal file
View File

@ -0,0 +1,79 @@
<!-- (C) International Organization for Standardization 1986
Permission to copy in any form is granted for use with
conforming SGML systems and applications as defined in
ISO 8879, provided this notice is included in all copies.
-->
<!-- Character entity set. Typical invocation:
<!ENTITY % ISOlat1 PUBLIC
"ISO 8879:1986//ENTITIES Added Latin 1//EN//XML">
%ISOlat1;
-->
<!-- This version of the entity set can be used with any SGML document
which uses ISO 8859-1 or ISO 10646 as its document character
set. This includes XML documents and ISO HTML documents.
-->
<!ENTITY Agrave "&#192;" ><!-- capital A, grave accent -->
<!ENTITY Aacute "&#193;" ><!-- capital A, acute accent -->
<!ENTITY Acirc "&#194;" ><!-- capital A, circumflex accent -->
<!ENTITY Atilde "&#195;" ><!-- capital A, tilde -->
<!ENTITY Auml "&#196;" ><!-- capital A, dieresis or umlaut mark -->
<!ENTITY Aring "&#197;" ><!-- capital A, ring -->
<!ENTITY AElig "&#198;" ><!-- capital AE diphthong (ligature) -->
<!ENTITY Ccedil "&#199;" ><!-- capital C, cedilla -->
<!ENTITY Egrave "&#200;" ><!-- capital E, grave accent -->
<!ENTITY Eacute "&#201;" ><!-- capital E, acute accent -->
<!ENTITY Ecirc "&#202;" ><!-- capital E, circumflex accent -->
<!ENTITY Euml "&#203;" ><!-- capital E, dieresis or umlaut mark -->
<!ENTITY Igrave "&#204;" ><!-- capital I, grave accent -->
<!ENTITY Iacute "&#205;" ><!-- capital I, acute accent -->
<!ENTITY Icirc "&#206;" ><!-- capital I, circumflex accent -->
<!ENTITY Iuml "&#207;" ><!-- capital I, dieresis or umlaut mark -->
<!ENTITY ETH "&#208;" ><!-- capital Eth, Icelandic -->
<!ENTITY Ntilde "&#209;" ><!-- capital N, tilde -->
<!ENTITY Ograve "&#210;" ><!-- capital O, grave accent -->
<!ENTITY Oacute "&#211;" ><!-- capital O, acute accent -->
<!ENTITY Ocirc "&#212;" ><!-- capital O, circumflex accent -->
<!ENTITY Otilde "&#213;" ><!-- capital O, tilde -->
<!ENTITY Ouml "&#214;" ><!-- capital O, dieresis or umlaut mark -->
<!ENTITY Oslash "&#216;" ><!-- capital O, slash -->
<!ENTITY Ugrave "&#217;" ><!-- capital U, grave accent -->
<!ENTITY Uacute "&#218;" ><!-- capital U, acute accent -->
<!ENTITY Ucirc "&#219;" ><!-- capital U, circumflex accent -->
<!ENTITY Uuml "&#220;" ><!-- capital U, dieresis or umlaut mark -->
<!ENTITY Yacute "&#221;" ><!-- capital Y, acute accent -->
<!ENTITY THORN "&#222;" ><!-- capital THORN, Icelandic -->
<!ENTITY szlig "&#223;" ><!-- small sharp s, German (sz ligature) -->
<!ENTITY agrave "&#224;" ><!-- small a, grave accent -->
<!ENTITY aacute "&#225;" ><!-- small a, acute accent -->
<!ENTITY acirc "&#226;" ><!-- small a, circumflex accent -->
<!ENTITY atilde "&#227;" ><!-- small a, tilde -->
<!ENTITY auml "&#228;" ><!-- small a, dieresis or umlaut mark -->
<!ENTITY aring "&#229;" ><!-- small a, ring -->
<!ENTITY aelig "&#230;" ><!-- small ae diphthong (ligature) -->
<!ENTITY ccedil "&#231;" ><!-- small c, cedilla -->
<!ENTITY egrave "&#232;" ><!-- small e, grave accent -->
<!ENTITY eacute "&#233;" ><!-- small e, acute accent -->
<!ENTITY ecirc "&#234;" ><!-- small e, circumflex accent -->
<!ENTITY euml "&#235;" ><!-- small e, dieresis or umlaut mark -->
<!ENTITY igrave "&#236;" ><!-- small i, grave accent -->
<!ENTITY iacute "&#237;" ><!-- small i, acute accent -->
<!ENTITY icirc "&#238;" ><!-- small i, circumflex accent -->
<!ENTITY iuml "&#239;" ><!-- small i, dieresis or umlaut mark -->
<!ENTITY eth "&#240;" ><!-- small eth, Icelandic -->
<!ENTITY ntilde "&#241;" ><!-- small n, tilde -->
<!ENTITY ograve "&#242;" ><!-- small o, grave accent -->
<!ENTITY oacute "&#243;" ><!-- small o, acute accent -->
<!ENTITY ocirc "&#244;" ><!-- small o, circumflex accent -->
<!ENTITY otilde "&#245;" ><!-- small o, tilde -->
<!ENTITY ouml "&#246;" ><!-- small o, dieresis or umlaut mark -->
<!ENTITY oslash "&#248;" ><!-- small o, slash -->
<!ENTITY ugrave "&#249;" ><!-- small u, grave accent -->
<!ENTITY uacute "&#250;" ><!-- small u, acute accent -->
<!ENTITY ucirc "&#251;" ><!-- small u, circumflex accent -->
<!ENTITY uuml "&#252;" ><!-- small u, dieresis or umlaut mark -->
<!ENTITY yacute "&#253;" ><!-- small y, acute accent -->
<!ENTITY thorn "&#254;" ><!-- small thorn, Icelandic -->
<!ENTITY yuml "&#255;" ><!-- small y, dieresis or umlaut mark -->

109
src/documentation/content/xdocs/entity/ISOnum.pen Normal file
View File

@ -0,0 +1,109 @@
<!-- (C) International Organization for Standardization 1986
Permission to copy in any form is granted for use with
conforming SGML systems and applications as defined in
ISO 8879, provided this notice is included in all copies.
-->
<!-- Character entity set. Typical invocation:
<!ENTITY % ISOnum PUBLIC
"ISO 8879:1986//ENTITIES Numeric and Special Graphic//EN//XML">
%ISOnum;
-->
<!-- This version of the entity set can be used with any SGML document
which uses ISO 10646 as its document character set.
This includes XML documents and ISO HTML documents.
This entity set uses hexadecimal numeric character references.
Creator: Rick Jelliffe, Allette Systems
Version: 1997-07-07
-->
<!ENTITY half "&#189;" ><!--=fraction one-half-->
<!ENTITY frac12 "&#189;" ><!--=fraction one-half-->
<!ENTITY frac14 "&#188;" ><!--=fraction one-quarter-->
<!ENTITY frac34 "&#190;" ><!--=fraction three-quarters-->
<!ENTITY frac18 "&#x215B;" >
<!-- or "&#xB1;&#x202;&#x2044;&#x2088;" --><!--=fraction one-eighth-->
<!ENTITY frac38 "&#x215C;" >
<!-- or "&#xB3;&#x2044;&#x2088;" --><!--=fraction three-eighths-->
<!ENTITY frac58 "&#x215D;" >
<!-- or "&#x2075;&#x2044;&#x2088;" --><!--=fraction five-eighths-->
<!ENTITY frac78 "&#x215E;" >
<!-- or "&#x2077;&#x2044;&#x2088;" --><!--=fraction seven-eighths-->
<!ENTITY sup1 "&#185;" ><!--=superscript one-->
<!ENTITY sup2 "&#178;" ><!--=superscript two-->
<!ENTITY sup3 "&#179;" ><!--=superscript three-->
<!ENTITY plus "+" ><!--=plus sign B:-->
<!ENTITY plusmn "&#xB1;" ><!--/pm B: =plus-or-minus sign-->
<!ENTITY lt "&#38;#60;" ><!--=less-than sign R:-->
<!ENTITY equals "=" ><!--=equals sign R:-->
<!ENTITY gt ">" ><!--=greater-than sign R:-->
<!ENTITY divide "&#247;" ><!--/div B: =divide sign-->
<!ENTITY times "&#215;" ><!--/times B: =multiply sign-->
<!ENTITY curren "&#164;" ><!--=general currency sign-->
<!ENTITY pound "&#163;" ><!--=pound sign-->
<!ENTITY dollar "$" ><!--=dollar sign-->
<!ENTITY cent "&#162;" ><!--=cent sign-->
<!ENTITY yen "&#165;" ><!--/yen =yen sign-->
<!ENTITY num "#" ><!--=number sign-->
<!ENTITY percnt "&#37;" ><!--=percent sign-->
<!ENTITY amp "&#38;#38;" ><!--=ampersand-->
<!ENTITY ast "*" ><!--/ast B: =asterisk-->
<!ENTITY commat "@" ><!--=commercial at-->
<!ENTITY lsqb "[" ><!--/lbrack O: =left square bracket-->
<!ENTITY bsol "\" ><!--/backslash =reverse solidus-->
<!ENTITY rsqb "]" ><!--/rbrack C: =right square bracket-->
<!ENTITY lcub "{" ><!--/lbrace O: =left curly bracket-->
<!ENTITY horbar "&#x2015;" ><!--=horizontal bar-->
<!ENTITY verbar "|" ><!--/vert =vertical bar-->
<!ENTITY rcub "}" ><!--/rbrace C: =right curly bracket-->
<!ENTITY micro "&#181;" ><!--=micro sign-->
<!ENTITY ohm "&#2126;" ><!--=ohm sign-->
<!ENTITY deg "&#176;" ><!--=degree sign-->
<!ENTITY ordm "&#186;" ><!--=ordinal indicator, masculine-->
<!ENTITY ordf "&#170;" ><!--=ordinal indicator, feminine-->
<!ENTITY sect "&#167;" ><!--=section sign-->
<!ENTITY para "&#182;" ><!--=pilcrow (paragraph sign)-->
<!ENTITY middot "&#183;" ><!--/centerdot B: =middle dot-->
<!ENTITY larr "&#x2190;" ><!--/leftarrow /gets A: =leftward arrow-->
<!ENTITY rarr "&#x2192;" ><!--/rightarrow /to A: =rightward arrow-->
<!ENTITY uarr "&#x2191;" ><!--/uparrow A: =upward arrow-->
<!ENTITY darr "&#x2193;" ><!--/downarrow A: =downward arrow-->
<!ENTITY copy "&#169;" ><!--=copyright sign-->
<!ENTITY reg "&#174;" ><!--/circledR =registered sign-->
<!ENTITY trade "&#8482;" ><!--=trade mark sign-->
<!ENTITY brvbar "&#xA6;" ><!--=bren (vertical) bar-->
<!ENTITY not "&#xAC;" ><!--/neg /lnot =not sign-->
<!ENTITY sung "&#x266A;" ><!--=music note (sung text sign)-->
<!ENTITY excl "!" ><!--=exclamation mark-->
<!ENTITY iexcl "&#xA1;" ><!--=inverted exclamation mark-->
<!ENTITY quot '"' ><!--=quotation mark-->
<!ENTITY apos "'" ><!--=apostrophe-->
<!ENTITY lpar "(" ><!--O: =left parenthesis-->
<!ENTITY rpar ")" ><!--C: =right parenthesis-->
<!ENTITY comma "," ><!--P: =comma-->
<!ENTITY lowbar "_" ><!--=low line-->
<!ENTITY hyphen "&#x2010;" ><!--=hyphen-->
<!ENTITY period "." ><!--=full stop, period-->
<!ENTITY sol "/" ><!--=solidus-->
<!ENTITY colon ":" ><!--/colon P:-->
<!ENTITY semi ";" ><!--=semicolon P:-->
<!ENTITY quest "?" ><!--=question mark-->
<!ENTITY iquest "&#xBF;" ><!--=inverted question mark-->
<!ENTITY laquo "&#x2039;" ><!--=angle quotation mark, left
But note that Unicode 1 & Maler & el Andaloussi give &#xAB; -->
<!ENTITY raquo "&#x203A;" ><!--=angle quotation mark, right
But note that Unicode 1 & Maler & el Andaloussi give &#xBB; -->
<!ENTITY lsquo "&#x2018;" ><!--=single quotation mark, left-->
<!ENTITY rsquo "&#x2019;" ><!--=single quotation mark, right-->
<!ENTITY ldquo "&#x201C;" ><!--=double quotation mark, left-->
<!ENTITY rdquo "&#x201D;" ><!--=double quotation mark, right-->
<!ENTITY nbsp "&#160;" ><!--=no break (required) space-->
<!ENTITY shy "&#173;" ><!--=soft hyphen-->

110
src/documentation/content/xdocs/entity/ISOpub.pen Normal file
View File

@ -0,0 +1,110 @@
<!-- (C) International Organization for Standardization 1986
Permission to copy in any form is granted for use with
conforming SGML systems and applications as defined in
ISO 8879, provided this notice is included in all copies.
-->
<!-- Character entity set. Typical invocation:
<!ENTITY % ISOpub PUBLIC
"ISO 8879:1986//ENTITIES Publishing//EN//XML">
%ISOpub;
-->
<!-- This version of the entity set can be used with any SGML document
which uses ISO 10646 as its document character set.
This includes XML documents and ISO HTML documents.
This entity set uses hexadecimal numeric character references.
Creator: Rick Jelliffe, Allette Systems
Version: 1997-07-07
-->
<!ENTITY emsp "&#x2003;" ><!--=em space-->
<!ENTITY ensp "&#x2002;" ><!--=en space (1/2-em)-->
<!ENTITY emsp13 "&#x2004;" ><!--=1/3-em space-->
<!ENTITY emsp14 "&#x2005;" ><!--=1/4-em space-->
<!ENTITY numsp "&#x2007;" ><!--=digit space (width of a number)-->
<!ENTITY puncsp "&#x2008;" ><!--=punctuation space (width of comma)-->
<!ENTITY thinsp "&#x2009;" ><!--=thin space (1/6-em)-->
<!ENTITY hairsp "&#x200A;" ><!--=hair space-->
<!ENTITY mdash "&#x2014;" ><!--=em dash-->
<!ENTITY ndash "&#x2013;" ><!--=en dash-->
<!ENTITY dash "&#x2010;" ><!--=hyphen (true graphic)-->
<!ENTITY blank "&#x2423;" ><!--=significant blank symbol-->
<!ENTITY hellip "&#x2026;" ><!--=ellipsis (horizontal)-->
<!ENTITY nldr "&#x2025;" ><!--=double baseline dot (en leader)-->
<!ENTITY frac13 "&#x2153;" ><!--=fraction one-third-->
<!ENTITY frac23 "&#x2154;" ><!--=fraction two-thirds-->
<!ENTITY frac15 "&#x2155;" ><!--=fraction one-fifth-->
<!ENTITY frac25 "&#x2156;" ><!--=fraction two-fifths-->
<!ENTITY frac35 "&#x2157;" ><!--=fraction three-fifths-->
<!ENTITY frac45 "&#x2158;" ><!--=fraction four-fifths-->
<!ENTITY frac16 "&#x2159;" ><!--=fraction one-sixth-->
<!ENTITY frac56 "&#x215a;" ><!--=fraction five-sixths-->
<!ENTITY incare "&#x2105;" ><!--=in-care-of symbol-->
<!ENTITY block "&#x2588;" ><!--=full block-->
<!ENTITY uhblk "&#x2580;" ><!--=upper half block-->
<!ENTITY lhblk "&#x2584;" ><!--=lower half block-->
<!ENTITY blk14 "&#x2591;" ><!--=25% shaded block-->
<!ENTITY blk12 "&#x2592;" ><!--=50% shaded block-->
<!ENTITY blk34 "&#x2593;" ><!--=75% shaded block-->
<!ENTITY marker "&#x25AE;" ><!--=histogram marker-->
<!ENTITY cir "&#x25CB;" ><!--/circ B: =circle, open-->
<!ENTITY squ "&#x25A1;" ><!--=square, open-->
<!ENTITY rect "&#x25AD;" ><!--=rectangle, open-->
<!ENTITY utri "&#x25B5;" ><!--/triangle =up triangle, open-->
<!ENTITY dtri "&#x25BF;" ><!--/triangledown =down triangle, open-->
<!ENTITY star "&#x2606;" ><!--=star, open-->
<!ENTITY bull "&#x2022;" ><!--/bullet B: =round bullet, filled-->
<!ENTITY squf "&#x25AA;" ><!--/blacksquare =sq bullet, filled-->
<!ENTITY utrif "&#x25B4;" ><!--/blacktriangle =up tri, filled-->
<!ENTITY dtrif "&#x25BE;" ><!--/blacktriangledown =dn tri, filled-->
<!ENTITY ltrif "&#x25C2;" ><!--/blacktriangleleft R: =l tri, filled-->
<!ENTITY rtrif "&#x25B8;" ><!--/blacktriangleright R: =r tri, filled-->
<!ENTITY clubs "&#x2663;" ><!--/clubsuit =club suit symbol-->
<!ENTITY diams "&#x2662;" ><!--/diamondsuit =diamond suit symbol-->
<!ENTITY hearts "&#x2661;" ><!--/heartsuit =heart suit symbol-->
<!ENTITY spades "&#x2660;" ><!--/spadesuit =spades suit symbol-->
<!ENTITY malt "&#x2720;" ><!--/maltese =maltese cross-->
<!ENTITY dagger "&#x2020;" ><!--/dagger B: =dagger-->
<!ENTITY Dagger "&#x2021;" ><!--/ddagger B: =double dagger-->
<!ENTITY check "&#x2713;" ><!--/checkmark =tick, check mark-->
<!ENTITY cross "&#x2717;" ><!--=ballot cross-->
<!ENTITY sharp "&#x266F;" ><!--/sharp =musical sharp-->
<!ENTITY flat "&#x266D;" ><!--/flat =musical flat-->
<!ENTITY male "&#x2642;" ><!--=male symbol-->
<!ENTITY female "&#x2640;" ><!--=female symbol-->
<!ENTITY phone "&#x26E0;" ><!--=telephone symbol-->
<!ENTITY telrec "&#x2315;" ><!--=telephone recorder symbol-->
<!ENTITY copysr "&#x2117;" ><!--=sound recording copyright sign-->
<!ENTITY caret "&#x2041;" ><!--=caret (insertion mark)-->
<!ENTITY lsquor "&#x201A;" ><!--=rising single quote, left (low)-->
<!ENTITY ldquor "&#x201E;" ><!--=rising dbl quote, left (low)-->
<!ENTITY fflig "&#xFB00;" ><!--small ff ligature-->
<!ENTITY filig "&#xFB01;" ><!--small fi ligature-->
<!ENTITY fjlig "fj" ><!--small fj ligature-->
<!ENTITY ffilig "&#xFB03;" ><!--small ffi ligature-->
<!ENTITY ffllig "&#xFB04;" ><!--small ffl ligature-->
<!ENTITY fllig "&#xFB02;" ><!--small fl ligature-->
<!ENTITY mldr "&#x2025;" ><!--em leader-->
<!ENTITY rdquor "&#x201D;" ><!--rising dbl quote, right (high)-->
<!ENTITY rsquor "&#x2019;" ><!--rising single quote, right (high)-->
<!ENTITY vellip "&#x22EE;" ><!--vertical ellipsis-->
<!ENTITY hybull "&#x2043;" ><!--rectangle, filled (hyphen bullet)-->
<!ENTITY loz "&#x2727;" ><!--/lozenge - lozenge or total mark-->
<!ENTITY lozf "&#x2726;" ><!--/blacklozenge - lozenge, filled-->
<!ENTITY ltri "&#x25C3;" ><!--/triangleleft B: l triangle, open-->
<!ENTITY rtri "&#x25B9;" ><!--/triangleright B: r triangle, open-->
<!ENTITY starf "&#x2605;" ><!--/bigstar - star, filled-->
<!ENTITY natur "&#x266E;" ><!--/natural - music natural-->
<!ENTITY rx "&#x211E;" ><!--pharmaceutical prescription (Rx)-->
<!ENTITY sext "&#x2736;" ><!--sextile (6-pointed star)-->
<!ENTITY target "&#x2316;" ><!--register mark or target-->
<!ENTITY dlcrop "&#x230D;" ><!--downward left crop mark -->
<!ENTITY drcrop "&#x230C;" ><!--downward right crop mark -->
<!ENTITY ulcrop "&#x230F;" ><!--upward left crop mark -->
<!ENTITY urcrop "&#x230E;" ><!--upward right crop mark -->

85
src/documentation/content/xdocs/entity/ISOtech.pen Normal file
View File

@ -0,0 +1,85 @@
<!-- (C) International Organization for Standardization 1986
Permission to copy in any form is granted for use with
conforming SGML systems and applications as defined in
ISO 8879, provided this notice is included in all copies.
-->
<!-- Character entity set. Typical invocation:
<!ENTITY % ISOtech PUBLIC
"ISO 8879:1986//ENTITIES General Technical//EN//XML"
"ISOtech.pen">
%ISOtech;
-->
<!-- This version of the entity set can be used with any SGML document
which uses ISO 10646 as its document character set.
This includes XML documents and ISO HTML documents.
This entity set uses hexadecimal numeric character references.
Creator: Rick Jelliffe, Allette Systems
Version: 1997-07-07
-->
<!ENTITY aleph "&#x2135;" ><!--/aleph =aleph, Hebrew-->
<!ENTITY and "&#x2227;" ><!--/wedge /land B: =logical and-->
<!ENTITY ang90 "&#x221F;" ><!--=right (90 degree) angle-->
<!ENTITY angsph "&#x2222;" ><!--/sphericalangle =angle-spherical-->
<!ENTITY ap "&#x2249;" ><!--/approx R: =approximate-->
<!ENTITY becaus "&#x2235;" ><!--/because R: =because-->
<!ENTITY bottom "&#x22A5;" ><!--/bot B: =perpendicular-->
<!ENTITY cap "&#x2229;" ><!--/cap B: =intersection-->
<!ENTITY cong "&#x2245;" ><!--/cong R: =congruent with-->
<!ENTITY conint "&#x222E;" ><!--/oint L: =contour integral operator-->
<!ENTITY cup "&#x222A;" ><!--/cup B: =union or logical sum-->
<!ENTITY equiv "&#x2261;" ><!--/equiv R: =identical with-->
<!ENTITY exist "&#x2203;" ><!--/exists =at least one exists-->
<!ENTITY forall "&#x2200;" ><!--/forall =for all-->
<!ENTITY fnof "&#x192;" ><!--=function of (italic small f)-->
<!ENTITY ge "&#x2265;" ><!--/geq /ge R: =greater-than-or-equal-->
<!ENTITY iff "&#x21D4;" ><!--/iff =if and only if-->
<!ENTITY infin "&#x221E;" ><!--/infty =infinity-->
<!ENTITY int "&#x222B;" ><!--/int L: =integral operator-->
<!ENTITY isin "&#x2208;" ><!--/in R: =set membership-->
<!ENTITY lang "&#x2329;" ><!--/langle O: =left angle bracket-->
<!ENTITY lArr "&#x21D0;" ><!--/Leftarrow A: =is implied by-->
<!ENTITY le "&#x2264;" ><!--/leq /le R: =less-than-or-equal-->
<!ENTITY minus "-" ><!--B: =minus sign-->
<!ENTITY mnplus "&#x2213;" ><!--/mp B: =minus-or-plus sign-->
<!ENTITY nabla "&#x2207;" ><!--/nabla =del, Hamilton operator-->
<!ENTITY ne "&#x2260;" ><!--/ne /neq R: =not equal-->
<!ENTITY ni "&#x220B;" ><!--/ni /owns R: =contains-->
<!ENTITY or "&#x2228;" ><!--/vee /lor B: =logical or-->
<!ENTITY par "&#x2225;" ><!--/parallel R: =parallel-->
<!ENTITY part "&#x2202;" ><!--/partial =partial differential-->
<!ENTITY permil "&#x2030;" ><!--=per thousand-->
<!ENTITY perp "&#x22A5;" ><!--/perp R: =perpendicular-->
<!ENTITY prime "&#x2032;" ><!--/prime =prime or minute-->
<!ENTITY Prime "&#x2033;" ><!--=double prime or second-->
<!ENTITY prop "&#x221D;" ><!--/propto R: =is proportional to-->
<!ENTITY radic "&#x221A;" ><!--/surd =radical-->
<!ENTITY rang "&#x232A;" ><!--/rangle C: =right angle bracket-->
<!ENTITY rArr "&#x21D2;" ><!--/Rightarrow A: =implies-->
<!ENTITY sim "&#x223C;" ><!--/sim R: =similar-->
<!ENTITY sime "&#x2243;" ><!--/simeq R: =similar, equals-->
<!ENTITY square "&#x25A1;" ><!--/square B: =square-->
<!ENTITY sub "&#x2282;" ><!--/subset R: =subset or is implied by-->
<!ENTITY sube "&#x2286;" ><!--/subseteq R: =subset, equals-->
<!ENTITY sup "&#x2283;" ><!--/supset R: =superset or implies-->
<!ENTITY supe "&#x2287;" ><!--/supseteq R: =superset, equals-->
<!ENTITY there4 "&#x2234;" ><!--/therefore R: =therefore-->
<!ENTITY Verbar "&#x2016;" ><!--/Vert =dbl vertical bar-->
<!ENTITY angst "&#x212B;" ><!--Angstrom =capital A, ring-->
<!ENTITY bernou "&#x212C;" ><!--Bernoulli function (script capital B)-->
<!ENTITY compfn "&#x2218;" ><!--B: composite function (small circle)-->
<!ENTITY Dot "&#xA8;" ><!--=dieresis or umlaut mark-->
<!ENTITY DotDot "&#x20DC;" ><!--four dots above-->
<!ENTITY hamilt "&#x210B;" ><!--Hamiltonian (script capital H)-->
<!ENTITY lagran "&#x2112;" ><!--Lagrangian (script capital L)-->
<!ENTITY lowast "&#x2217;" ><!--low asterisk-->
<!ENTITY notin "&#x2209;" ><!--N: negated set membership-->
<!ENTITY order "&#x2134;" ><!--order of (script small o)-->
<!ENTITY phmmat "&#x2133;" ><!--physics M-matrix (script capital M)-->
<!ENTITY tdot "&#x20DB;" ><!--three dots above-->
<!ENTITY tprime "&#x2034;" ><!--triple prime-->
<!ENTITY wedgeq "&#x2259;" ><!--R: corresponds to (wedge, equals)-->

393
src/documentation/content/xdocs/faq.xml Normal file
View File

@ -0,0 +1,393 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
====================================================================
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
====================================================================
-->
<!DOCTYPE faqs PUBLIC "-//APACHE//DTD FAQ V1.1//EN" "./dtd/faq-v11.dtd">
<faqs title="Frequently Asked Questions">
<faq>
<question>
My code uses some new feature, compiles fine but fails when live with a "MethodNotFoundException" or "IncompatibleClassChangeError"
</question>
<answer>
<p>You almost certainly have an older version of POI
on your classpath. Quite a few runtimes and other packages
will ship an older version of POI, so this is an easy problem
to hit without your realising.</p>
<p>The best way to identify the offending earlier jar file is
with a few lines of java. These will load one of the core POI
classes, and report where it came from.</p>
<source>
ClassLoader classloader =
org.apache.poi.poifs.filesystem.POIFSFileSystem.class.getClassLoader();
URL res = classloader.getResource(
"org/apache/poi/poifs/filesystem/POIFSFileSystem.class");
String path = res.getPath();
System.out.println("Core POI came from " + path);
</source>
</answer>
</faq>
<faq>
<question>
My code uses the scratchpad, compiles fine but fails to run with a "MethodNotFoundException"
</question>
<answer>
<p>You almost certainly have an older version earlier on your
classpath. See the prior answer.</p>
</answer>
</faq>
<faq>
<question>
I'm using the poi-ooxml-schemas jar, but my code is failing with "java.lang.NoClassDefFoundError: org/openxmlformats/schemas/*something*"
</question>
<answer>
<p>To use the new OOXML file formats, POI requires a jar containing
the file format XSDs, as compiled by
<link href="http://xmlbeans.apache.org/">XMLBeans</link>. These
XSDs, once compiled into Java classes, live in the
<em>org.openxmlformats.schemas</em> namespace.</p>
<p>There are two jar files available, as described in
<link href="/overview.html">the components overview section</link>.
The <em>full jar of all of the schemas is ooxml-schemas-1.1.jar</em>,
and it is currently around 15mb. The <em>smaller poi-ooxml-schemas
jar</em> is only about 4mb. This latter jar file only contains the
typically used parts though.</p>
<p>Many users choose to use the smaller poi-ooxml-schemas jar to save
space. However, the poi-ooxml-schemas jar only contains the XSDs and
classes that are typically used, as identified by the unit tests.
Every so often, you may try to use part of the file format which
isn't included in the minimal poi-ooxml-schemas jar. In this case,
you should switch to the full ooxml-schemas-1.1.jar. Longer term,
you may also wish to submit a new unit test which uses the extra
parts of the XSDs, so that a future poi-ooxml-schemas jar will
include them.</p>
<p>There are a number of ways to get the full ooxml-schemas-1.1.jar.
If you are a maven user, see the
<link href="/overview.html">the components overview section</link>
for the artifact details to have maven download it for you.
If you download the source release of POI, and/or checkout the
source code from <link href="/subversion.html">subversion</link>,
then you can run the ant task "compile-ooxml-xsds" to have the
OOXML schemas downloaded and compiled for you (This will also
give you the XMLBeans generated source code, in case you wish to
look at this). Finally, you can download the jar by hand from the
<link href="http://www.ibiblio.org/maven/org.apache.poi/jars/">POI
Maven Repository</link>.</p>
<p>Note that for POI 3.5 and 3.6, the full ooxml schemas jar was
named ooxml-schemas-1.0.jar. For POI 3.7, the filename was bumped
to ooxml-schemas-1.1.jar when generics support was added. You can
use ooxml-schemas-1.1.jar with POI 3.5 and 3.6 if you wish, but
POI 3.7 won't wokr with ooxml-schemas-1.0.jar (it needs thew newer
one).</p>
</answer>
</faq>
<faq>
<question>
Why is reading a simple sheet taking so long?
</question>
<answer>
<p>You've probably enabled logging. Logging is intended only for
autopsy style debugging. Having it enabled will reduce performance
by a factor of at least 100. Logging is helpful for understanding
why POI can't read some file or developing POI itself. Important
errors are thrown as exceptions, which means you probably don't need
logging.</p>
</answer>
</faq>
<faq>
<question>
What is the HSSF "eventmodel"?
</question>
<answer>
<p>The SS eventmodel package is an API for reading Excel files without loading the whole spreadsheet into memory. It does
require more knowledge on the part of the user, but reduces memory consumption by more than
tenfold. It is based on the AWT event model in combination with SAX. If you need read-only
access, this is the best way to do it.</p>
</answer>
</faq>
<faq>
<question>
Why can't read the document I created using Star Office 5.1?
</question>
<answer>
<p>Star Office 5.1 writes some records using the older BIFF standard. This causes some problems
with POI which supports only BIFF8.</p>
</answer>
</faq>
<faq>
<question>
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 POI.
If you encounter this then please create the simplest file that demonstrates the trouble and submit it to
<link href="http://issues.apache.org/bugzilla/buglist.cgi?product=POI">Bugzilla.</link></p>
</answer>
</faq>
<faq>
<question>
How do you tell if a spreadsheet cell contains a date?
</question>
<answer>
<p>Excel stores dates as numbers therefore the only way to determine if a cell is
actually stored as a date is to look at the formatting. There is a helper method
in HSSFDateUtil that checks for this.
Thanks to Jason Hoffman for providing the solution.</p>
<source>
case HSSFCell.CELL_TYPE_NUMERIC:
double d = cell.getNumericCellValue();
// test if a date!
if (HSSFDateUtil.isCellDateFormatted(cell)) {
// format in form of M/D/YY
cal.setTime(HSSFDateUtil.getJavaDate(d));
cellText =
(String.valueOf(cal.get(Calendar.YEAR))).substring(2);
cellText = cal.get(Calendar.MONTH)+1 + "/" +
cal.get(Calendar.DAY_OF_MONTH) + "/" +
cellText;
}
</source>
</answer>
</faq>
<faq>
<question>
I'm trying to stream an XLS file from a servlet and I'm having some trouble. What's the problem?
</question>
<answer>
<p>
The problem usually manifests itself as the junk characters being shown on
screen. The problem persists even though you have set the correct mime type.
</p>
<p>
The short answer is, don't depend on IE to display a binary file type properly if you stream it via a
servlet. Every minor version of IE has different bugs on this issue.
</p>
<p>
The problem in most versions of IE is that it does not use the mime type on
the HTTP response to determine the file type; rather it uses the file extension
on the request. Thus you might want to add a
<strong>.xls</strong> to your request
string. For example
<em>http://yourserver.com/myServelet.xls?param1=xx</em>. This is
easily accomplished through URL mapping in any servlet container. Sometimes
a request like
<em>http://yourserver.com/myServelet?param1=xx&amp;dummy=file.xls</em> is also
known to work.
</p>
<p>
To guarantee opening the file properly in Excel from IE, write out your file to a
temporary file under your web root from your servelet. Then send an http response
to the browser to do a client side redirection to your temp file. (Note that using a
server side redirect using RequestDispatcher will not be effective in this case)
</p>
<p>
Note also that when you request a document that is opened with an
external handler, IE sometimes makes two requests to the webserver. So if your
generating process is heavy, it makes sense to write out to a temporary file, so that multiple
requests happen for a static file.
</p>
<p>
None of this is particular to Excel. The same problem arises when you try to
generate any binary file dynamically to an IE client. For example, if you generate
pdf files using
<link href="http://xml.apache.org/fop">FOP</link>, you will come across many of the same issues.
</p>
<!-- Thanks to Avik for the answer -->
</answer>
</faq>
<faq>
<question>
I want to set a cell format (Data format of a cell) of a excel sheet as ###,###,###.#### or ###,###,###.0000. Is it possible using POI ?
</question>
<answer>
<p>
Yes. You first need to get a DataFormat object from the workbook and call getFormat with the desired format. Some examples are <link href="spreadsheet/quick-guide.html#DataFormats">here</link>.
</p>
</answer>
</faq>
<faq>
<question>
I want to set a cell format (Data format of a cell) of a excel sheet as text. Is it possible using POI ?
</question>
<answer>
<p>
Yes. This is a built-in format for excel that you can get from DataFormat object using the format string "@". Also, the string "text" will alias this format.
</p>
</answer>
</faq>
<faq>
<question>
How do I add a border around a merged cell?
</question>
<answer>
<p>Add blank cells around where the cells normally would have been and set the borders individually for each cell.
We will probably enhance HSSF in the future to make this process easier.</p>
</answer>
</faq>
<faq>
<question>
I am using styles when creating a workbook in POI, but Excel refuses to open the file, complaining about "Too Many Styles".
</question>
<answer>
<p>You just create the styles OUTSIDE of the loop in which you create cells.</p>
<p>GOOD:</p>
<source>
HSSFWorkbook wb = new HSSFWorkbook();
HSSFSheet sheet = wb.createSheet("new sheet");
HSSFRow row = null;
// Aqua background
HSSFCellStyle style = wb.createCellStyle();
style.setFillBackgroundColor(HSSFColor.AQUA.index);
style.setFillPattern(HSSFCellStyle.BIG_SPOTS);
HSSFCell cell = row.createCell((short) 1);
cell.setCellValue("X");
cell.setCellStyle(style);
// Orange "foreground",
// foreground being the fill foreground not the font color.
style = wb.createCellStyle();
style.setFillForegroundColor(HSSFColor.ORANGE.index);
style.setFillPattern(HSSFCellStyle.SOLID_FOREGROUND);
for (int x = 0; x &lt; 1000; x++) {
// Create a row and put some cells in it. Rows are 0 based.
row = sheet.createRow((short) k);
for (int y = 0; y &lt; 100; y++) {
cell = row.createCell((short) k);
cell.setCellValue("X");
cell.setCellStyle(style);
}
}
// Write the output to a file
FileOutputStream fileOut = new FileOutputStream("workbook.xls");
wb.write(fileOut);
fileOut.close();
</source>
<p>BAD:</p>
<source>
HSSFWorkbook wb = new HSSFWorkbook();
HSSFSheet sheet = wb.createSheet("new sheet");
HSSFRow row = null;
for (int x = 0; x &lt; 1000; x++) {
// Aqua background
HSSFCellStyle style = wb.createCellStyle();
style.setFillBackgroundColor(HSSFColor.AQUA.index);
style.setFillPattern(HSSFCellStyle.BIG_SPOTS);
HSSFCell cell = row.createCell((short) 1);
cell.setCellValue("X");
cell.setCellStyle(style);
// Orange "foreground",
// foreground being the fill foreground not the font color.
style = wb.createCellStyle();
style.setFillForegroundColor(HSSFColor.ORANGE.index);
style.setFillPattern(HSSFCellStyle.SOLID_FOREGROUND);
// Create a row and put some cells in it. Rows are 0 based.
row = sheet.createRow((short) k);
for (int y = 0; y &lt; 100; y++) {
cell = row.createCell((short) k);
cell.setCellValue("X");
cell.setCellStyle(style);
}
}
// Write the output to a file
FileOutputStream fileOut = new FileOutputStream("workbook.xls");
wb.write(fileOut);
fileOut.close();
</source>
</answer>
</faq>
<faq>
<question>
I can't seem to find the source for the OOXML CT.. classes, where do they
come from?
</question>
<answer>
<p>The OOXML support in Apache POI is built on top of the file format
XML Schemas, as compiled into Java using
<link href="http://xmlbeans.apache.org/">XMLBeans</link>. Currently,
the compilation is done with XMLBeans 2.3, for maximum compatibility
with installations. (You can use the resulting classes on the XMLBeans
2.3 runtime, or any later version of XMLBeans. If you are currently using
XMLBeans 2.2 or earlier, you will unfortunately have to upgrade, but this
isn't common any more).</p>
<p>All of the <em>org.openxmlformats.schemas.spreadsheetml.x2006</em> CT...
classes are auto-generated by XMLBeans. The resulting generated Java goes
in the <em>ooxml-schemas-src</em> jar, and the compiled version into the
<em>ooxml-schemas</em> jar.</p>
<p>The full <em>ooxml-schemas</em> jar is distributed with Apache POI,
along with the cut-down <em>poi-ooxml-schemas</em> jar containing just
the common parts. The source jar isn't normally distributed with POI.
It is, however, available from Maven Central - ask your favourite Maven
mirror for the <em>ooxml-schemas-src</em> jar. Alternately, if you download
the POI source distribution (or checkout from SVN) and build, Ant will
automatically download the specification XML Schema, and compile it for
you to generate the source and binary ooxml-schemas jars.</p>
</answer>
</faq>
<faq>
<question>
An OLE2 ("binary") file is giving me problems, but I can't share it. How can I investigate the problem on my own?
</question>
<answer>
<p>The first thing to try is running the
<link href="http://blogs.msdn.com/b/officeinteroperability/archive/2011/07/12/microsoft-office-binary-file-format-validator-is-now-available.aspx">Binary File Format Validator</link>
from Microsoft against the file, which will report if the file
complies with the specification. If your input file doesn't, then this
may well explain why POI isn't able to process it correctly. You
should probably in this case speak to whoever is generating the file,
and have them fix it there. If your POI generated file is identified
as having an issue, and you're on the
<link href="/howtobuild.html">latest codebase</link>, report a new
POI bug and include the details of the validation failure.</p>
<p>Another thing to try, especially if the file is valid but POI isn't
behaving as expected, are the POI Dev Tools for the component you're
using. For example, HSSF has <em>org.apache.poi.hssf.dev.BiffViewer</em>
which will allow you to view the file as POI does. This will often
allow you to check that things are being read as you expect, and
narrow in on problem records and structures.</p>
</answer>
</faq>
<faq>
<question>
An OOXML ("xml") file is giving me problems, but I can't share it. How can I investigate the problem on my own?
</question>
<answer>
<p>There's not currently a simple validator tool as there is for the
OLE2 based (binary) file formats, but checking the basics of a file
is generally much easier.</p>
<p>Files such as .xlsx, .docx and .pptx are actually a zip file of XML
files, with a special structure. Your first step in diagnosing the
issues with the input or output file will likely be to unzip the
file, and look at the XML of it. Newer versions of Office will
normally tell you which area of the file is problematic, so
narrow in on there. Looking at the XML, does it look correct?</p>
<p>When reporting bugs, ideally include the whole file, but if you're
unable to then include the snippet of XML for the problem area, and
reference the OOXML standard for what it should contain.</p>
</answer>
</faq>
</faqs>

329
src/documentation/content/xdocs/guidelines.xml Normal file
View File

@ -0,0 +1,329 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
====================================================================
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
====================================================================
-->
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "./dtd/document-v11.dtd">
<document>
<header>
<title>Apache POI - Contribution Guidelines</title>
<authors>
<person name="Nick Burch" email="dev@poi.apache.org"/>
<person name="David Fisher" email="dev@poi.apache.org"/>
</authors>
</header>
<body>
<section><title>Index of Contribution Guidelines</title>
<ul>
<li><link href="#Introduction">Introduction</link></li>
<li><link href="#GetInvolved">I just want to get involved, but don't know where to start?</link></li>
<li><link href="#SubmittingPatches">Submitting Patches</link></li>
<li><link href="#CodeStyle">Code Style</link></li>
<li><link href="#Mentoring">Mentoring and Committership</link></li>
</ul>
</section>
<anchor id="Introduction"/>
<section><title>Introduction</title>
<section><title>Disclaimer</title>
<p>
Any information in here that might be perceived as legal information is
informational only. We're not lawyers, so consult a legal professional
if needed.
</p>
</section>
<section><title>The Licensing</title>
<p>
The POI project is <link href="http://www.opensource.org">OpenSource</link>
and developed/distributed under the <link
href="http://www.apache.org/foundation/license-faq.html">
Apache Software License</link>. Unlike other licenses this license allows
free open source development; however, it does not require you to release
your source or use any particular license for your source. If you wish
to contribute to POI (which you're very welcome and encouraged to do so)
then you must agree to release the rights of your source to us under this
license.
</p>
</section>
<section><title>Publicly Available Information on the file formats</title>
<p>
In early 2008, Microsoft made a fairly complete set of documentation
on the binary file formats freely and publicly available. These were
released under the <link href="http://www.microsoft.com/interop/osp">Open
Specification Promise</link>, which does allow us to use them for
building open source software under the <link
href="http://www.apache.org/foundation/license-FAQ.html">
Apache Software License</link>.
</p>
<p>
You can download the documentation on Excel, Word, PowerPoint and
Escher (drawing) from
<link href="http://msdn.microsoft.com/en-us/library/cc313118.aspx">http://msdn.microsoft.com/en-us/library/cc313118.aspx</link>.
Documentation on a few of the supporting technologies used in these
file formats can be downloaded from
<link href="http://msdn.microsoft.com/en-us/library/jj633110.aspx">http://msdn.microsoft.com/en-us/library/jj633110.aspx</link>.
</p>
<p>
Previously, Microsoft published a book on the Excel 97 file format.
It can still be of plenty of use, and is handy dead tree form. Pick up
a copy of "Excel 97 Developer's Kit" from your favourite second hand
book store.
</p>
<p>
The newer Office Open XML (ooxml) file formats are documented as part
of the ECMA / ISO standardisation effort for the formats. This
documentation is quite large, but you can normally find the bit you
need without too much effort! This can be downloaded from
<link href="http://www.ecma-international.org/publications/standards/Ecma-376.htm">http://www.ecma-international.org/publications/standards/Ecma-376.htm</link>,
and is also under the <link href="http://www.microsoft.com/interop/osp">OSP</link>.
</p>
<p>
It is also worth checking the documentation and code of the other
open source implementations of the file formats.
</p>
</section>
<section><title>I just signed an NDA to get a spec from Microsoft and I'd like to contribute</title>
<p>
In short, stay away, stay far far away. Implementing these file formats
in POI is done strictly by using public information. Most of this Public
Information currently comes from the documentation that Microsoft
makes freely available (see above). The rest of the public information
includes sources from other open source projects, books that state the
purpose intended is for allowing implementation of the file format and
do not require any non-disclosure agreement and just hard work.
We are intent on keeping it legal, by contributing patches you agree to
do the same.
</p>
<p>
If you've ever received information regarding the OLE 2 Compound Document
Format under any type of exclusionary agreement from Microsoft, or
received such information from a person bound by such an agreement, you
cannot participate in this project. Sorry. Well, unless you can persuade
Microsoft to release you from the terms of the NDA on the grounds that
most of the information is now publically available. However, if you have
been party to a Microsoft NDA, you will need to get clearance from Microsoft
before contributing.
</p>
<p>
Those submitting patches that show insight into the file format may be
asked to state explicitly that they have only ever read the publicly
available file format information, and not any received under an NDA
or similar, and have only made us of the public documentation.
</p>
</section>
</section>
<anchor id="GetInvolved"/>
<section><title>I just want to get involved, but don't know where to start?</title>
<ul>
<li>Read the rest of the website, understand what POI is and what it does,
the project vision, etc.</li>
<li>Use POI a bit, look for gaps in the documentation and examples.</li>
<li>Join the <link href="mailinglists.html">mailing lists</link> and share your knowledge with others.</li>
<li>Get <link href="subversion.html">Subversion</link> and check out the POI source tree</li>
<li>Documentation is always the best place to start contributing, maybe you found that if the documentation just told you how to do X then it would make more sense, modify the documentation.</li>
<li>Contribute examples - if there's something people are often asking about on the <link href="mailinglists.html">user list</link> which isn't covered in the documentation or current examples, try writing an example of this and uploading it as a patch.</li>
<li>Get used to building POI, you'll be doing it a lot, be one with the build, know its targets, etc.</li>
<li>Write Unit Tests. Great way to understand POI. Look for classes that aren't tested, or aren't tested on a public/protected method level, start there.</li>
<li>Download the file format documentation from Microsoft -
<link href="http://www.microsoft.com/interop/docs/OfficeBinaryFormats.mspx">OLE2 Binary File Formats</link> or
<link href="http://www.ecma-international.org/publications/standards/Ecma-376.htm">OOXML XML File Formats</link></li>
<li>Submit patches (see below) of your contributions, modifications.</li>
<li>Check the <link href="http://issues.apache.org/bugzilla/buglist.cgi?product=POI">bug database</link> for simple problem reports, and write a patch to fix the problem</li>
<li>Review existing patches in the <link href="http://issues.apache.org/bugzilla/buglist.cgi?product=POI">bug database</link>, and report if they still apply, if they need unit tests atc.</li>
<li>Take a look at all the <link href="https://issues.apache.org/bugzilla/buglist.cgi?product=POI;bug_status=NEW;bug_status=NEEDINFO">unresolved issues in the bug database</link>, and see if you can help with testing or patches for them</li>
<li>Add in new features, see <link href="http://issues.apache.org/bugzilla/buglist.cgi?product=POI">Bug database</link> for suggestions.</li>
</ul>
<p>The Apache <link href="http://www.apache.org/dev/contributors.html">Contributors Tech Guide</link> gives a good overview how to start contributing patches.</p>
<p>The Nutch project also have a very useful guide on becoming a
new developer in their project. While it is written for their project,
a large part of it will apply to POI too. You can read it at
<link href="http://wiki.apache.org/nutch/Becoming_A_Nutch_Developer">http://wiki.apache.org/nutch/Becoming_A_Nutch_Developer</link>. The
<link href="http://community.apache.org/">Apache Community Development
Project</link> also provides guidance and mentoring for new contributors.</p>
</section>
<anchor id="SubmittingPatches"/>
<section><title>Submitting Patches</title>
<p>
Patches are submitted via the <link href="http://issues.apache.org/bugzilla/buglist.cgi?product=POI">Bug Database</link>.
Create a new bug, set the subject to [PATCH] followed by a brief description. Explain you patch and any special instructions and submit/save it.
Next, go back to the bug, and create attachements for the patch files you
created. Be sure to describe not only the files purpose, but its format.
(Is that ZIP or a tgz or a bz2 or what?).
</p>
<p>
Ideally, patches should be submitted early and often. This is for
two key reasons. Firstly, it's much easier to review smaller patches
than large ones. This means that smaller patches are much more likely
to be applied to SVN in a timely fashion. Secondly, by sending in your
patches earlier rather than later, it's much easier to get feedback
on your coding and direction. If you've missed an easier way to do something,
or are duplicating some (probably hidden) existing code, or taking things
in an unusual direction, it's best to get the feedback sooner rather than
later! As such, when submitting patches to POI, as with other Apache
Software Foundation projects, do please try to submit early and often, rather
than "throwing a large patch over the wall" at the end.
</p>
<p>
A number of Apache projects provide far more comprehensive guides to producing
and submitting patches than we do, you may wish to review some of their
information if you're unsure. The
<link href="http://commons.apache.org/patches.html">Apache Commons</link> one
is fairly similar as a starting point.
</p>
<p>You may create your patch file using either of the following approaches (the committers recommend the first):</p>
<section><title>Approach 1 - use Ant</title>
<p>Use Ant to generate a patch file to POI: </p>
<source>
ant -f patch.xml
</source>
<p>
This will create a file named patch.tar.gz that will contain a unified diff of files that have been modified
and also include files that have been added. Review the file for completeness and correctness. This approach
is recommended because it standardizes the way in which patch files are constructed. It also eliminates the
chance of you missing to submit new files that constitute part of the patch.
</p>
</section>
<section><title>Approach 2 - the manual way</title>
<p>
Patches to existing files should be generated with svn diff filename and save the output to a file.
if you want to get the changes made to multiple files in a directory , just use svn diff.
then, tar and gzip the patch file as well as any new files that you have added.
</p>
<p>If you use a unix shell, you may find the following following
sequence of commands useful for building the files to attach.</p>
<source>
# run this in the root of the checkout, i.e. the directory holding
# build.xml and poi.pom
# build the directory to hold new files
mkdir /tmp/poi-patch/
mkdir /tmp/poi-patch/new-files/
# get changes to existing files
svn diff > /tmp/poi-patch/diff.txt
# capture any new files, as svn diff won't include them
# preserve the path
svn status | grep "^\?" | awk '{printf "cp --parents %s /tmp/poi-patch/new-files/\n", $2 }' | sh -s
# tar up the new files
cd /tmp/poi-patch/new-files/
tar jcvf ../new-files.tar.bz2
cd ..
# upload these to bugzilla
echo "please upload to bugzilla:"
echo " /tmp/poi-patch/diff.txt"
echo " /tmp/poi-patch/new-files.tar.bz2"
</source>
</section>
<section><title>checklist before submitting a patch</title>
<ul>
<li>added code complies with <link href="#CodeStyle">coding standards</link></li>
<li>added code compiles and runs on java 1.5</li>
<li>new java files begin with the <link href="http://www.apache.org/foundation/license-faq.html">
apache software license</link> statement.</li>
<li>the code does not depend on gpl or lgpl code.</li>
<li>the code doesn't include @author tags</li>
<li>existing test cases succeed.</li>
<li>new test cases written and succeed.</li>
<li>documentation page extended as appropriate.</li>
<li>diff files generated using svn diff</li>
<li>the bugzilla subject dev contains [patch], task name and patch reason in subject.</li>
<li>the bugzilla description contains a rationale for the patch.</li>
<li>attachment to the bugzilla entry contains the patch file(s).</li>
</ul>
</section>
</section>
<anchor id="CodeStyle"/>
<section><title>Code Style</title>
<p>The long standing
<link href="http://poi.apache.org/resolutions/res001.html">Minimal
Coding Standards</link> from 2002 still largely apply to the project.</p>
<p>When making changes to an existing file, please try to follow the
same style that that file already uses. This will keep things
looking similar, and will prevent patches becoming largely about
whitespace. Whitespace fixing changes, if needed, should normally be
in their own commit, so that they don't crowd out coding changes
in review.</p>
<p>Normally, tabs should not be used to indent code. Instead, spaces
should be used. If starting on a fresh file, please use 4 spaces to
indent your code. If working on an existing file, please use
whichever of 3 or 4 spaces that file already follows.</p>
<p>Normally, braces should open on the same line as the decision
statement. Braces should normally close on their own line. Brackets
should normally have a space before them when they are the first.</p>
<p>Lines normally shouldn't be too long. There's no hard and fast rule,
but if you line is getting above about 90 characters think about
splitting it, and you should rarely create something over about 100
characters without a very good reason!</p>
</section>
<anchor id="Mentoring"/>
<section><title>Mentoring and Committership</title>
<p>The POI project will generally offer committership to contributors who send
in consistently good patches over a period of several months.</p>
<p>The requirement for "good patches" generally means patches which can be applied
to SVN with little or no changes. These patches should include unit test, and
appropriate documentation. Whilst your first patch to POI may require quite a
bit of work before it can be committed by an existing committer, with any luck
your later patches will be applied with no / minor tweaks. Please do take note
of any changes required by your earlier patches, to learn for later ones! If
in doubt, ask on the <link href="mailinglists.html">dev mailing list</link>.</p>
<p>The requirement for patches over several months is to ensure that committers
remain with the project. It's very easy for a good developer to fire off half
a dozen good patches in the couple of weeks that they're working on a POI
powered project. However, if that developer then moves away, and stops
contributing to POI after that spurt, then they're not a good candidate for
committership. As such, we generally require people to stay around for a while,
submitting patches and helping on the mailing list before considering them
for committership.</p>
<p>Where possible, patches should be submitted early and often. For more details
on this, please see the "Submitting Patches" section above.</p>
<p>Where possible, the existing developers will try to help and mentor new
contributors. However, everyone involved in POI is a volunteer, and it may
happen that your first few patches come in at a time when all the committers
are very busy. Do please have patience, and remember to use the
<link href="mailinglists.html">dev mailing list</link> so that other
contributors can assist you!</p>
<p>For more information on getting started at Apache, mentoring, and local
Apache Committers near you who can offer advice, please see the
<link href="http://community.apache.org/">Apache Community Development
Project</link> website.</p>
</section>
</body>
<footer>
<legal>
Copyright (c) @year@ The Apache Software Foundation. All rights reserved.
<br />
Apache POI, POI, Apache, the Apache feather logo, and the Apache
POI project logo are trademarks of The Apache Software Foundation.
</legal>
</footer>
</document>

34
src/documentation/content/xdocs/hdgf/book.xml Normal file
View File

@ -0,0 +1,34 @@
<?xml version="1.0"?>
<!--
====================================================================
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
====================================================================
-->
<!DOCTYPE book PUBLIC "-//APACHE//DTD Cocoon Documentation Book V1.0//EN" "../dtd/book-cocoon-v10.dtd">
<book software="POI Project"
title="HDGF"
copyright="@year@ POI Project">
<menu label="Apache POI">
<menu-item label="Top" href="../index.html"/>
</menu>
<menu label="HDGF">
<menu-item label="Overview" href="index.html"/>
</menu>
</book>

101
src/documentation/content/xdocs/hdgf/index.xml Normal file
View File

@ -0,0 +1,101 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
====================================================================
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
====================================================================
-->
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "../dtd/document-v11.dtd">
<document>
<header>
<title>POI-HDGF - Java API To Access Microsoft Visio Format Files</title>
<subtitle>Overview</subtitle>
<authors>
<person name="Nick Burch" email="nick at apache dot org"/>
</authors>
</header>
<body>
<section>
<title>Overview</title>
<p>HDGF is the POI Project's pure Java implementation of the Visio file format.</p>
<p>Currently, HDGF provides a low-level, read-only api for
accessing Visio documents. It also provides a
<link href="http://svn.apache.org/repos/asf/poi/trunk/src/scratchpad/src/org/apache/poi/hdgf/extractor/">way</link>
to extract the textual content from a file.
</p>
<p>At this time, there is no <em>usermodel</em> api or similar,
only low level access to the streams, chunks and chunk commands.
Users are advised to check the unit tests to see how everything
works. They are also well advised to read the documentation
supplied with
<link href="http://web.archive.org/web/20071212220759/http://www.gnome.ru/projects/vsdump_en.html">vsdump</link>
to get a feel for how Visio files are structured.</p>
<p>To get a feel for the contents of a file, and to track down
where data of interest is stored, HDGF comes with
<link href="http://svn.apache.org/repos/asf/poi/trunk/src/scratchpad/src/org/apache/poi/hdgf/dev/">VSDDumper</link>
to print out the contents of the file. Users should also make
use of
<link href="http://web.archive.org/web/20071212220759/http://www.gnome.ru/projects/vsdump_en.html">vsdump</link>
to probe the structure of files.</p>
<note>
This code currently lives the
<link href="http://svn.apache.org/viewcvs.cgi/poi/trunk/src/scratchpad/">scratchpad area</link>
of the POI SVN repository.
Ensure that you have the scratchpad jar or the scratchpad
build area in your
classpath before experimenting with this code.
</note>
<section>
<title>Steps required for write support</title>
<p>Currently, HDGF is only able to read visio files, it is
not able to write them back out again. We believe the
following are the steps that would need to be taken to
implement it.</p>
<ol>
<li>Re-write the decompression support in LZW4HDGF as
HDGFLZW, which will be much better documented, and also
under the ASL. <strong>Completed October 2007</strong></li>
<li>Add compression support to HDGFLZW.
<strong>In progress - works for small streams but encoding
goes wrong on larger ones</strong></li>
<li>Have HDGF just write back the raw bytes it read in, and
have a test to ensure the file is un-changed.</li>
<li>Have HDGF generate the bytes to write out from the
Stream stores, using the compressed data as appropriate,
without re-compressing. Plus test to ensure file is
un-changed.</li>
<li>Have HDGF generate the bytes to write out from the
Stream stores, re-compressing any streams that were
decompressed. Plus test to ensure file is un-changed.</li>
<li>Have HDGF re-generate the offsets in pointers for the
locations of the streams. Plus test to ensure file is
un-changed.</li>
<li>Have HDGF re-generate the bytes for all the chunks, from
the chunk commands. Tests to ensure the chunks are
serialized properly, and then that the file is un-changed</li>
<li>Alter the data of one command, but keep it the same
length, and check visio can open the file when written
out.</li>
<li>Alter the data of one command, to a new length, and
check that visio can open the file when written out.</li>
</ol>
</section>
</section>
</body>
</document>

158
src/documentation/content/xdocs/historyandfuture.xml Normal file
View File

@ -0,0 +1,158 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
====================================================================
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
====================================================================
-->
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.3//EN" "./dtd/document-v13.dtd">
<document>
<header>
<title>Apache POI - Project History</title>
<authors>
<person id="AO" name="Andrew C. Oliver" email="acoliver@apache.org"/>
</authors>
</header>
<body>
<section><title>Apache POI - Brief Project History</title>
<p>The POI project was dreamed up back around April 2001, when
Andrew Oliver landed a short term contract to do Java-based
reporting to Excel. He'd done this project a few times before
and knew right where to look for the tools he needed.
Ironically, the API he used to use had skyrocketed from around
$300 ($US) to around $10K ($US). He figured it would take two
people around six months to write an Excel port so he
recommended the client fork out the $10K.
</p>
<p>Around June 2001, Andrew started thinking how great it would
be to have an open source Java tool to do this and, while he
had some spare time, he started on the project and learned
about OLE 2 Compound Document Format. After hitting some real
stumpers he realized he'd need help. He posted a message to
his local Java User's Group (JUG) and asked if anyone else
would be interested. He lucked out and the most talented Java
programmer he'd ever met, Marc Johnson, joined the project. He
ran rings around Andrew at porting OLE 2 CDF and rewrote his
skeletal code into a more sophisticated library. It took Marc
a few iterations to get something they were happy with.
</p>
<p>While Marc worked on that, Andrew ported XLS to Java, based
on Marc's library. Several users wrote in asking to read XLS
(not just write as had originally been planned) and one user
had special requests for a different use for POIFS. Before
long, the project scope had tripled. POI 1.0 was released a
month later than planned, but with far more features. Marc
quickly wrote the serializer framework and HSSF Serializer in
record time and Andrew banged out more documentation and worked
on making people aware of the project
</p>
<p> Shortly before the release, POI was fortunate to come into
contact with Nicola -Ken- Barrozzi who gave them samples for
the HSSF Serializer and help uncover its unfortunate bugs
(which were promptly fixed). More recently, Ken ported most
of the POI project documentation to XML from Andrew's crappy
HTML docs he wrote with Star Office.
</p>
<p> Around the same time as the release, Glen Stampoultzis
joined the project. Glen was ticked off at Andrew's flippant attitude
towards adding graphing to HSSF. Glen got so ticked off he decided to
grab a hammer and do it himself. Glen has already become an integral
part of the POI development community; his contributions to HSSF have
already started making waves.
</p>
<p>Somewhere in there we decided to finally submit the project
to <link href="http://cocoon.apache.org/">The Apache
Cocoon Project</link>, only to discover the project had
outgrown fitting nicely into just Cocoon long ago.
Furthermore, Andrew started eyeing other projects he'd like to
see POI functionality added to. So it was decided to donate
the Serializers and Generators to Cocoon, other POI
integration components to other projects, and the POI APIs
would become part of Jakarta. It was a bumpy road but it
looks like everything turned out since you're reading this!
</p>
<p>In Early 2007, we graduated from
<link href="http://jakarta.apache.org/">Jakarta</link>, and became
our own Top Level Project (TLP) within Apache.</p>
</section>
<!--
<section><title>What's next for Poi</title>
<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
they'd simply write us each a really large check. I've yet to
get a phone call or email so I'm assuming they're not going to
pay us to go away.
</p>
<p>Next, we've got some work to do here at Jakarta to finish
integrating POI into the community. Furthermore, we're
still transitioning the Serializer to Cocoon.
</p>
<p>HSSF, during the 2.0 cycle, will undergo a few
optimizations. We'll also be adding new features like a full
implementation of Formulas and custom text formats. We're
hoping to be able to generate smaller files by adding
write-support for RK, MulRK and MulBlank records. I'm also
going to work on a Cocoon 2 Generator. Currently, reading is
not very efficient in HSSF. This is mainly because in order to
write or modify, one needs to be able to update upstream
pointers to downstream data. To do this you have to have
everything between in memory. A Generator would allow SAX
events to be processed instead. (This will be based on the low
level structures). One of the great things about this is that,
you'll not only have a more efficient way to read the file,
you'll have a great way to use spreadsheets as XML data
sources.
</p>
<p>The HSSF Serializer, will further separate into a general
framework for creating serializers for other formats and the
HSSF Serializer specific implementation. (This is largely
already true). We'll also be adding support for features
already supported by HSSF (styles, fonts, text formats). We're
hoping to add support for formulas during this cycle.
</p>
<p>We're beginning to expand our scope yet again. If we could
do all of this for XLS files, what about Doc files or PowerPoint
files? We're thinking that our next component (HWPF - Manipulates
Word Processor Format) should follow the same pattern. We're hoping
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>
</section> -->
</body>
<footer>
<legal>
Copyright (c) @year@ The Apache Software Foundation All rights reserved.
<br />
Apache POI, POI, Apache, the Apache feather logo, and the Apache
POI project logo are trademarks of The Apache Software Foundation.
</legal>
</footer>
</document>

34
src/documentation/content/xdocs/hmef/book.xml Normal file
View File

@ -0,0 +1,34 @@
<?xml version="1.0"?>
<!--
====================================================================
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
====================================================================
-->
<!DOCTYPE book PUBLIC "-//APACHE//DTD Cocoon Documentation Book V1.0//EN" "../dtd/book-cocoon-v10.dtd">
<book software="POI Project"
title="HMEF"
copyright="@year@ POI Project">
<menu label="Apache POI">
<menu-item label="Top" href="../index.html"/>
</menu>
<menu label="HMEF">
<menu-item label="Overview" href="index.html"/>
</menu>
</book>

212
src/documentation/content/xdocs/hmef/index.xml Normal file
View File

@ -0,0 +1,212 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
====================================================================
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
====================================================================
-->
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "../dtd/document-v11.dtd">
<document>
<header>
<title>POI-HMEF - Java API To Access Microsoft Transport Neutral Encoding Files (TNEF)</title>
<subtitle>Overview</subtitle>
<authors>
<person name="Nick Burch" email="nick at apache dot org"/>
</authors>
</header>
<body>
<section>
<title>Overview</title>
<p>HMEF is the POI Project's pure Java implementation of Microsoft's
TNEF (Transport Neurtral Encoding Format), aka winmail.dat,
which is used by Outlook and Exchange in some situations.</p>
<p>Currently, HMEF provides a read-only api for accessing common
message and attachment attributes, including the message body
and attachment files. In addition, it's possible to have
read-only access to all of the underlying TNEF and MAPI
attributes of the message and attachments.</p>
<p>HMEF also provides a command line tool for extracting out
the message body and attachment files from a TNEF (winmail.dat)
file.</p>
<note>
This code currently lives the
<link href="http://svn.apache.org/viewcvs.cgi/poi/trunk/src/scratchpad/">scratchpad area</link>
of the POI SVN repository.
Ensure that you have the scratchpad jar or the scratchpad
build area in your classpath before experimenting with this code.
</note>
<note>
This code is a new POI feature, and the first release that will
contain it will be POI 3.8 beta 2. Until then, you will need to
build your own jars from a <link href="../subversion.html">svn
checkout</link>.
</note>
</section>
<section>
<title>Using HMEF to access TNEF (winmail.dat) files</title>
<section>
<title>Easy extraction of message body and attachment files</title>
<p>The class <em>org.apache.poi.hmef.extractor.HMEFContentsExtractor</em>
provides both command line and Java extraction. It allows the
saving of the message body (an RTF file), and all of the
attachment files, to a single directory as specified.</p>
<p>From the command line, simply call the class specifying the
TNEF file to extract, and the directory to place the extracted
files into, eg:</p>
<source>
java -classpath poi-3.8-FINAL.jar:poi-scratchpad-3.8-FINAL.jar org.apache.poi.hmef.extractor.HMEFContentsExtractor winmail.dat /tmp/extracted/
</source>
<p>From Java, there are two method calls on the class, one to
extract the message body RTF to a file, and the other to extract
all the attachments to a directory. A typical use would be:</p>
<source>
public void extract(String winmailFilename, String directoryName) throws Exception {
HMEFContentsExtractor ext = new HMEFContentsExtractor(new File(winmailFilename));
File dir = new File(directoryName);
File rtf = new File(dir, "message.rtf");
if(! dir.exists()) {
throw new FileNotFoundException("Output directory " + dir.getName() + " not found");
}
System.out.println("Extracting...");
ext.extractMessageBody(rtf);
ext.extractAttachments(dir);
System.out.println("Extraction completed");
}
</source>
</section>
<section>
<title>Attachment attributes and contents</title>
<p>To get at your attachments, simply call the
<em>getAttachments()</em> method on a <em>HMEFMessage</em>
instance, and you'll receive a list of all the attachments.</p>
<p>When you have a <em>org.apache.poi.hmef.Attachment</em> object,
there are several helper methods available. These will all
return the value of the appropriate underlying attachment
attributes, or null if for some reason the attribute isn't
present in your file.</p>
<ul>
<li><em>getFilename()</em> - returns the name of the attachment
file, possibly in 8.3 format</li>
<li><em>getLongFilename()</em> - returns the full name of the
attachment file</li>
<li><em>getExtension()</em> - returns the extension of the
attachment file, including the "."</li>
<li><em>getModifiedDate()</em> - returns the date that the
attachment file was last edited on</li>
<li><em>getContents()</em> - returns a byte array of the contents
of the attached file</li>
<li><em>getRenderedMetaFile()</em> - returns a byte array of
a windows meta file representation of the attached file</li>
</ul>
</section>
<section>
<title>Message attributes and message body</title>
<p>A <em>org.apache.poi.hmef.HMEFMessage</em> instance is created
from an <em>InputStream</em> of the underlying TNEF (winmail.dat)
file.</p>
<p>From a <em>HMEFMessage</em>, there are three main methods of
interest to call:</p>
<ul>
<li><em>getBody()</em> - returns a String containing the RTF
contents of the message body. </li>
<li><em>getSubject()</em> - returns the message subject</li>
<li><em>getAttachments()</em> - returns the list of
<em>Attachment</em> objects for the message</li>
</ul>
</section>
<section>
<title>Low level attribute access</title>
<p>Both Messages and Attachments contain two kinds of attributes.
These are <em>TNEFAttribute</em> and <em>MAPIAttribute</em>.</p>
<p>TNEFAttribute is specific to TNEF files in terms of the
available types and properties. In general, Attachments have a
few more useful ones of these then Messages.</p>
<p>MAPIAttributes hold standard MAPI properties and values, and
work in a similar way to <link href="../hsmf/">HSMF
(Outlook)</link> does. There are typically many of these on both
Messages and Attachments. <em>Note - see limitations</em></p>
<p>Both <em>HMEFMessage</em> and <em>Attachment</em> supports
support two different ways of getting to attributes of interest.
Firstly, they support list getters, to return all attributes
(either TNEF or MAPI). Secondly, they support specific getters by
TNEF or MAPI property.</p>
<source>
HMEFMessage msg = new HMEFMessage(new FileInputStream(file));
for(TNEFAttribute attr : msg.getMessageAttributes) {
System.out.println("TNEF : " + attr);
}
for(MAPIAttribute attr : msg.getMessageMAPIAttributes) {
System.out.println("MAPI : " + attr);
}
System.out.println("Subject is " + msg.getMessageMAPIAttribute(MAPIProperty.CONVERSATION_TOPIC));
for(Attachment attach : msg.getAttachments()) {
for(TNEFAttribute attr : attach.getAttributes) {
System.out.println("A.TNEF : " + attr);
}
for(MAPIAttribute attr : attach.getMAPIAttributes) {
System.out.println("A.MAPI : " + attr);
}
System.out.println("Filename is " + attach.getAttribute(TNEFProperty.CID_ATTACHTITLE));
System.out.println("Extension is " + attach.getMAPIAttribute(MAPIProperty.ATTACH_EXTENSION));
}
</source>
</section>
</section>
<section>
<title>Investigating a TNEF file</title>
<p>To get a feel for the contents of a file, and to track down
where data of interest is stored, HMEF comes with
<link href="http://svn.apache.org/repos/asf/poi/trunk/src/scratchpad/src/org/apache/poi/hmef/dev/">HMEFDumper</link>
to print out the contents of the file.</p>
</section>
<section>
<title>Limitations</title>
<p>HMEF is currently a work-in-progress, and not everything
works yet. The current limitations are:</p>
<ul>
<li>Non-standard MAPI properties from the range 0x8000 to 0x8fff
may not be being quite correctly turned into attributes.
The values show up, but the name and type may not always
be correct.</li>
<li>All testing so far has been performed on a small number of
English documents. We think we're correctly turning bytes into
Java unicode strings, but we need a few non-English sample
files in the test suite to verify this!</li>
</ul>
</section>
</body>
</document>

125
src/documentation/content/xdocs/howtobuild.xml Normal file
View File

@ -0,0 +1,125 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
====================================================================
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
====================================================================
-->
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.3//EN" "./dtd/document-v13.dtd">
<document>
<header>
<title>Apache POI - How To Build</title>
<authors>
<person email="user@poi.apache.org" name="Glen Stampoultzis" id="GS"/>
<person email="tetsuya@apache.org" name="Tetsuya Kitahata" id="TK"/>
<person email="dfisher@jmlafferty.com" name="David Fisher" id="DF"/>
</authors>
</header>
<body>
<section>
<title>JDK Version</title>
<p>
POI 3.5 and later requires the JDK version 1.5 or later.
Versions prior to 3.5 require JDK 1.4+
</p>
</section>
<section>
<title>Install Apache Ant</title>
<p>
The POI build system requires <link href="http://ant.apache.org/bindownload.cgi">Apache Ant</link>
</p>
<p>
Specifically the build has been tested to work with Ant version
1.7.1. To install the product download the distribution and follow the instructions.
</p>
<p>
Remember to set the ANT_HOME environment variable and add ANT_HOME/bin
to your shell's PATH.
</p>
</section>
<section>
<title>Install JUnit</title>
<p>
Running unit tests and building a distribution requires <link href="http://www.junit.org/">JUnit</link>.
</p>
<p>
Just pick the latest versions of the jars from
<link href="http://sourceforge.net/projects/junit/files/junit/">SourceForge</link> and place
them in ANT_HOME/lib. Make sure that optional.jar is in ANT_HOME/lib.
</p>
</section>
<section>
<title>Install Apache Forrest</title>
<p>
The POI build system requires <link href="http://forrest.apache.org/">Apache Forrest</link> to build the documentation.
</p>
<p>
Specifically the build has been tested to work with Forrest 0.5. This is an old release which is available
<link href="http://archive.apache.org/dist/forrest/pre-0.6/">here</link>.
</p>
<p>
Remember to set the FORREST_HOME environment variable.
</p>
</section>
<section>
<title>Building Targets with Ant</title>
<p>
The main targets of interest to our users are:
</p>
<table>
<tr>
<th>Ant Target</th>
<th>Description</th>
</tr>
<tr>
<td>clean</td>
<td>Erase all build work products (ie. everything in the
build directory</td>
</tr>
<tr>
<td>compile</td>
<td>Compiles all files from main, ooxml and scratchpad</td>
</tr>
<tr>
<td>test</td>
<td>Run all unit tests from main, ooxml and scratchpad</td>
</tr>
<tr>
<td>jar</td>
<td>Produce jar files</td>
</tr>
<tr>
<td>assemble</td>
<td>Produce .zip and tar.gz distribution packages</td>
</tr>
<tr>
<td>docs</td>
<td>Generate all documentation (Requires Apache Forrest)</td>
</tr>
</table>
</section>
</body>
<footer>
<legal>
Copyright (c) @year@ The Apache Software Foundation. All rights reserved.
<br />
Apache POI, POI, Apache, the Apache feather logo, and the Apache
POI project logo are trademarks of The Apache Software Foundation.
</legal>
</footer>
</document>

35
src/documentation/content/xdocs/hpbf/book.xml Normal file
View File

@ -0,0 +1,35 @@
<?xml version="1.0"?>
<!--
====================================================================
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
====================================================================
-->
<!DOCTYPE book PUBLIC "-//APACHE//DTD Cocoon Documentation Book V1.0//EN" "../dtd/book-cocoon-v10.dtd">
<book software="POI Project"
title="HPBF"
copyright="@year@ POI Project">
<menu label="Apache POI">
<menu-item label="Top" href="../index.html"/>
</menu>
<menu label="HPBF">
<menu-item label="Overview" href="index.html"/>
<menu-item label="File Format" href="file-format.xml"/>
</menu>
</book>

197
src/documentation/content/xdocs/hpbf/file-format.xml Normal file
View File

@ -0,0 +1,197 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
====================================================================
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
====================================================================
-->
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "../dtd/document-v11.dtd">
<document>
<header>
<title>POI-HPBF - A Guide to the Publisher File Format</title>
<subtitle>Overview</subtitle>
<authors>
<person name="Nick Burch" email="nick at torchbox dot com"/>
</authors>
</header>
<body>
<section><title>Document Streams</title>
<p>
The file is made up of a number of POIFS streams. A typical
file will be made up as follows:
</p>
<source>
Root Entry -
Objects -
(no children)
SummaryInformation &lt;(0x05)SummaryInformation&gt;
DocumentSummaryInformation &lt;(0x05)DocumentSummaryInformation&gt;
Escher -
EscherStm
EscherDelayStm
Quill -
QuillSub -
CONTENTS
CompObj &lt;(0x01)CompObj&gt;
Envelope
Contents
Internal &lt;(0x03)Internal&gt;
CompObj &lt;(0x01)CompObj&gt;
VBA -
(no children)
</source>
</section>
<section><title>Changing Text</title>
<p>If you make a change to the text of a file, but not change
how much text there is, then the <em>CONTENTS</em> stream
will undergo a small change, and the <em>Contents</em> stream
will undergo a large change.</p>
<p>If you make a change to the text of a file, and change the
amount of text there is, then both the <em>Contents</em> and
the <em>CONTENTS</em> streams change.</p>
</section>
<section><title>Changing Shapes</title>
<p>If you alter the size of a textbox, but make no text changes,
then both <em>Contents</em> and <em>CONTENTS</em> streams
change. There are no changes to the Escher streams.</p>
<p>If you set the background colour of a textbox, but make
no changes to the text, (to finish off)</p>
</section>
<section><title>Structure of CONTENTS</title>
<p>First we have "CHNKINK ", followed by 24 bytes.</p>
<p>Next we have 20 sequences of 24 bytes each. If the first two bytes
at 0x1800, then that sequence entry exists, but if it's 0x0000 then
the entry doesn't exist. If it does exist, we then have 4 bytes of
upper case ASCII text, followed by three little endian shorts.
The first of these seems to be the count of that type, the second is
usually 1, the third is usually zero. The we have another 4 bytes of
upper case ASCII text, normally but not always the same as the first
text. Finally, we have an unsigned little endian 32 bit offset to
the start of the data for this, then an unsigned little endian
32 bit offset of the length of this section.</p>
<p>Normally, the first sequence entry is for TEXT, and the text data
will start at 0x200. After that is normally two or three STSH entries
(so the first short has values 0, then 1, then 2). After that it
seems to vary.</p>
<p>At 0x200 we have the text, stored as little endian 16 bit unicode.</p>
<p>After the text comes all sorts of other stuff, presumably as
described by the sequences.</p>
<p>For a contents stream of length 7168 / 0x1c00 bytes, the start
looks something like:</p>
<source>
CHNKINK // "CHNKINK "
04 00 07 00 // Normally 04 00 07 00
13 00 00 03 // Normally ## 00 00 03
00 02 00 00 // Normally 00 ## 00 00
00 1c 00 00 // Normally length of the stream
f8 01 13 00 // Normally f8 01 11/13 00
ff ff ff ff // Normally seems to be ffffffff
18 00
TEXT 00 00 01 00 00 00 // TEXT 0 1 0
TEXT 00 02 00 00 d0 03 00 00 // TEXT from: 200 (512), len: 3d0 (976)
18 00
STSH 00 00 01 00 00 00 // STSH 0 1 0
STSH d0 05 00 00 1e 00 00 00 // STSH from: 5d0 (1488), len: 1e (30)
18 00
STSH 01 00 01 00 00 00 // STSH 1 1 0
STSH ee 05 00 00 b8 01 00 00 // STSH from: 5ee (1518), len: 1b8 (440)
18 00
STSH 02 00 01 00 00 00 // STSH 2 1 0
STSH a6 07 00 00 3c 00 00 00 // STSH from: 7a6 (1958), len: 3c (60)
18 00
FDPP 00 00 01 00 00 00 // FDPP 0 1 0
FDPP 00 08 00 00 00 02 00 00 // FDPP from: 800 (2048), len: 200 (512)
18 00
FDPC 00 00 01 00 00 00 // FDPC 0 1 0
FDPC 00 0a 00 00 00 02 00 00 // FDPC from: a00 (2560), len: 200 (512)
18 00
FDPC 01 00 01 00 00 00 // FDPC 1 1 0
FDPC 00 0c 00 00 00 02 00 00 // FDPC from: c00 (3072), len: 200 (512)
18 00
SYID 00 00 01 00 00 00 // SYID 0 1 0
SYID 00 0e 00 00 20 00 00 00 // SYID from: e00 (3584), len: 20 (32)
18 00
SGP 00 00 01 00 00 00 // SGP 0 1 0
SGP 20 0e 00 00 0a 00 00 00 // SGP from: e20 (3616), len: a (10)
18 00
INK 00 00 01 00 00 00 // INK 0 1 0
INK 2a 0e 00 00 04 00 00 00 // INK from: e2a (3626), len: 4 (4)
18 00
BTEP 00 00 01 00 00 00 // BTEP 0 1 0
PLC 2e 0e 00 00 18 00 00 00 // PLC from: e2e (3630), len: 18 (24)
18 00
BTEC 00 00 01 00 00 00 // BTEC 0 1 0
PLC 46 0e 00 00 20 00 00 00 // PLC from: e46 (3654), len: 20 (32)
18 00
FONT 00 00 01 00 00 00 // FONT 0 1 0
FONT 66 0e 00 00 48 03 00 00 // FONT from: e66 (3686), len: 348 (840)
18 00
TCD 03 00 01 00 00 00 // TCD 3 1 0
PLC ae 11 00 00 24 00 00 00 // PLC from: 11ae (4526), len: 24 (36)
18 00
TOKN 04 00 01 00 00 00 // TOKN 4 1 0
PLC d2 11 00 00 0a 01 00 00 // PLC from: 11d2 (4562), len: 10a (266)
18 00
TOKN 05 00 01 00 00 00 // TOKN 5 1 0
PLC dc 12 00 00 2a 01 00 00 // PLC from: 12dc (4828), len: 12a (298)
18 00
STRS 00 00 01 00 00 00 // STRS 0 1 0
PLC 06 14 00 00 46 00 00 00 // PLC from: 1406 (5126), len: 46 (70)
18 00
MCLD 00 00 01 00 00 00 // MCLD 0 1 0
MCLD 4c 14 00 00 16 06 00 00 // MCLD from: 144c (5196), len: 616 (1558)
18 00
PL 00 00 01 00 00 00 // PL 0 1 0
PL 62 1a 00 00 48 00 00 00 // PL from: 1a62 (6754), len: 48 (72)
00 00 // Blank entry follows
00 00 00 00 00 00
00 00 00 00 00 00 00 00
00 00 00 00 00 00 00 00
(the text will then start)
</source>
<p>We think that the first 4 bytes of text describes the
the function of the data at the offset. The first short is
then the count of that type, eg the 2nd will have 1. We
think that the second 4 bytes of text describes the format
of data block at the offset. The format of the text block
is easy, but we're still trying to figure out the others.</p>
<section><title>Structure of TEXT bit</title>
<p>This is very simple. All the text for the document is
stored in a single bit of the Quill CONTENTS. The text
is stored as little endian 16 bit unicode strings.</p>
</section>
<section><title>Structure of PLC bit</title>
<p>The first four bytes seem to hold the count of the
entries in the bit, and the second four bytes seem to hold
the type. There is then some pre-data, and then data for
each of the entries, the exact format dependant on the type.</p>
<p>Type 0 has 4 2 byte unsigned ints, then a pair of 2 byte
unsigned ints for each entry.</p>
<p>Type 4 has 4 2 byte unsigned ints, then a pair of 4 byte
unsigned ints for each entry.</p>
<p>Type 8 has 7 2 byte unsigned ints, then a pair of 4 byte
unsigned ints for each entry.</p>
<p>Type 12 holds hyperlinks, and is very much more complex.
See <code>org.apache.poi.hpbf.model.qcbits.QCPLCBit</code>
for our best guess as to how the contents match up.</p>
</section>
</section>
</body>
</document>

66
src/documentation/content/xdocs/hpbf/index.xml Normal file
View File

@ -0,0 +1,66 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
====================================================================
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
====================================================================
-->
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "../dtd/document-v11.dtd">
<document>
<header>
<title>POI-HPBF - Java API To Access Microsoft Publisher Format Files</title>
<subtitle>Overview</subtitle>
<authors>
<person name="Nick Burch" email="nick at apache dot org"/>
</authors>
</header>
<body>
<section>
<title>Overview</title>
<p>HPBF is the POI Project's pure Java implementation of the
Publisher file format.</p>
<p>Currently, HPBF is in an early stage, whilst we try to
figure out the file format. So far, we have basic text
extraction support, and are able to read some parts within
the file. Writing is not yet supported, as we are unable
to make sense of the Contents stream, which we think has
lots of offsets to other parts of the file.</p>
<p>Our initial aim is to provude a text extractor for the format
(now done), and be able to extract hyperlinks from within
the document (partly supported). Additional low level
code to process the file format may follow, if there
is demand and developer interest warrant it.</p>
<p>Text Extraction is available via the
<em>org.apache.poi.hpbf.extractor.PublisherTextExtractor</em>
class.</p>
<p>At this time, there is no <em>usermodel</em> api or similar.
There is only low level support for certain parts of
the file, but by no means all of it.</p>
<p>Our current understanding of the file format is documented
<link href="file-format.html">here</link>.</p>
<note>
This code currently lives the
<link href="http://svn.apache.org/viewcvs.cgi/poi/trunk/src/scratchpad/">scratchpad area</link>
of the POI SVN repository.
Ensure that you have the scratchpad jar or the scratchpad
build area in your
classpath before experimenting with this code.
</note>
</section>
</body>
</document>

36
src/documentation/content/xdocs/hpsf/book.xml Normal file
View File

@ -0,0 +1,36 @@
<?xml version="1.0"?>
<!--
====================================================================
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
====================================================================
-->
<!DOCTYPE book PUBLIC "-//APACHE//DTD Cocoon Documentation Book V1.0//EN" "../dtd/book-cocoon-v10.dtd">
<book software="POI Project"
title="HPSF"
copyright="@year@ POI Project">
<menu label="Apache POI">
<menu-item label="Top" href="../index.html"/>
</menu>
<menu label="HPSF">
<menu-item label="Overview" href="index.html"/>
<menu-item label="How To" href="how-to.html"/>
<menu-item label="Thumbnails" href="thumbnails.html"/>
<menu-item label="Internals" href="internals.html"/>
<menu-item label="To Do" href="todo.html"/>
</menu>
</book>

1500
src/documentation/content/xdocs/hpsf/how-to.xml Normal file
View File

File diff suppressed because it is too large Load Diff

74
src/documentation/content/xdocs/hpsf/index.xml Normal file
View File

@ -0,0 +1,74 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
====================================================================
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
====================================================================
-->
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "../dtd/document-v11.dtd">
<document>
<header>
<title>Apache POI - HPSF - Java API to Handle Microsoft Format Document
Properties</title>
<subtitle>Overview</subtitle>
<authors>
<person name="Rainer Klute" email="klute@apache.org"/>
</authors>
</header>
<body>
<section><title>Overview</title>
<p>Microsoft applications like "Word", "Excel" or "Powerpoint" 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 document properties are stored in so-called <strong>property set
streams</strong>. A property set stream is a separate document within a
<link href="../poifs/index.html">POI filesystem</link>. We'll call property
set streams mostly just "property sets". HPSF is POI's pure-Java
implementation to read and write property sets.</p>
<p>The <link href="how-to.html">HPSF HOWTO</link> describes what a Java
application should do to read a property set using HPSF, how to retrieve
the information it needs, and how to write properties into the
document.</p>
<p>HPSF supports OLE2 property set streams in general, and is not limited to
the special case of document properties in the Microsoft Office files
mentioned above. The <link href="internals.html">HPSF description</link>
describes the internal structure of property set streams. A separate
document explains the internal of <link href="thumbnails.html">thumbnail
images</link>.</p>
</section>
</body>
</document>
<!-- Keep this comment at the end of the file
Local variables:
mode: xml
sgml-omittag:nil
sgml-shorttag:nil
sgml-namecase-general:nil
sgml-general-insert-case:lower
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
sgml-parent-document:nil
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
-->

1081
src/documentation/content/xdocs/hpsf/internals.xml Normal file
View File

File diff suppressed because it is too large Load Diff

199
src/documentation/content/xdocs/hpsf/thumbnails.xml Normal file
View File

@ -0,0 +1,199 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
====================================================================
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
====================================================================
-->
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN"
"../dtd/document-v11.dtd">
<document>
<header>
<title>HPSF THUMBNAIL HOW-TO</title>
<authors>
<person name="Drew Varner" email="Drew.Varner@-deleteThis-sc.edu" />
</authors>
</header>
<body>
<section><title>The VT_CF Format</title>
<p>Thumbnail information is stored as a VT_CF, or Thumbnail Variant. The
Thumbnail Variant is used to store various types of information in a
clipboard. The VT_CF can store information in formats for the Macintosh or
Windows clipboard.</p>
<p>There are many types of data that can be copied to the clipboard, but the
only types of information needed for thumbnail manipulation are the image
formats.</p>
<p>The <code>VT_CF</code> structure looks like this:</p>
<table>
<tr>
<th>Element:</th>
<td>Clipboard Size</td>
<td>Clipboard Format Tag</td>
<td>Clipboard Data</td>
</tr>
<tr>
<th>Size:</th>
<td>32 bit unsigned integer (DWord)</td>
<td>32 bit signed integer (DWord)</td>
<td>variable length (byte array)</td>
</tr>
</table>
<p>The Clipboard Size refers to the size (in bytes) of Clipboard Data
(variable size) plus the Clipboard Format (four bytes).</p>
<p>Clipboard Format Tag has four possible values:</p>
<table>
<tr>
<th>Value</th>
<th>Identifier</th>
<th>Description</th>
</tr>
<tr>
<td><code>-1L</code></td>
<td><code>CFTAG_WINDOWS</code></td>
<td>a built-in Windows&copy; clipboard format value</td>
</tr>
<tr>
<td><code>-2L</code></td>
<td><code>CFTAG_MACINTOSH</code></td>
<td>a Macintosh clipboard format value</td>
</tr>
<tr>
<td><code>-3L</code></td>
<td><code>CFTAG_FMTID</code></td>
<td>a format identifier (FMTID) This is rarely used.</td>
</tr>
<tr>
<td><code>0L</code></td>
<td><code>CFTAG_NODATA</code></td>
<td>No data This is rarely used.</td>
</tr>
</table>
</section>
<section><title>Windows Clipboard Data</title>
<p>Windows clipboard data has four image formats for thumbnails:</p>
<table>
<tr>
<th>Value</th>
<th>Identifier</th>
<th>Description</th>
</tr>
<tr>
<td>3</td>
<td><code>CF_METAFILEPICT</code></td>
<td>Windows metafile format - recommended</td>
</tr>
<tr>
<td>8</td>
<td><code>CF_DIB</code></td>
<td>Device Independent Bitmap</td>
</tr>
<tr>
<td>14</td>
<td><code>CF_ENHMETAFILE</code></td>
<td>Enhanced Windows metafile format</td>
</tr>
<tr>
<td>2</td>
<td><code>CF_BITMAP</code></td>
<td>Bitmap - Obsolete - Use <code>CF_DIB</code> instead</td>
</tr>
</table>
</section>
<section><title>Windows Metafile Format</title>
<p>The most common format for thumbnails on the Windows platform is the
Windows metafile format. The Clipboard places and extra header in front of
a the standard Windows Metafile Format data.</p>
<p>The Clipboard Data byte array looks like this when an image is stored in
Windows' Clipboard WMF format.</p>
<table>
<tr>
<th>Identifier</th>
<td>CF_METAFILEPICT</td>
<td>mm</td>
<td>width</td>
<td>height</td>
<td>handle</td>
<td>WMF data</td>
</tr>
<tr>
<th>Size</th>
<td>32 bit unsigned int</td>
<td>16 bit unsigned(?) int</td>
<td>16 bit unsigned(?) int</td>
<td>16 bit unsigned(?) int</td>
<td>16 bit unsigned(?) int</td>
<td>byte array - variable length</td>
</tr>
<tr>
<th>Description</th>
<td>Clipboard WMF</td>
<td>Mapping Mode</td>
<td>Image Width</td>
<td>Image Height</td>
<td>handle to the WMF data array in memory, or 0</td>
<td>standard WMF byte stream</td>
</tr>
</table>
</section>
<section><title>Device Independent Bitmap</title>
<p><strong>FIXME:</strong> Describe the Device Independent Bitmap
format!</p>
</section>
<section><title>Macintosh Clipboard Data</title>
<p><strong>FIXME:</strong> Describe the Macintosh clipboard formats!</p>
</section>
</body>
</document>
<!-- Keep this comment at the end of the file
Local variables:
mode: xml
sgml-omittag:nil
sgml-shorttag:nil
sgml-namecase-general:nil
sgml-general-insert-case:lower
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
sgml-parent-document:nil
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
-->

77
src/documentation/content/xdocs/hpsf/todo.xml Normal file
View File

@ -0,0 +1,77 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
====================================================================
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
====================================================================
-->
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "../dtd/document-v11.dtd">
<document>
<header>
<title>To Do</title>
<authors>
<person name="Rainer Klute" email="klute@rainer-klute.de"/>
</authors>
</header>
<body>
<section><title>To Do</title>
<p>The following functionalities should be added to HPFS:</p>
<ol>
<li>
Improve writing support! We need convenience classes and methods for
easily writing summary information streams and document summary
information streams.
</li>
<li>
Add resource bundles to
<code>org.apache.poi.hpsf.wellknown</code> to ease
localizations. This would be useful for mapping standard property IDs to
localized strings. Example: The property ID 4 could be mapped to "Author"
in English or "Verfasser" in German.
</li>
<li>
Implement reading functionality for those property types that are not
yet supported. HPSF should return proper Java types instead of just byte
arrays.
</li>
<li>
Add WMF to <code>java.awt.Image</code> example code in the <link
href="thumbnails.html">Thumbnail HOW-TO</link>.
</li>
</ol>
</section>
</body>
</document>
<!-- Keep this comment at the end of the file
Local variables:
mode: xml
sgml-omittag:nil
sgml-shorttag:nil
sgml-namecase-general:nil
sgml-general-insert-case:lower
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
sgml-parent-document:nil
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
-->

34
src/documentation/content/xdocs/hsmf/book.xml Normal file
View File

@ -0,0 +1,34 @@
<?xml version="1.0"?>
<!--
====================================================================
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
====================================================================
-->
<!DOCTYPE book PUBLIC "-//APACHE//DTD Cocoon Documentation Book V1.0//EN" "../dtd/book-cocoon-v10.dtd">
<book software="POI Project"
title="HSMF"
copyright="@year@ POI Project">
<menu label="Apache POI">
<menu-item label="Top" href="../index.html"/>
</menu>
<menu label="HSMF">
<menu-item label="Overview" href="index.html"/>
</menu>
</book>

55
src/documentation/content/xdocs/hsmf/index.xml Normal file
View File

@ -0,0 +1,55 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
====================================================================
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
====================================================================
-->
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "../dtd/document-v11.dtd">
<document>
<header>
<title>POI-HSMF - Java API To Access Microsoft Outlook MSG Files</title>
<subtitle>Overview</subtitle>
<authors>
<person name="Nick Burch" email="nick at apache dot org"/>
<person name="Travis Ferguson" email="uniformstupidity at gmail dot com"/>
</authors>
</header>
<body>
<section>
<title>Overview</title>
<p>HSMF is the POI Project's pure Java implementation of the Outlook MSG format.</p>
<p>At this time, it provides low-level read access to all of the file, along
with a user-facing way to get at the common textual content of MSG files.
to all</p>
<p>There is an example MSG textual renderer, which shows how to access the
common parts such as sender, subject, message body and examples. This is
in the
<link href="http://svn.apache.org/viewcvs.cgi/poi/trunk/src/examples/src/org/apache/poi/hsmf/examples/">HSMF examples area</link>
of SVN. You may also wish to look at the unit tests for more use guides.</p>
<note>
This code currently lives the
<link href="http://svn.apache.org/viewcvs.cgi/poi/trunk/src/scratchpad/">scratchpad area</link>
of the POI SVN repository.
Ensure that you have the scratchpad jar or the scratchpad
build area in your classpath before experimenting with this code.
</note>
</section>
</body>
</document>

31
src/documentation/content/xdocs/hwpf/book.xml Normal file
View File

@ -0,0 +1,31 @@
<?xml version="1.0"?>
<!--
====================================================================
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
====================================================================
-->
<!DOCTYPE book PUBLIC "-//APACHE//DTD Cocoon Documentation Book V1.0//EN" "../dtd/book-cocoon-v10.dtd">
<book software="POI Project" title="HWPF" copyright="@year@ POI Project">
<menu label="Apache POI">
<menu-item label="Top" href="../index.html"/>
</menu>
<menu label="HWPF">
<menu-item label="Overview" href="index.html"/>
<menu-item label="Quick Guide" href="quick-guide.html"/>
<menu-item label="HWPF Format" href="docoverview.html"/>
<menu-item label="HWPF Project plan" href="projectplan.html"/>
</menu>
</book>

113
src/documentation/content/xdocs/hwpf/docoverview.xml Normal file
View File

@ -0,0 +1,113 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
====================================================================
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
====================================================================
-->
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "../dtd/document-v11.dtd">
<document>
<header>
<title>Apache POI - HWPF - Java API to Handle Microsoft Word Files</title>
<subtitle>Word File Format</subtitle>
<authors>
<person name="S. Ryan Ackley" email="sackley@cfl.rr.com"/>
</authors>
</header>
<body>
<section><title>The Word 97 File Format in semi-plain English</title>
<p>The purpose of this document is to give a brief high level overview of the
HWPF document format. This document does not go into in-depth technical
detail and is only meant as a supplement to the Microsoft Word 97-2007
Binary File Format freely available from
<link href="http://www.microsoft.com/interop/docs/officebinaryformats.mspx">Microsoft</link>.</p>
<p>The OLE file format is not discussed in this document. It is assumed that
the reader has a working knowledge of the POIFS API. </p>
<section><title>Word file structure</title>
<p>A Word file is made up of the document text and data structures
containing formatting information about the text. Of course, this is a
very simplified illustration. There are fields and macros and other
things that have not been considered. At this stage, HWPF is mainly
concerned with formatted text.</p>
</section>
<section><title>Reading Word files</title>
<p>The entry point for HWPF's reading of a Word file is the File Information
Block (FIB). This structure is the entry point for the locations and size
of a document's text and data structures. The FIB is located at the
beginning of the main stream.</p>
<section><title>Text</title>
<p>The document's text is also located in the main stream. Its starting
location is given as FIB.fcMin and its length is given in bytes by
FIB.ccpText. These two values are not very useful in getting the text
because of unicode. There may be unicode text intermingled with ASCII
text. That brings us to the piece table.</p>
<p>The piece table is used to divide the text into non-unicode and unicode
pieces. The size and offset are given in FIB.fcClx and FIB.lcbClx
respectively. The piece table may contain Property Modifiers (prm).
These are for complex(fast-saved) files and are skipped. Each text piece
contains offsets in the main stream that contain text for that piece.
If the piece uses unicode, the file offset is masked with a certain bit.
Then you have to unmask the bit and divide by 2 to get the real file
offset. </p>
</section>
<section><title>Text Formatting</title>
<section><title>Stylesheet</title>
<p>All text formatting is based on styles contained in the StyleSheet.
The StyleSheet is a data structure containing among other things, style
descriptions. Each style description can contain a paragraph style and
a character style or simply a character style. Each style description
is stored in a compressed version on file. Basically these are deltas
from another style.</p>
<p>Eventually, you have to chain back to the nil style which is an
imaginary style with certain implied values.</p>
</section>
<section><title>Paragraph and Character styles</title>
<p>Paragraph and Character formatting properties for a document's text are
stored on file as deltas from some base style in the Stylesheet. The
deltas are used to create a complete uncompressed style in memory.</p>
<p>Uncompressed paragraph styles are represented by the Pargraph
Properties(PAP) data structure. Uncompressed character styles are
represented by the Character Properties(CHP) data structure. The styles
for the document text are stored in compressed format in the
corresponding Formatted Disk Pages (FKP). A compressed PAP is referred
to as a PAPX and a compressed CHP is a CHPX. The FKP locations are
stored in the bin table. There are seperate bin tables for CHPXs and
PAPXs. The bin tables' locations and sizes are stored in the FIB.</p>
<p>A FKP is a 512 byte OLE page. It contains the offsets of the beginning
and end of each paragraph/character run in the main stream and the
compressed properties for that interval. The compessed PAPX is based on
its base style in the StyleSheet. The compressed CHPX is based on the
enclosing paragraph's base style in the Stylesheet.</p>
</section>
<section><title>Uncompressing styles and other data structures</title>
<p>All compressed properties(CHPX, PAPX, SEPX) contain a grpprl. A grpprl
is an array of sprms. A sprm defines a delta from some base property.
There is a table of possible sprms in the Word 97 spec. Each sprm is a
two byte operand followed by a parameter. The parameter size depends on
the sprm. Each sprm describes an operation that should be performed on
the base style. After every sprm in the grpprl is performed on the base
style you will have the style for the paragraph, character run,
section, etc.</p>
</section>
</section>
</section>
</section>
</body>
</document>

200
src/documentation/content/xdocs/hwpf/index.xml Normal file
View File

@ -0,0 +1,200 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
====================================================================
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
====================================================================
-->
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "../dtd/document-v11.dtd">
<document>
<header>
<title>Apache POI - HWPF - Java API to Handle Microsoft Word Files</title>
<subtitle>Overview</subtitle>
<authors>
<person name="Nicola Ken Barozzi" email="barozzi@nicolaken.com"/>
<person name="Andrew C. Oliver" email="acoliver@apache.org"/>
<person name="Ryan Ackley" email="sackley@apache.org"/>
<person name="Rainer Klute" email="klute@apache.org"/>
</authors>
</header>
<body>
<section><title>Overview</title>
<p>HWPF is the name of our port of the Microsoft Word 97(-2007) file format
to pure Java. It also provides limited read only support for the older
Word 6 and Word 95 file formats.</p>
<p>The partner to HWPF for the new Word 2007 .docx format is <em>XWPF</em>.
Whilst HWPF and XWPF provide similar features, there is not a common
interface across the two of them at this time.</p>
<p>HWPF is still in early development. It is in the <link
href="http://svn.apache.org/viewcvs.cgi/poi/trunk/src/scratchpad/">
scratchpad section of the SVN.</link> You will need to ensure you
either have a recent SVN checkout, or a recent SVN nightly build
(including the scratchpad jar!)</p>
<p>
Source code in the
<em>org.apache.poi.hdf</em>
tree is the old legacy code. Source in the
<em>org.apache.poi.hwpf.model</em>
tree is the old legacy code refactored into an new object model. Those packages contains
Java representation of internal Word format structure. This code is "internal", it shall not
be used by your code. Because of backward-compatibility some API still has references to
those packages. They are subject to be deprecated and removed. Code from
<em>org.apache.poi.hwpf.usermodel</em>
package is actual public and user-friendly (as much as possible) API to access document
parts. Source code in the
<em>org.apache.poi.hwpf.extractor</em>
tree is a wrapper of this to facilitate easy extraction of interesting things (eg the Text),
and
<em>org.apache.poi.hwpf.converter</em>
package contains Word-to-HTML and Word-to-FO converters (latest can be used to generate PDF
from Word files when using with
<link href="http://xmlgraphics.apache.org/fop/">Apache FOP</link>
). Also there is a small file-structure-dumping utility in
<em>org.apache.poi.hwpf.dev</em>
package, primally for developing purposes.
</p>
<p>
The main entry point to HWPF is HWPFDocument. Currently it has a lot of references both to
internal interfaces (
<em>org.apache.poi.hwpf.model</em>
package) and public API (
<em>org.apache.poi.hwpf.usermodel</em>
) package. It is possible that it will be split into two different interfaces (like WordFile
and WordDocument) in later versions.
</p>
<p>Word document can be considered as very long single text buffer. HWPF API provides "pointers"
to document parts, like sections, paragraphs and character runs. Usually user will iterates
over main document part sections, paragraphs from sections and character runs from
paragraph. Each such interface is a pointer to document text subrange along with additional
properties (and they all extends same Range parent class). There is additional Range
implementations like Table, TableRow, TableCell, etc. Some structures like Bookmark or Field
can also provide subranges pointers.
</p>
<p>Changing file content usually requires a lot of synchronized changes in those structures like
updating property boundaries, position handlers, etc. Because of that HWPF API shall be
considered as not thread safe. In addition, there is a "one pointer" rule for changing
content. It means you should not use two different Range instances at one time. More
precisely, if you are changing file content using some range pointer, all other range
pointers except parents' ones become invalid. For example if you obtain overall range (1),
paragraph range (2) from overall range and character run range (3) from paragraph range and
change text of paragraph, character run range is now invalid and should not be used, but
overall range pointer still valid. Each time you obtaining range (pointer) new instance is
created. It means if you obtained two range pointers and changed document text using first
range pointer, second one became invalid.
</p>
</section>
<section>
<title>XWPF Patches Required!</title>
<p>At the moment, XWPF covers many common use cases for reading and writing
.docx files. Whilst this is a great thing, it does mean that XWPF does
everything that the current POI committers need it to do, and so none of
the committers are actively adding new features.</p>
<p>If you come across a feature in XWPF that you need, and isn't currently
there, please do send in a patch to add the extra functionality! More details
on contributing patches are available on the <link
href="../guidelines.html">"Contribution to POI" page</link>.</p>
</section>
<section>
<title>HWPF Pointman Needed!</title>
<p>At the moment we unfortunately do not have someone taking care for HWPF
and fostering its development. What we need is someone to stand up, take
this thing under his hood as his baby and push it forward. Ryan Ackley,
who put a lot of effort into HWPF, is no longer on board, so HWPF is an
orphan child waiting to be adopted.</p>
<p>If <strong>you</strong> are interested in becoming the new HWPF
pointman, you should look into the Microsoft Word internals. A good
starting point seems to be Ryan Ackley's <link
href="docoverview.html">overview</link>. Full details on the word format
is available from
<link href="http://www.microsoft.com/interop/docs/OfficeBinaryFormats.mspx">Microsoft</link>,
but the documentation can be a little hard to get into at first... Try reading the
<link href="docoverview.html">overview</link> first, and looking at the existing
code, then finally look up the documentation for specific missing features.</p>
<p>As a first step you should familiarize yourself with the source code,
examples, test cases, and the HWPF patches available at <link
href="http://issues.apache.org/">Bugzilla</link> (if any). Then you
should compile an overview of</p>
<ul>
<li>the current HWPF status,</li>
<li>the patches in <link
href="http://issues.apache.org/bugzilla/">Bugzilla</link> to be checked
in (and those that should better be ditched),</li>
<li>the available test cases and the test cases still to be written,</li>
<li>the available documentation and the docs to be written,</li>
<li>anything else that seems reasonable</li>
</ul>
<p>When you start coding, you will not yet have write access to the
SVN repository. Please submit your patches to <link
href="http://issues.apache.org/">Bugzilla</link> and nag <link
href="mailto:dev@poi.apache.org">the dev list</link> until someone commits
them. Besides the actual checking in of HWPF patches, current POI
committers will also do some minor reviews now and then of your source code
patches, test cases and documentation to help ensure software quality. But
most of the time you will be on your own. However, anyone offering useful
contributions over a period of time will be offered committership!</p>
<p>Please do not forget to write <link
href="http://www.junit.org/">JUnit</link> test cases and documentation!
We won't accept code that doesn't come with test cases. And please
consider that other contributors should be able to understand your source
code easily. If you need any help getting started with JUnit test cases
for HWPF, please ask on the developers' mailing list! If you show that you
are prepared to stick at it you will most likely be given SVN commit
access. See <link href="../guidelines.html">"Contribution to POI" page</link>
for more details and help getting started.</p>
<p>Of course we will help you as best as we can. However, presently there
is no committer who is really familiar with the Word format, so you'll be
mostly on your own. We are looking forward for you and your contributions!
Honor and glory of becoming a POI committer are waiting!</p>
</section>
</body>
</document>
<!-- Keep this comment at the end of the file
Local variables:
mode: xml
sgml-omittag:nil
sgml-shorttag:nil
sgml-namecase-general:nil
sgml-general-insert-case:lower
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
sgml-parent-document:nil
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
-->

392
src/documentation/content/xdocs/hwpf/projectplan.xml Normal file
View File

@ -0,0 +1,392 @@
<?xml version="1.0"?>
<!--
====================================================================
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
====================================================================
-->
<!-- edited with XMLSPY v5 rel. 4 U (http://www.xmlspy.com) by Ryan Ackley (Myself) -->
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "../dtd/document-v11.dtd">
<document>
<header>
<title>Apache POI - HWPF - Java API to Handle Microsoft Word Files</title>
<subtitle>Project Plan</subtitle>
<authors>
<person name="Ryan Ackley" email="sackley@apache.org"/>
</authors>
</header>
<body>
<p>HWPF Milestones</p>
<table>
<tr>
<th>
Milestones
</th>
<th>
Target Date
</th>
<th>
Owner
</th>
</tr>
<tr>
<td>
Read in a Word document
with minimum formatting
(no lists, tables, footnotes,
endnotes, headers, footers)
and write it back out with the
result viewable in Word
97/2000
</td>
<td>
07/11/2003
</td>
<td>
Ryan
</td>
</tr>
<tr>
<td>
Add support for Lists and
Tables
</td>
<td>
8/15/2003
</td>
<td>
&#160;
</td>
</tr>
<tr>
<td>
HWPF 1.0-alpha release with
documentation and examples
</td>
<td>
8/18/2003
</td>
<td>
Praveen/Ryan
</td>
</tr>
<tr>
<td>
Add support for Headers,
Footers, endnotes, and
footnotes
</td>
<td>
8/31/2003
</td>
<td>
?
</td>
</tr>
<tr>
<td>
Add support for forms and
mail merge
</td>
<td>
September/October 2003
</td>
<td>
?
</td>
</tr>
</table>
<p>HWPF Task Lists</p>
<p>Read in a Word document with minimum formatting (no lists, tables, footnotes,
endnotes, headers, footers) and write it back out with the result viewable in Word 97/2000</p>
<table>
<tr>
<th>
Task
</th>
<th>
Target Date
</th>
<th>
Owner
</th>
</tr>
<tr>
<td>
Create classes to read and
write low level data
structures with test cases
</td>
<td>
7/10/2003
</td>
<td>
Ryan
</td>
</tr>
<tr>
<td>
Create classes to read and
write FontTable and Font
names with test case
</td>
<td>
7/10/2003
</td>
<td>
Praveen
</td>
</tr>
<tr>
<td>
Final test
</td>
<td>
7/11/2003
</td>
<td>
Ryan
</td>
</tr>
</table>
<p>Develop user friendly API so it is fun and easy to read and write word documents
with java.</p>
<table>
<tr>
<th>
Task
</th>
<th>
Target Date
</th>
<th>
Owner
</th>
</tr>
<tr>
<td>
Develop a way for SPRMS to
be compressed and
uncompressed
</td>
<td>
</td>
<td>
</td>
</tr>
<tr>
<td>
Override CHPAbstractType
with a concrete class that
exposes attributes with
human readable names
</td>
<td>
</td>
<td>
</td>
</tr>
<tr>
<td>
Override PAPAbstractType
with a concrete class that
exposes attributes with
human readable names
</td>
<td>
</td>
<td>
</td>
</tr>
<tr>
<td>
Override SEPAbstractType
with a concrete class that
exposes attributes with
human readable names
</td>
<td>
</td>
<td>
</td>
</tr>
<tr>
<td>
Override DOPAbstractType
with a concrete class that
exposes attributes with
human readable names
</td>
<td>
</td>
<td>
</td>
</tr>
<tr>
<td>
Override TAPAbstractType
with a concrete class that
exposes attributes with
human readable names
</td>
<td>
</td>
<td>
</td>
</tr>
<tr>
<td>
Override TCAbstractType
with a concrete class that
exposes attributes with
human readable names
</td>
<td>
</td>
<td>
</td>
</tr>
<tr>
<td>
Develop a VerifyIntegrity
class for testing so it is easy
to determine if a Word
Document is well-formed.
</td>
<td>
</td>
<td>
</td>
</tr>
<tr>
<td>
Develop general intuitive
API to tie everything together
</td>
<td>
</td>
<td>
</td>
</tr>
</table>
<p>Add support for lists and tables</p>
<table>
<tr>
<th>
Task
</th>
<th>
Target Date
</th>
<th>
Owner
</th>
</tr>
<tr>
<td>
Add data structures for
reading and writing list data
with test cases.
</td>
<td>
</td>
<td>
</td>
</tr>
<tr>
<td>
Add data structures for
reading and writing tables
with test cases.
</td>
<td>
</td>
<td>
</td>
</tr>
</table>
<p>HWPF 1.0-alpha release with documentation and examples</p>
<table>
<tr>
<th>
Task
</th>
<th>
Target Date
</th>
<th>
Owner
</th>
</tr>
<tr>
<td>
Document the user model
API
</td>
<td>
</td>
<td>
</td>
</tr>
<tr>
<td>
Document the low level
classes
</td>
<td>
</td>
<td>
</td>
</tr>
<tr>
<td>
Come up with detailed How-To&#8217;s
</td>
<td>
</td>
<td>
</td>
</tr>
</table>
</body>
</document>

88
src/documentation/content/xdocs/hwpf/quick-guide.xml Normal file
View File

@ -0,0 +1,88 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
====================================================================
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
====================================================================
-->
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "../dtd/document-v11.dtd">
<document>
<header>
<title>POI-HWPF - A Quick Guide</title>
<subtitle>Overview</subtitle>
<authors>
<person name="Nick Burch" email="nick at torchbox dot com"/>
</authors>
</header>
<body>
<p>HWPF is still in early development. It is in the <link
href="http://svn.apache.org/viewcvs.cgi/poi/trunk/src/scratchpad/">
scratchpad section of the SVN.</link> You will need to ensure you
either have a recent SVN checkout, or a recent SVN nightly build
(including the scratchpad jar!)</p>
<section><title>Basic Text Extraction</title>
<p>For basic text extraction, make use of
<code>org.apache.poi.hwpf.extractor.WordExtractor</code>. It accepts an input
stream or a <code>HWPFDocument</code>. The <code>getText()</code>
method can be used to
get the text from all the paragraphs, or <code>getParagraphText()</code>
can be used to fetch the text from each paragraph in turn. The other
option is <code>getTextFromPieces()</code>, which is very fast, but
tends to return things that aren't text from the page. YMMV.
</p>
</section>
<section><title>Specific Text Extraction</title>
<p>To get specific bits of text, first create a
<code>org.apache.poi.hwpf.HWPFDocument</code>. Fetch the range
with <code>getRange()</code>, then get paragraphs from that. You
can then get text and other properties.
</p>
</section>
<section><title>Headers and Footers</title>
<p>To get at the headers and footers of a word document, first create a
<code>org.apache.poi.hwpf.HWPFDocument</code>. Next, you need to create a
<code>org.apache.poi.hwpf.usermodel.HeaderStores</code>, passing it your
HWPFDocument. Finally, the HeaderStores gives you access to the headers and
footers, including first / even / odd page ones if defined in your
document. Additionally, HeaderStores provides a method for removing
any macros in the text, which is helpful as many headers and footers
do end up with macros in them.</p>
</section>
<section><title>Changing Text</title>
<p>It is possible to change the text via
<code>insertBefore()</code> and <code>insertAfter()</code>
on a <code>Range</code> object (either a <code>Range</code>,
<code>Paragraph</code> or <code>CharacterRun</code>).
It is also possible to delete a <code>Range</code>.
This code will work in many, but not all cases, and patches to
improve it are gratefully received!
</p>
</section>
<section><title>Further Examples</title>
<p>For now, the best source of additional examples is in the unit
tests. <link
href="http://svn.apache.org/viewvc/poi/trunk/src/scratchpad/testcases/org/apache/poi/hwpf/">
Browse the HWPF unit tests.</link>
</p>
</section>
</body>
</document>

176
src/documentation/content/xdocs/index.xml Normal file
View File

@ -0,0 +1,176 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
====================================================================
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
====================================================================
-->
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.3//EN" "./dtd/document-v13.dtd">
<document>
<header>
<title>Apache POI - the Java API for Microsoft Documents</title>
<authors>
<person id="AO" name="Andrew C. Oliver" email="acoliver@apache.org"/>
<person id="GJS" name="Glen Stampoultzis" email="user@poi.apache.org"/>
<person id="AS" name="Avik Sengupta" email="user@poi.apache.org"/>
<person id="RK" name="Rainer Klute" email="klute@apache.org"/>
<person id="DF" name="David Fisher" email="dfisher@jmlafferty.com"/>
</authors>
</header>
<body>
<section><title>Project News</title>
<section><title>19 September 2013 - POI 3.10 Beta 2 available</title>
<p>The Apache POI team is pleased to announce the release of 3.10 Beta 2. This primarily
includes a large number of bug fixes, and some enhancements (especially in the number of
Formula Functions supported).
</p>
<p>A full list of changes is available in the <link href="changes.html">change log</link>.
People interested should also follow the <link href="mailinglists.html">dev mailing list</link> to track further progress.</p>
<p>See the <link href="download.html">downloads</link> page for more details.</p>
</section>
<section><title>3 December 2012 - POI 3.9 available</title>
<p>The Apache POI team is pleased to announce the release of 3.9. This includes a large number of bug fixes, and some
enhancements (especially text extraction). See the
<link href="http://www.apache.org/dist/poi/release/RELEASE-NOTES.txt">release notes</link> for more details.
</p>
<p>A full list of changes is available in the <link href="changes.html">change log</link>.
People interested should also follow the <link href="mailinglists.html">dev mailing list</link> to track further progress.</p>
<p>See the <link href="download.html">downloads</link> page for more details.</p>
</section>
<section><title>28 August 2011 - The Apache POI project is celebrating its 10th anniversary</title>
<p>
The Apache POI project is celebrating its 10th anniversary. On the 28th of August 2001, the first 0.1 alpha version of POI was released.
<link href="https://blogs.apache.org/foundation/entry/the_apache_software_foundation_announces14">Read more...</link></p>
</section>
</section>
<section><title>Mission Statement</title>
<p>
The Apache POI Project's mission is to create and maintain Java APIs for manipulating various file formats
based upon the Office Open XML standards (OOXML) and Microsoft's OLE 2 Compound Document format (OLE2).
In short, you can read and write MS Excel files using Java.
In addition, you can read and write MS Word and MS PowerPoint files using Java. Apache POI is your Java Excel
solution (for Excel 97-2008). We have a complete API for porting other OOXML and OLE2 formats and welcome others to participate.
</p>
<p>
OLE2 files include most Microsoft Office files such as XLS, DOC, and PPT as well as MFC serialization API based file formats.
The project provides APIs for the <link href="poifs/index.html">OLE2 Filesystem (POIFS)</link> and
<link href="hpsf/index.html">OLE2 Document Properties (HPSF)</link>.
</p>
<p>
Office OpenXML Format is the new standards based XML file format found in Microsoft Office 2007 and 2008.
This includes XLSX, DOCX and PPTX. The project provides a low level API to support the Open Packaging Conventions
using <link href="oxml4j/index.html">openxml4j</link>.
</p>
<p>
For each MS Office application there exists a component module that attempts to provide a common high level Java api to both OLE2 and OOXML
document formats. This is most developed for <link href="spreadsheet/index.html">Excel workbooks (SS=HSSF+XSSF)</link>.
Work is progressing for <link href="hwpf/index.html">Word documents (HWPF+XWPF)</link> and
<link href="slideshow/index.html">PowerPoint presentations (HSLF+XSLF)</link>.
</p>
<p>
The project has recently added support for <link href="hsmf/index.html">Outlook (HSMF)</link>. Microsoft opened the specifications
to this format in October 2007. We would welcome contributions.
</p>
<p>
There are also projects for
<link href="hdgf/index.html">Visio (HDGF)</link>,
<link href="hmef/index.html">TNEF (HMEF)</link>,
and <link href="hpbf/index.html">Publisher (HPBF)</link>.
</p>
<p>
As a general policy we collaborate as much as possible with other projects to
provide this functionality. Examples include: <link href="http://xml.apache.org/cocoon">Cocoon</link> for
which there are serializers for HSSF;
<link href="http://www.openoffice.org">Open Office.org</link> with whom we collaborate in documenting the
XLS format; and <link href="http://tika.apache.org/">Tika</link> /
<link href="http://lucene.apache.org/">Lucene</link>,
for which we provide format interpretors. When practical, we donate
components directly to those projects for POI-enabling them.
</p>
<section><title>Why should I use Apache POI?</title>
<p>
A major use of the Apache POI api is for <link href="text-extraction.html">Text Extraction</link> applications
such as web spiders, index builders, and content management systems.
</p>
<p>
So why should you use POIFS, HSSF or XSSF?
</p>
<p>
You'd use POIFS if you had a document written in OLE 2 Compound Document Format, probably written using
MFC, that you needed to read in Java. Alternatively, you'd use POIFS to write OLE 2 Compound Document Format
if you needed to inter-operate with software running on the Windows platform. We are not just bragging when
we say that POIFS is the most complete and correct implementation of this file format to date!
</p>
<p>
You'd use HSSF if you needed to read or write an Excel file using Java (XLS). You'd use
XSSF if you need to read or write an OOXML Excel file using Java (XLSX). The combined
SS interface allows you to easily read and write all kinds of Excel files (XLS and XLSX)
using Java.
</p>
</section>
<section><title>Components</title>
<p>
The Apache POI Project provides several component modules some of which may not be of interest to you.
Use the information on our <link href="overview.html#components">Components</link> page to determine which
jar files to include in your classpath.
</p>
</section>
</section>
<section><title>Contributing </title>
<p>
So you'd like to contribute to the project? Great! We need enthusiastic, hard-working, talented folks to help
us on the project. So if you're motivated, ready, and have the time time download the source from the
<link href="subversion.html">Subversion Repository</link>, <link href="howtobuild.html">build the code</link>,
join the <link href="mailinglists.html">mailing lists</link> and we'll be happy to help you get started on the project!
</p>
<p>
Please read our <link href="guidelines.html">Contribution Guidelines</link>. When your contribution is ready
submit a patch to our <link href="https://issues.apache.org/bugzilla/buglist.cgi?product=POI">Bug Database</link>.
</p>
</section>
</body>
<footer>
<legal>
Copyright (c) @year@ The Apache Software Foundation. All rights reserved.
<br />
Apache POI, POI, Apache, the Apache feather logo, and the Apache
POI project logo are trademarks of The Apache Software Foundation.
</legal>
</footer>
</document>
<!-- Keep this comment at the end of the file
Local variables:
mode: xml
sgml-omittag:nil
sgml-shorttag:nil
sgml-namecase-general:nil
sgml-general-insert-case:lower
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:2
sgml-indent-data:t
sgml-parent-document:nil
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
-->

100
src/documentation/content/xdocs/legal.xml Normal file
View File

@ -0,0 +1,100 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
====================================================================
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
====================================================================
-->
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.3//EN" "./dtd/document-v13.dtd">
<document>
<header>
<title>Apache POI - Legal Stuff</title>
<authors>
<person id="TK" name="Tetsuya Kitahata" email="tetsuya@apache.org"/>
<person id="DF" name="David Fisher" email="dfisher@jmlafferty.com"/>
</authors>
</header>
<body>
<section><title>License and Notice</title>
<p>
Apache POI releases are available under the <link href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0.</link>
See the NOTICE file contained in each release artifact for applicable copyright attribution notices. Release artifacts are available
from the <link href="download.html">Download</link> page.
</p>
</section>
<section><title>Copyrights and Trademarks</title>
<p>
All material on this website is Copyright &#169; 2002-2010, The Apache
Software Foundation.
</p>
<p>
Apache POI, POI, Apache, the Apache feather logo, and the Apache POI
project logo are trademarks of The Apache Software Foundation.
</p>
<p>
Sun, Sun Microsystems, Solaris, Java, JavaServer Web Development Kit,
and JavaServer Pages are trademarks or registered trademarks of Sun
Microsystems, Inc. UNIX is a registered trademark in the United States
and other countries, exclusively licensed through 'The Open Group'.
Microsoft, Windows, WindowsNT, Excel, Word, PowerPoint, Viso, Publisher, Outlook,
and Win32 are registered trademarks of Microsoft Corporation.
Linux is a registered trademark of Linus Torvalds.
All other product names mentioned herein and throughout the entire
web site are trademarks of their respective owners.
</p>
<section><title>Cryptography Notice</title>
<p>
This distribution includes cryptographic software. The country in
which you currently reside may have restrictions on the import,
possession, use, and/or re-export to another country, of
encryption software. BEFORE using any encryption software, please
check your country's laws, regulations and policies concerning the
import, possession, or use, and re-export of encryption software, to
see if this is permitted. See
<link href="http://www.wassenaar.org/">http://www.wassenaar.org/</link>
for more information.
</p>
<p>
The U.S. Government Department of Commerce, Bureau of Industry and
Security (BIS), has classified this software as Export Commodity
Control Number (ECCN) 5D002.C.1, which includes information security
software using or performing cryptographic functions with asymmetric
algorithms. The form and manner of this Apache Software Foundation
distribution makes it eligible for export under the License Exception
ENC Technology Software Unrestricted (TSU) exception (see the BIS
Export Administration Regulations, Section 740.13) for both object
code and source code.
</p>
<p>
The cryptographic software used is from <em>java.security</em> and
<em>javax.crypto</em> and is used when processing encrypted and
protected documents.
</p>
</section>
</section>
</body>
<footer>
<legal>
Copyright (c) @year@ The Apache Software Foundation All rights reserved.
<br />
Apache POI, POI, Apache, the Apache feather logo, and the Apache
POI project logo are trademarks of The Apache Software Foundation.
</legal>
</footer>
</document>

99
src/documentation/content/xdocs/mailinglists.xml Normal file
View File

@ -0,0 +1,99 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
====================================================================
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
====================================================================
-->
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.3//EN" "./dtd/document-v13.dtd">
<document>
<header>
<title>Mailing Lists</title>
<authors>
<person id="NB" name="Nick Burch" email="nick@apache.org"/>
</authors>
</header>
<body>
<section><title>Mailing Lists - Guidelines</title>
<p>
<strong>Before subscribing to any of the mailing lists, please make
sure that you have read and understand the following
guidelines:</strong>
</p>
<ul>
<li><link href="http://www.apache.org/foundation/mailinglists.html">ASF guide to Mailing Lists</link></li>
<li><link href="http://www.apache.org/dev/contrib-email-tips.html">ASF Tips for email contributors</link></li>
<li><link href="http://jakarta.apache.org/site/mail.html">The Jakarta guide to Mailing Lists</link></li>
</ul>
</section>
<section><title>Lists</title>
<section><title>The POI User List</title>
<p>
<strong>Medium Traffic</strong>
<link href="mailto:user-subscribe@poi.apache.org">Subscribe</link>
<link href="mailto:user-unsubscribe@poi.apache.org">Unsubscribe</link>
<link href="http://mail-archives.apache.org/mod_mbox/poi-user/">Archive</link>
<link href="http://news.gmane.org/thread.php?group=gmane.comp.jakarta.poi.user">gmane.org</link>
</p>
<p>
This list is for users of POI to ask questions, share knowledge,
and discuss issues. POI developers are also expected to be
lurking on this list to offer support to users of POI.
</p>
</section>
<section><title>The POI Developer List</title>
<p>
<strong>Low Traffic</strong>
<link href="mailto:dev-subscribe@poi.apache.org">Subscribe</link>
<link href="mailto:dev-unsubscribe@poi.apache.org">Unsubscribe</link>
<link href="http://mail-archives.apache.org/mod_mbox/poi-dev/">Archive</link>
<link href="http://news.gmane.org/gmane.comp.jakarta.poi.devel">gmane.org</link>
</p>
<p>
This is the list where participating developers of the POI
project meet and discuss issues, code changes/additions, etc.
Subscribers to this list also get notices of each and every
code change, build results, testing notices, etc.
<strong>Do not send mail to this list with usage questions or
configuration problems.</strong>
</p>
</section>
<section><title>The POI General List</title>
<p>
<strong>Low Traffic</strong>
<link href="mailto:general-subscribe@poi.apache.org">Subscribe</link>
<link href="mailto:general-unsubscribe@poi.apache.org">Unsubscribe</link>
<link href="http://mail-archives.apache.org/mod_mbox/poi-general/">Archive</link>
</p>
<p>
This list exists for general discussions on POI, not specific to
code or problems with code. Used for discussion of general matters
relating to all of the POI project, such as the website and
changes in procedures.
</p>
</section>
</section>
</body>
<footer>
<legal>
Copyright (c) @year@ The Apache Software Foundation. All rights reserved.
<br />
Apache POI, POI, Apache, the Apache feather logo, and the Apache
POI project logo are trademarks of The Apache Software Foundation.
</legal>
</footer>
</document>

57
src/documentation/content/xdocs/mirrors.xml Normal file
View File

@ -0,0 +1,57 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
====================================================================
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
====================================================================
-->
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.3//EN" "./dtd/document-v13.dtd">
<document>
<header>
<title>Apache POI Mirror Site</title>
<authors>
<person id="AO" name="Andrew C. Oliver" email="acoliver@apache.org"/>
</authors>
</header>
<body>
<section><title>Mirrors</title>
<p>
These are mirrors of the
<link href="http://poi.apache.org/">POI</link> website.
If you know of others...report them! :-)
</p>
</section>
<section><title>Austria</title>
<ul>
<li><link href="http://gd.tuwien.ac.at/infosys/servers/http/apache-jakarta-site/poi/index.html">Austrian Mirror of Jakarta POI</link></li>
</ul>
</section>
<section><title>Korea</title>
<ul>
<li><link href="http://jakarta.ktech21.co.kr/">Jakarta site partially translated into Korean and Mirrored</link></li>
</ul>
</section>
</body>
<footer>
<legal>
Copyright (c) @year@ The Apache Software Foundation All rights reserved.
<br />
Apache POI, POI, Apache, the Apache feather logo, and the Apache
POI project logo are trademarks of The Apache Software Foundation.
</legal>
</footer>
</document>

233
src/documentation/content/xdocs/news.xml Normal file
View File

@ -0,0 +1,233 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
====================================================================
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
====================================================================
-->
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.3//EN" "./dtd/document-v13.dtd">
<document>
<header>
<title>Apache POI - In the News over the world</title>
<authors>
<person id="AO" name="Andrew C. Oliver" email="acoliver@apache.org"/>
<person id="TK" name="Tetsuya Kitahata" email="tetsuya@apache.org"/>
</authors>
</header>
<body>
<section><title>POI in the news</title>
<p>
These are articles/etc. posted about POI around the web. If you
see POI in the news or mentioned at least somewhat prominently
on a site (not your homepage that you put the work POI on in
order to get us to link you and by the why here is a picture of
your wife in kids) then send a patch to the list. In general
equal time will be given so please feel free to send inflamatory
defamation as well as favorable, technical and factual. Really
stupid things won't be mentioned (sorry).
</p>
</section>
<section><title>English</title>
<ul>
<li>
<link href="http://archive.midrange.com/web400/200204/msg00023.html">Discussion about using POI on AS/400s</link>
</li>
<li>
<link href="http://www.somelist.com/mails/23819.html">Discussion from back when we almost had POI as the filter for KOffice if politics and licenses hadn't killed iit</link>
</li>
<li>
<link href="http://www.oreillynet.com/pub/wlg/1552?page=last&amp;x-showcontent=text">Java discussion on O'Reilly Network including discussion about POI</link> - O'Reilly.net
</li>
<li>
<link href="http://www.rollerweblogger.org/page/roller/20020715">Poor Obfuscation Implementation.</link> - Blog of David M. Johnson
</li>
<li>
<link href="http://www.jsurfer.org/article.php?sid=322">
POI 1.5-dev-rc2 released </link> - JSurfer
</li>
<li>
<link href="http://directory.google.com/Top/Computers/Programming/Languages/Java/Class_Libraries/Data_Formats/Microsoft_Formats/"> Google says we're the most important in our category </link>
</li>
<li>
<link href="http://www.javaworld.com/javaworld/javaqa/2002-05/01-qa-0503-excel3.html">It's POI-fect</link> - Tony Sintes, Javaworld
</li>
<li>
<link href="http://www.need-a-cake.com/categories/cocoonWeblog/2002/03/07.html">
Nicola announces POI serialization code
</link> - Matthew Langham's Radio Weblog
</li>
<li>
<link href="http://javalobby.org/discussionContext/showThreaded/frm/javalobby?folderId=20&amp;discussionContextId=11523">
Jakarta POI 1.4583 Released</link> - JavaLobby
</li>
<li>
<link href="http://javalobby.org/discussionContext/showThreaded/frm/javalobby?discussionContextId=11442&amp;folderId=20">
POI project moves to Jakarta (OLE 2 CDF/Excel/Word in
pure java)</link> - JavaLobby
</li>
<li>
<link
href="http://www.geocities.com/marcoschmidt.geo/java-image-coding.html">
List of Java libraries to read and write image and document files
</link> Marco Schmidt's homepage (normally we wouldn't
feature someone's homepage but its an extensive list of
information including "alternatives to POI" (for those
of you who are very wealthy). But heck I think I'll
bookmark his page for myself since he's like got every
piece of info known to man linked or featured on it!
</li>
<li>
<link href="http://radio.weblogs.com/0101350/">
The Experiences of an Operator (M&#229;ns af Klercker)
</link> - radio.weblogs.com
</li>
<li>
<link href="http://dataconv.org/apps_office.html">
DATACONV - Data Conversion Tools: Office
</link> DATACONV
</li>
<li>
<link href="http://chicago.sourceforge.net/devel/">
Chicago Developer Page
</link>
</li>
<li>
<link href="http://www.onjava.com/pub/d/1157">
POI/POI Serialization Project
</link> - Man you know you've hit the bigtime when
O'Reilly Likes you.. ;-)
</li>
<li>
<link
href="http://www.javaworld.com/netnews/index.shtml">
News Around the Net
</link> - Java World
</li>
</ul>
</section>
<section><title>Nederlandstalige (Dutch)</title>
<ul>
<li>
<link
href="http://www.ster.be/java/java9.html">
Een Excel-werkboek maken vanuit Java - Lieven Smits
</link>
</li>
</ul>
</section>
<section><title>Deutsch (German)</title>
<ul>
<li> <link
href="http://www.entwickler.com/itr/news/show.php3?id=6132&amp;nodeid=82 ">Apache POI verffentlicht</link> - entwicker.com
</li>
<li>
<link
href="http://www.jsp-develop.de/newsletter/10/">
Apache Jakarta-Projekt bringt Word und Excel in die Java-Welt </link> - jsp-develop.de (for the misguided who use JSP ;-) )
</li>
<li>
<link
href="http://www.entwickler.com/news/2002/02/5718/news.shtml">
Neues Apache-Projekt bringt Word- und Excel nach Java
</link> - entwickler.com
</li>
</ul>
</section>
<section><title>Espa&#241;ol (Spanish)</title>
<ul>
<li>
<link href="http://www.javahispano.com/noticias/todas.jsp">
OLE2 desde Java nativo
</link> - javaHispano
</li>
<li>
<link href="http://p2p.wrox.com/archive/java_espanol/2002-08/3.asp">Spanish discussion about Excel and Java including POI from Wrox forums</link>
</li>
</ul>
</section>
<section><title>Fran&#231;ais (French)</title>
<ul>
<li>
<link href="http://linuxfr.org/section/D%E9veloppeur,0,1,8,0.html">
Excel/OLE accessibles
</link> - Da Linux French Page
</li>
<li>
<link href="http://www.sogid.com/javalist/f2002/traiter_word_java.html">Discussion on POI in French</link>
</li>
</ul>
</section>
<section><title>Nihongo (Japanese)</title>
<ul>
<li>
<link href="http://drpanda.freezope.org/Memo/docs/jakarta/poi/poi_sample">100% PureJava...</link> - Dr. Panda Portal
</li>
<li>
<link
href="http://www.gimlay.org/~andoh/java/javanew.html">
What's new with java?
</link> - gimlay.org
</li>
<li><link href="http://taka-2.com/jclass/POI/">Java de Excel</link> - How to use Japanese with POI</li>
<li><link href="http://www.tech-arts.co.jp/macosx/webobjects-jp/htdocs/3200/3218.html">Various discussion in Japanese including on POI</link></li>
<li><link href="http://muimi.com/j/jakarta/">Japanese resources on Jakarta projects including POI</link></li>
<li><link href="http://www.fk.urban.ne.jp/home/kishida/">Kishida's site</link> -- Weekly Forte Lectures -- includes a snip about POI and Japanese.</li>
</ul>
</section>
<section><title>Russkii Yazyk (Russian)</title>
<ul>
<li>
<link href="http://www.nestor.minsk.by/kg/kg02/21/kg22108.html">
Probably a translation of the Javalobby announcement of 1.5-final
</link> -- Computer News (What's New)
</li>
</ul>
</section>
<section><title>Hangul (Korean)</title>
<ul>
<li>
<link href="http://www.javabrain.co.kr/AnswerView?questionId=1189&amp;categoryId=8">Various discussion in Korean about Excel output/APIs including POI</link>
</li>
</ul>
</section>
<section><title>No freaking idea</title>
<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>
<ul>
<li>
<link
href="http://www.javacentrix.com/index.htm">
If I had to guess, I'd say this is Thai, but
maybe you actually know</link> - javacentrix.com
</li>
</ul>
</section>
</body>
<footer>
<legal>
Copyright (c) @year@ The Apache Software Foundation All rights reserved.
<br />
Apache POI, POI, Apache, the Apache feather logo, and the Apache
POI project logo are trademarks of The Apache Software Foundation.
</legal>
</footer>
</document>

37
src/documentation/content/xdocs/news/book.xml Normal file
View File

@ -0,0 +1,37 @@
<?xml version="1.0"?>
<!--
====================================================================
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
====================================================================
-->
<!DOCTYPE book PUBLIC "-//APACHE//DTD Cocoon Documentation Book V1.0//EN" "../dtd/book-cocoon-v10.dtd">
<book software="POI Project"
title="POI Project News Pages"
copyright="@year@ POI Project">
<menu label="Navigation">
<menu-item label="Main" href="../index.html"/>
</menu>
<menu label="News">
<menu-item label="Logo Submissions" href="logocontest.html"/>
</menu>
</book>

194
src/documentation/content/xdocs/news/logocontest.xml Normal file
View File

@ -0,0 +1,194 @@
<?xml version="1.0" encoding="ISO-8859-1"?>
<!--
====================================================================
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
====================================================================
-->
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "document-v11.dtd">
<document>
<header>
<title></title>
<authors>
<person id="AO" name="Andrew C. Oliver" email="acoliver@apache.org"/>
<person id="GS" name="Glen Stampoultzis" email="user@poi.apache.org"/>
</authors>
</header>
<body>
<section><title>POI logos</title>
<p>
Here are the current logo submissions. Thanks to the artists!
</p>
<section><title>Michael Mosmann</title>
<p>
<img alt="logo" src="images/logoMichaelMosmann.png"/>
</p>
</section>
<section><title>Loïc Lefèvre</title>
<p>
<img alt="logo" src="images/logoLoicLefevre.png"/>&nbsp;&nbsp;&nbsp;
<img alt="logo" src="images/logoLoicLefevre2.png"/>
</p>
</section>
<section><title>Glen Stampoultzis</title>
<p>
<img alt="logo" src="images/logoGlenStampoutlzis.png"/>
</p>
</section>
<section><title>Marcus Gustafsson</title>
<p>
<img alt="logo" src="images/logoGustafsson1.png"/>&nbsp;&nbsp;&nbsp;
<img alt="logo" src="images/logoGustafsson2.png"/>
</p>
</section>
<section><title>Adrianus Handoyo</title>
<p>
<img alt="logo" src="images/logoAdria1.png"/>&nbsp;&nbsp;&nbsp;
<img alt="logo" src="images/logoAdria2.png"/>&nbsp;&nbsp;&nbsp;
<img alt="logo" src="images/logoAdria3.png"/>
</p>
</section>
<section><title>RussellBeattie</title>
<p>
<img alt="logo" src="images/logoRussellBeattie1.png"/>&nbsp;&nbsp;&nbsp;
<img alt="logo" src="images/logoRussellBeattie2.png"/>&nbsp;&nbsp;&nbsp;
<img alt="logo" src="images/logoRussellBeattie3.png"/>
</p>
<p>
<img alt="logo" src="images/logoRussellBeattie4.png"/>&nbsp;&nbsp;&nbsp;
<img alt="logo" src="images/logoRussellBeattie5.png"/>
</p>
</section>
<section><title>Daniel Fernandez</title>
<p>
<img alt="logo" src="images/logoDanielFernandez.png"/>
</p>
</section>
<section><title>Andrew Clements</title>
<p>
<img alt="logo" src="images/logoAndrewClements.png"/>&nbsp;&nbsp;&nbsp;
<img alt="logo" src="images/logoAndrewClements2.png"/>
</p>
</section>
<section><title>Wendy Wise</title>
<p>
<img alt="logo" src="images/logoWendyWise.png"/>&nbsp;&nbsp;&nbsp;
<img alt="logo" src="images/logoWendyWise2.png"/>
</p>
</section>
<section><title>Nikhil Karmokar</title>
<p>
<img alt="logo" src="images/logoKarmokar1.png"/>&nbsp;&nbsp;&nbsp;
<img alt="logo" src="images/logoKarmokar1s.png"/>
</p>
<p>
<img alt="logo" src="images/logoKarmokar2.png"/>&nbsp;&nbsp;&nbsp;
<img alt="logo" src="images/logoKarmokar2s.png"/>
</p>
<p>
<img alt="logo" src="images/logoKarmokar3.png"/>&nbsp;&nbsp;&nbsp;
<img alt="logo" src="images/logoKarmokar3s.png"/>
</p>
<p>
<img alt="logo" src="images/logoKarmokar4.png"/>&nbsp;&nbsp;&nbsp;
<img alt="logo" src="images/logoKarmokar4s.png"/>
</p>
<p>
<img alt="logo" src="images/logoKarmokar5.png"/>&nbsp;&nbsp;&nbsp;
<img alt="logo" src="images/logoKarmokar5s.png"/>
</p>
<p>
<img alt="logo" src="images/logoKarmokar6.png"/>&nbsp;&nbsp;&nbsp;
<img alt="logo" src="images/logoKarmokar6s.png"/>
</p>
</section>
<section><title>Lieven Janssen</title>
<p>
<img alt="logo" src="images/logoJanssen1.png"/>&nbsp;&nbsp;&nbsp;
<img alt="logo" src="images/logoJanssen2.png"/>
</p>
</section>
<section><title>RaPi GmbH</title>
<p>
Contact Person: Fancy at: fancy at my-feiqi.com
</p>
<p>
<img alt="logo" src="images/logoRaPiGmbH1.png"/>&nbsp;&nbsp;&nbsp;
<img alt="logo" src="images/logoRaPiGmbH2.png"/>
</p>
<p>
<img alt="logo" src="images/logoRaPiGmbH5.png"/>
</p>
<p>
<img alt="logo" src="images/logoRaPiGmbH6.png"/>
</p>
<p>
<img alt="logo" src="images/logoRaPiGmbH7.png"/>
</p>
<p>
<img alt="logo" src="images/logoRaPiGmbH8.png"/>
</p>
<p>
<img alt="logo" src="images/logoRaPiGmbH9.png"/>
</p>
<p>
<img alt="logo" src="images/logoRaPiGmbH10.png"/>
</p>
<p>
<img alt="logo" src="images/logoRaPiGmbH11.png"/>
</p>
<p>
<img alt="logo" src="images/logoRaPiGmbH12.png"/>
</p>
</section>
<section><title>Randy Stanard</title>
<p>
<img alt="logo" src="images/logoRandyStanard01.png"/>
</p>
<p>
<img alt="logo" src="images/logoRandyStanard02.png"/>
</p>
<p>
<img alt="logo" src="images/logoRandyStanard03.png"/>
</p>
<p>
<img alt="logo" src="images/logoRandyStanard04.png"/>
</p>
<p>
<img alt="logo" src="images/logoRandyStanard05.png"/>
</p>
<p>
<img alt="logo" src="images/logoRandyStanard06.png"/>
</p>
<p>
<img alt="logo" src="images/logoRandyStanard07.png"/>
</p>
<p>
<img alt="logo" src="images/logoRandyStanard08.png"/>
</p>
</section>
</section>
</body>
<footer>
<legal>
Copyright (c) @year@ The Apache Software Foundation All rights reserved.
<br />
Apache POI, POI, Apache, the Apache feather logo, and the Apache
POI project logo are trademarks of The Apache Software Foundation.
</legal>
</footer>
</document>

351
src/documentation/content/xdocs/overview.xml Normal file
View File

@ -0,0 +1,351 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
====================================================================
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
====================================================================
-->
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.3//EN" "./dtd/document-v13.dtd">
<document>
<header>
<title>Apache POI - Component Overview</title>
<authors>
<person id="AO" name="Andrew C. Oliver" email="acoliver@apache.org"/>
<person id="RK" name="Rainer Klute" email="klute@apache.org"/>
<person id="DF" name="David Fisher" email="dfisher@jmlafferty.com"/>
</authors>
</header>
<body>
<section><title>Apache POI Project Components</title>
<section><title>POIFS for OLE 2 Documents</title>
<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>
</section>
<section><title>HSSF and XSSF for Excel Documents</title>
<p>
HSSF is our port of the Microsoft Excel 97(-2007) file format (BIFF8) to pure
Java. XSSF is our port of the Microsoft Excel XML (2007+) file format (OOXML) to
pure Java. SS is a package that provides common support for both formats with a common API.
They both support read and write capability. Please see
<link href="./spreadsheet/index.html">the HSSF+XSSF project page</link> for more
information.
</p>
</section>
<section><title>HWPF and XWPF for Word Documents</title>
<p>
HWPF is our port of the Microsoft Word 97 (-2003) file format to pure
Java. It supports read, and limited write capabilities. It also provides
simple text extraction support for the older Word 6 and Word 95 formats.
Please see <link href="./hwpf/index.html">the HWPF project page for more
information</link>. This component remains in early stages of
development. It can already read and write simple files.
</p>
<p>
We are also working on the XWPF for the WordprocessingML (2007+) format from the
OOXML specification. This provides read and write support for simpler
files, along with text extraction capabilities.
</p>
</section>
<section><title>HSLF and XSLF for PowerPoint Documents</title>
<p>
HSLF is our port of the Microsoft PowerPoint 97(-2003) file format to pure
Java. It supports read and write capabilities. Please see <link
href="./slideshow/index.html">the HSLF project page for more
information</link>.
</p>
<p>
We are also working on the XSLF for the PresentationML (2007+) format from the
OOXML specification.
</p>
</section>
<section><title>HPSF for OLE 2 Document Properties</title>
<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
for application-specific purposes as well.
</p>
<p>
HPSF supports both reading and writing of properties.
</p>
<p>
Please see <link href="./hpsf/index.html">the HPSF project
page</link> for more information.
</p>
</section>
<section><title>HDGF for Visio Documents</title>
<p>
HDGF is our port of the Microsoft Viso 97(-2003) file format to pure
Java. It currently only supports reading at a very low level, and
simple text extraction. Please see <link
href="./hdgf/index.html">the HDGF project page for more
information</link>.
</p>
</section>
<section><title>HPBF for Publisher Documents</title>
<p>
HPBF is our port of the Microsoft Publisher 98(-2007) file format to pure
Java. It currently only supports reading at a low level for around
half of the file parts, and simple text extraction. Please see <link
href="./hpbf/index.html">the HPBF project page for more
information</link>.
</p>
</section>
<section><title>HMEF for TNEF (winmail.dat) Outlook Attachments</title>
<p>
HMEF is our port of the Microsoft TNEF (Transport Neutral Encoding
Format) file format to pure Java. TNEF is sometimes used by Outlook
for encoding the message, and will typically come through as
winmail.dat. HMEF currently only supports reading at a low level, but
we hope to add text and attachment extraction shortly. Please see <link
href="./hmef/index.html">the HMEF project page for more
information</link>.
</p>
</section>
<section><title>HSMF for Outlook Messages</title>
<p>
HSMF is our port of the Microsoft Outlook message file format to pure
Java. It currently only some of the textual content of MSG files, and
some attachments. Further support and documentation is coming in slowly.
For now, users are advised to consult the unit tests for example use.
Please see <link href="./hsmf/index.html">the HPBF project page for more
information</link>.
</p>
<p>
Microsoft has recently added the Outlook file format to its OSP. More information
is now available making implementation of this API an easier task.
</p>
</section>
</section>
<section><title>What is it?</title>
<p>The Apache 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>
<p>Apache POI is also the master project for developing pure
Java ports of file formats based on Office Open XML (ooxml.)
OOXML is part of an ECMA / ISO standardisation effort. This
documentation is quite large, but you can normally find the bit you
need without too much effort!
<link href="http://www.ecma-international.org/publications/standards/Ecma-376.htm">ECMA-376 standard is here</link>,
and is also under the <link href="http://www.microsoft.com/interop/osp">Microsoft OSP</link>.
</p>
</section>
<section id="components"><title>Component Map</title>
<p>
The Apache POI distribution consists of support for many document file formats. This support is provided
in several Jar files. Not all of the Jars are needed for every format. The following tables
show the relationships between POI components, Maven repository tags, and the project's Jar files.
</p>
<table>
<tr>
<th>Component</th>
<th>Application type</th>
<th>Maven artifactId</th>
<th>Notes</th>
</tr>
<tr>
<td><link href="./poifs/index.html">POIFS</link></td>
<td>OLE2 Filesystem</td>
<td><em>poi</em></td>
<td>Required to work with OLE2 / POIFS based files</td>
</tr>
<tr>
<td><link href="./hpsf/index.html">HPSF</link></td>
<td>OLE2 Property Sets</td>
<td>poi</td>
<td>&nbsp;</td>
</tr>
<tr>
<td><link href="./spreadsheet/index.html">HSSF</link></td>
<td>Excel XLS</td>
<td>poi</td>
<td>For HSSF only, if common SS is needed see below</td>
</tr>
<tr>
<td><link href="./slideshow/index.html">HSLF</link></td>
<td>PowerPoint PPT</td>
<td>poi-scratchpad</td>
<td>&nbsp;</td>
</tr>
<tr>
<td><link href="./hwpf/index.html">HWPF</link></td>
<td>Word DOC</td>
<td>poi-scratchpad</td>
<td>&nbsp;</td>
</tr>
<tr>
<td><link href="./hdgf/index.html">HDGF</link></td>
<td>Visio VSD</td>
<td>poi-scratchpad</td>
<td>&nbsp;</td>
</tr>
<tr>
<td><link href="./hpbf/index.html">HPBF</link></td>
<td>Publisher PUB</td>
<td>poi-scratchpad</td>
<td>&nbsp;</td>
</tr>
<tr>
<td><link href="./hsmf/index.html">HSMF</link></td>
<td>Outlook MSG</td>
<td>poi-scratchpad</td>
<td>&nbsp;</td>
</tr>
<tr>
<td><link href="./oxml4j/index.html">OpenXML4J</link></td>
<td>OOXML</td>
<td>poi-ooxml plus one of<br />poi-ooxml-schemas, ooxml-schemas</td>
<td>Only one schemas jar is needed, see below for differences</td>
</tr>
<tr>
<td><link href="./spreadsheet/index.html">XSSF</link></td>
<td>Excel XLSX</td>
<td>poi-ooxml</td>
<td>&nbsp;</td>
</tr>
<tr>
<td><link href="./slideshow/index.html">XSLF</link></td>
<td>PowerPoint PPTX</td>
<td>poi-ooxml</td>
<td>&nbsp;</td>
</tr>
<tr>
<td><link href="./hwpf/index.html">XWPF</link></td>
<td>Word DOCX</td>
<td>poi-ooxml</td>
<td>&nbsp;</td>
</tr>
<tr>
<td><link href="./spreadsheet/index.html">Common SS</link></td>
<td>Excel XLS and XLSX</td>
<td>poi-ooxml</td>
<td>WorkbookFactory and friends all require poi-ooxml, not just core poi</td>
</tr>
</table>
<p><br /></p>
<p>
This table maps artifacts into the jar file name. "version-yyyymmdd" is
the POI version stamp. For the latest stable release it is
3.9-20121203
. For the latest beta release it is
3.10-beta2-20130904
.
</p>
<table>
<tr>
<th>Maven artifactId</th>
<th>Prerequisites</th>
<th>JAR</th>
</tr>
<tr>
<td>poi</td>
<td>commons-logging, commons-codec, log4j</td>
<td>poi-version-yyyymmdd.jar</td>
</tr>
<tr>
<td>poi-scratchpad</td>
<td>poi</td>
<td>poi-scratchpad-version-yyyymmdd.jar</td>
</tr>
<tr>
<td>poi-ooxml</td>
<td>poi, poi-ooxml-schemas, dom4j</td>
<td>poi-ooxml-version-yyyymmdd.jar</td>
</tr>
<tr>
<td>poi-ooxml-schemas</td>
<td>xmlbeans, stax-api-1.0.1</td>
<td>poi-ooxml-schemas-version-yyyymmdd.jar</td>
</tr>
<tr>
<td>poi-examples</td>
<td>poi, poi-scratchpad, poi-ooxml</td>
<td>poi-examples-version-yyyymmdd.jar</td>
</tr>
<tr>
<td>ooxml-schemas</td>
<td>xmlbeans, stax-api-1.0.1</td>
<td>ooxml-schemas-1.1.jar</td>
</tr>
</table>
<p>&nbsp;</p>
<p>
poi-ooxml requires poi-ooxml-schemas. This is a substantially smaller
version of the ooxml-schemas jar (ooxml-schemas-1.1.jar for POI 3.7 or
later, ooxml-scheams-1.0.jar for POI 3.5 and 3.6).
The larger ooxml-schemas jar is <link href="faq.html">normally</link>
only required for development
</p>
<p>
The OOXML jars require a stax implementation. The "stax-api-1.0.1" jar
should normally be used (it is recommended for compatibility with other
Apache projects), though any compliant implementation should work fine though.
</p>
</section>
<section><title>Examples</title>
<p>
Small sample programs using the POI API are available in the
<em>src/examples</em> directory of the source distribution. Before
studying the source code you might want to have a look at the
"Examples" section of the <link href="apidocs/overview-summary.html">POI API
documentation</link>.
</p>
<section><title>POI Browser</title>
<p>
The POI Browser is a very simple Swing GUI tool that displays the
internal structure of a Microsoft Office file and especially the
property set streams. Further information and instructions how to
execute it can be found in the <link
href="http://svn.apache.org/repos/asf/poi/trunk/src/examples/src/org/apache/poi/poifs/poibrowser/POIBrowser.java">POI
source code</link>.
</p>
</section>
<p>
All of the examples are inclided in POI distributions as a poi-examples artifact.
</p>
</section>
<section><title>Contributed Software</title>
<p>
Besides the "official" components outlined above there is some further
software distributed with POI. This is called "contributed" software. It
is not explicitly recommended or even maintained by the POI team, but
it might still be useful to you.
</p>
<p>
See <link href="poi-ruby.html">POI Ruby Bindings</link> and other code in the
<link
href="http://svn.apache.org/repos/asf/poi/trunk/src/contrib/">poi-contrib module</link>
</p>
</section>
</body>
<footer>
<legal>
Copyright (c) @year@ The Apache Software Foundation. All rights reserved.
<br />
Apache POI, POI, Apache, the Apache feather logo, and the Apache
POI project logo are trademarks of The Apache Software Foundation.
</legal>
</footer>
</document>

34
src/documentation/content/xdocs/oxml4j/book.xml Normal file
View File

@ -0,0 +1,34 @@
<?xml version="1.0"?>
<!--
====================================================================
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
====================================================================
-->
<!DOCTYPE book PUBLIC "-//APACHE//DTD Cocoon Documentation Book V1.0//EN" "../dtd/book-cocoon-v10.dtd">
<book software="POI Project"
title="OpenXML4J"
copyright="@year@ POI Project">
<menu label="Apache POI">
<menu-item label="Top" href="../index.html"/>
</menu>
<menu label="OpenXML4J">
<menu-item label="Overview" href="index.html"/>
</menu>
</book>

42
src/documentation/content/xdocs/oxml4j/index.xml Normal file
View File

@ -0,0 +1,42 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
====================================================================
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
====================================================================
-->
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "../dtd/document-v11.dtd">
<document>
<header>
<title>POI-OpenXML4J - Java API To Access Office Open XML documents</title>
<subtitle>Overview</subtitle>
</header>
<body>
<section>
<title>Overview</title>
<p>OpenXML4J is the POI Project's pure Java implementation of the Open Packaging Conventions (OPC) defined in
<link href="http://www.ecma-international.org/publications/standards/Ecma-376.htm">ECMA-376</link>.</p>
<p>Every OpenXML file comprises a collection of byte streams called parts, combined into a container called a package.
POI OpenXML4J provides a physical implementation of the OPC that uses the Zip file format.</p>
</section>
<section>
<title>History</title>
<p>OpenXML4J was originally developed by <link href="http://openxml4j.org/">http://openxml4j.org/</link> and contributed to POI in 2008.
Thanks to the support and guidance of Julien Chable</p>
</section>
</body>
</document>

92
src/documentation/content/xdocs/patches.xml Normal file
View File

@ -0,0 +1,92 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
====================================================================
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
====================================================================
-->
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.3//EN" "./dtd/document-v13.dtd">
<!-- Is this being used? -->
<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</title>
<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.
These patches are not (yet) part of the POI project, but need reviewing for possible
inclusion. This system was instituted because, due to the large volume of mail and
the lack of time of the committers, some patches tended to get forgotten about. This
queue does not guarantee that any patch will be reviewed within a reasonable time frame,
but it does at least make them easier to find!
</p>
<p>
<strong>Reviewers wanted!</strong> - If you have time to review and/or test these patches,
we would be grateful for your time. Please post comments to the dev mailing lists.
</p>
<p>
Before submitting a patch, please read the page on
<link href="contrib.xml">Third-Party
Contributions</link>. 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 the unified diff format. This format is
created by the typical Subversion client when you execute the
<code>svn diff</code> command or the equivalent of it in a GUI environment.</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>
</section>
<section>
<title>Patch Queue</title>
<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
<link href="mail-archives.xml">mailing list archives.</link>
</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
<link href="todo.xml">To Do</link>.
</p>
</section>
</body>
</document>

521
src/documentation/content/xdocs/plan/POI10Vision.xml Normal file
View File

@ -0,0 +1,521 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
====================================================================
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
====================================================================
-->
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "document-v11.dtd">
<document>
<header>
<title>POI 1.0 Vision Document</title>
<authors>
<person name="Andrew C. Oliver" email="acoliver@apache.org"/>
<person name="Marcus W. Johnson" email="mjohnson@apache.org"/>
</authors>
</header>
<body>
<section><title>Preface</title>
<p>
(21-Jan-02) While this document is just full of useful project
introductory information and I do suggest those interested in getting
involved in the project read it, it is woefully out of date.
</p>
<p>
We deliberately allowed this document to run out of date because it
is a good reflection of what the original vision was for POI 1.0.
You'll note that some of the terminology is not used in quite the same
way any longer. I've made some minor corrections where reading this
confused me. An example: in some places this document may refer to
POI API instead of POIFS API. When this vision was written we had
an incomplete understanding of the project.
</p>
<p>
Lastly, the scope of the project expanded dramatically near the end
of the 1.0 cycle. Our vision at the time was to focus merely on the
Excel port (having no idea how the project would grow or be received)
and provide the OLE 2 Compound Document port for others to port later
formats. We now plan to spearhead these ports under the umbrella of
the POI project. So, you've been warned. Read on, but just realize
that we had a fuzzy view of things to come, and hindsight is 20-20.
</p>
<p>
If I recall major holes were: a complete understanding of the format
of OLE 2 Compound Document format, Excel file format, and exactly how
Cocoon 2 Serializers worked. (that just about covers the whole range
huh?)
</p>
</section>
<section><title>1. Introduction</title>
<section><title>1.1 Purpose of this document</title>
<p>
The purpose of this document is to
collect, analyze and define high-level requirements, user needs and
features of the HSSF Serializer for Cocoon 2 and related libraries.
The HSSF Serializer is a java class supporting the Serializer
interface from the Cocoon 2 project and outputting in a compatible
format of that used by the spreadsheet program Microsoft Excel '97.
The HSSF Serializer will be responsible for converting XML
spreadsheet-like documents into Excel-compatible XLS spreadsheets.
</p>
</section>
<section><title>1.2 Project Overview</title>
<p>
Many web apps today hit a brick wall
when it comes to the user request that they be able to easily
manipulate their reports and data extracts in the popular Microsoft
Excel spreadsheet format. This often causes inferior technologies to be
chosen for the project simply because they easily support this
format. This project seeks to extend existing XML, Java and Apache
Cocoon 2 project technologies by:
</p>
<ul>
<li>
providing an extensible library
(POIFS) which reads/writes in a compatable format to OLE 2 Compound
Document Format (aka Structured Storage Format) for easy
implementation of other document types;
</li>
<li>
providing a library (HSSF) for
manipulating spreadsheet data and outputting it in a compatible
format to Microsoft Excel XLS format;
</li>
<li>
and providing a Cocoon 2
Serializer (HSSFSerializer) for serializing XML documents as
Excel-compatible spreadsheets.
</li>
</ul>
</section>
</section>
<section><title>2. User Description</title>
<section><title>2.1 User/Market Demographics</title>
<p>
There are a number of enthusiastic
users of XML, UNIX and Java technology. Secondly, the Microsoft
solution for outputting Office Document formats often involves
actually manipulating the software as an OLE Server. This method
provides extremely low performance, extremely high overhead and is
only capable of handling one document at a time.
</p>
<ol>
<li>
Our intended audience for the HSSF
Serializer portion of this project are developers writing reports or
data extracts in XML format.
</li>
<li>
Our intended audience for the HSSF
library portion of this project is ourselves as we are developing
the Serializer and anyone who needs to write to Excel spreadsheets
in a non-XML Java environment or who has specific needs not
addressed by the Serializer.
</li>
<li>
Our intended audience for the
&quot;POIFS&quot; OLE 2 Compound Document format reader/writer is
ourselves as we are writing the HSSF library and secondly, anyone
wishing to provide other libraries for reading/writing OLE 2
Compound Document Format in Java.
</li>
</ol>
</section>
<section><title>2.2. User environment</title>
<p>
The users of this software shall be
developers in a Java environment on any Operating System or power
users who are capable of XML document generation/deployment.
</p>
</section>
<section><title>2.3. Key User Needs</title>
<p>
The OLE 2 Compound Document format is
undocumented for all practical purposes and cryptic for all
impractical purposes. Developer needs in this area include
documentation and an easy to use library for reading and writing in
this format without requiring the developer to have intimate
knowledge of the format.
</p>
<p>
There is currently no good way to write
to Microsoft Excel documents from Java or from a non-Microsoft
Windows based platform for that matter. Developers need an easy to
use library that supports a reasonable feature set and allows
seperation of data from formatting/stylistic concerns.
</p>
<p>
There is currently no good way to
transform XML data to Microsoft Excel. Apache's Cocoon 2 project
supplies a complete framework for XML, but nothing for outputting in
Excel's XLS format. Developers and power users alike need a simple
method to output XML documents to Excel through server-side
processing.
</p>
</section>
</section>
<section><title>3. Project Overview</title>
<section><title>3.1. Project Perspective</title>
<p>
The produced code shall be licensed by
the Apache License as used by the Cocoon 2 project and maintained on
a project page until such time as the Cocoon 2 developers accept it
as a donation (at which time the copyright will be turned over to
them).
</p>
</section>
<section><title>3.2. Project Position Statement</title>
<p>
For developers on a Java and/or XML
environment this project will provide all the tools necessary for
outputting XML data in the Microsoft Excel format. This project seeks
to make the use of Microsoft Windows based servers unnecessary for
file format considerations and to fully document the OLE 2 Compound
Document format. The project aims not only to provide the tools for
serializing XML to Excel's file format and the tools for writing to
that file format from Java, but also to provide the tools for later
projects to convert other OLE 2 Compound Document formats to pure
Java APIs.
</p>
</section>
<section><title>3.3. Summary of Capabilities</title>
<p>
HSSF Serializer for Apache Cocoon 2
</p>
<table>
<tr>
<td>
Benefit
</td>
<td>
Supporting Features
</td>
</tr>
<tr>
<td>
Standard XML tag language for sheet data
</td>
<td>
Serializer will transform documents utilizing a defined tag
language
</td>
</tr>
<tr>
<td>
Utilize XML to output in Excel
</td>
<td>
Serializer will output in Excel
</td>
</tr>
<tr>
<td>
Java API to output in Excel on any platform
</td>
<td>
The project will develop an API that outputs in Excel using
pure Java.
</td>
</tr>
<tr>
<td>
Make it easy for developers to port other OLE 2 Compound
Document-based formats to Java.
</td>
<td>
The POIFS library will contain both a high-level abstraction
along with low-level constructs. The project will fully document
the OLE 2 Compound Document Format.
</td>
</tr>
</table>
</section>
<section><title>3.4. Assumptions and Dependencies</title>
<ul>
<li>
The HSSF Serializer will run on
any Java 2 supporting platform with Apache Cocoon 2 installed along
with the HSSF and POIFS APIs.
</li>
<li>
The HSSF API requires a Java 2
implementation and the POI API.
</li>
<li>
The POIFS API requires a Java 2
implementation.
</li>
</ul>
</section>
</section>
<section><title>4. Project Features</title>
<p>
The POIFS API will include:
</p>
<ul>
<li>
Low level structures representing
the structures in a POI filesystems.
</li>
<li>
A low-level API for
creating/manipulating POI filesystems.
</li>
<li>
A set of high level interfaces
abstracting the user from the POI filesystem constructs and
representing it as a standard filesystem (Files, directories, etc)
</li>
</ul>
<p>
The HSSF API will include:
</p>
<ul>
<li>
Low level structures representing
the structures in an Excel file.
</li>
<li>
A low-level API for creating and
manipulating Excel files and writing them into POI filesystems.
</li>
<li>
A high level model and style
interface for manipulating spreadsheet data without knowing anything
about the Excel format itself.
</li>
</ul>
<section><title>4.1 POI Filesystem API</title>
<p>
The POI Filesystem API includes:
</p>
<ul>
<li>An implementation of Big Blocks</li>
<li>An implementation of Small Blocks</li>
<li>An implementation of Header Blocks</li>
<li>An implementation of Block Allocation Tables</li>
<li>An implementation of Property Sets</li>
<li>An implementation of the POI
filesystem including functions to get and set the above constructs;
compound functions for reading/writing files/directories.
</li>
<li>An abstraction of the POI
filesystem providing interfaces representing Files, Directories,
FileSystems in normal terminology and encapulating the above
constructs.
</li>
<li>Full documentation of the POI file
format.
</li>
<li>Full documentation of the APIs and
interfaces provided through Javadoc, user documentation (aimed at
developers using the APIs)
</li>
<li>Examples aimed at teaching the
user to write code using POI. (titled: recipes for POI)
</li>
<li>Performance specifications.
(Example POI filesystems rated by some measure of complexity along
with system specifications and execution times for given operations)
</li>
</ul>
</section>
<section><title>4.2 HSSF API</title>
<p>
The HSSF API includes:
</p>
<ul>
<li>An implementation of Record
(binary 2 byte type followed by 2 byte size (n) followed by n bytes)</li>
<li>Implementations of many standard
record types mapping the data bytes to fields along with methods to
reserialize those fields</li>
<li>An implementation of the HSSF File
including functions to get/set the above constructs, create a blank
file with the minimum required record types and mappings between
getting/setting data and style in a workbook to the creation of
record types, and read HSSF files.</li>
<li>An abstraction of the HSSF file
format providing interfaces representing the HSSF File, HSSF
Workbook, HSSF Sheet, HSSF Column, HSSF Formulas in a manner
seperating the data from the styling and encapsulating the above
constructs.</li>
<li>Full documentation of the HSSF
file format (which will be a subset of the Excel '97 File format).
This must be done with care for legal reasons.</li>
<li>Full documentation of the APIs and
interfaces provided through Javadoc, user documentation (aimed at
developers using the apis).</li>
<li>Examples aimed at teaching
developers to use the APIs.
</li>
<li>Performance specifications.
(Example files rated by some measure of complexity along with system
specifications and execution times for given operations - possibly
the same files used for POI's tests)</li>
</ul>
</section>
<section><title>4.3 HSSF Serializer</title>
<p>
The HSSF Serializer subproject:
</p>
<ul>
<li>A class supporting the Cocoon 2
Serializer Interface.</li>
<li>An interface between the SAX
events and the HSSF APIs.</li>
<li>A specified tag language for using
with the Serializer.</li>
<li>Documentation on the tag language
for the HSSF Serializer</li>
<li>Normal javadocs.</li>
<li>Example XML files</li>
<li>Performance specifications.
(Example XML docs and stylesheets rated by some measure of
complexity along with system specifications and execution times)</li>
</ul>
</section>
</section>
<section><title>5. Other Product Requirements</title>
<section><title>5.1. Applicable Standards</title>
<p>
All Java code will be 100% pure Java.
</p>
</section>
<section><title>5.2. System Requirements</title>
<p>
The minimum system requirements for POIFS are:
</p>
<ul>
<li>64 Mbytes memory</li>
<li>Java 2 environment</li>
<li>Pentium or better processor (or equivalent on other platforms)</li>
</ul>
<p>
The minimum system requirements for HSSF are:
</p>
<ul>
<li>64 Mbytes memory</li>
<li>Java 2 environment</li>
<li>Pentium or better processor (or equivalent on other platforms)</li>
<li>POIFS API</li>
</ul>
<p>
The minimum system requirements for the HSSF Serializer are:
</p>
<ul>
<li>64 Mbytes memory</li>
<li>Java 2 environment</li>
<li>Pentium or better processor (or equivalent on other platforms)</li>
<li>Cocoon 2</li>
<li>HSSF API</li>
<li>POI API</li>
</ul>
</section>
<section><title>5.3. Performance Requirements</title>
<p>
All components must perform well enough
to be practical for use in a webserver environment (especially
Cocoon2/Tomcat/Apache combo)
</p>
</section>
<section><title>5.4. Environmental Requirements</title>
<p>
The software will run primarily in
developer environments. We should make some allowances for
not-highly-technical users to write XML documents for the HSSF
Serializer. All other components will assume intermediate Java 2
knowledge. No XML knowledge will be required except for using the
HSSF Serializer. As much documentation as is practical shall be
required for all components as XML is relatively new, and the
concepts introduced for writing spreadsheets and to POI filesystems
will be brand new to Java and many Java developers.
</p>
</section>
</section>
<section><title>6. Documentation Requirements</title>
<section><title>6.1 POI Filesystem</title>
<p>
The filesystem as read and written by
POI shall be fully documented and explained so that the average Java
developer can understand it.
</p>
</section>
<section><title>6.2. POI API</title>
<p>
The POI API will be fully documented
through Javadoc. A walkthrough of using the high level POI API shall
be provided. No documentation outside of the Javadoc shall be
provided for the low-level POI APIs.
</p>
</section>
<section><title>6.3. HSSF File Format</title>
<p>
The HSSF File Format as implemented by
the HSSF API will be fully documented. No documentation will be
provided for features that are not supported by HSSF API that are
supported by the Excel 97 File Format. Care will be taken not to
infringe on any &quot;legal stuff&quot;.
</p>
</section>
<section><title>6.4. HSSF API</title>
<p>
The HSSF API will be documented by
javadoc. A walkthrough of using the high level HSSF API shall be
provided. No documentation outside of the Javadoc shall be provided
for the low level HSSF APIs.
</p>
</section>
<section><title>6.5. HSSF Serializer</title>
<p>
The HSSF Serializer will be documented
by javadoc.
</p>
</section>
<section><title>6.6 HSSF Serializer Tag language</title>
<p>
The XML tag language along with
function and usage shall be fully documented. Examples will be
provided as well.
</p>
</section>
</section>
<section><title>7. Terminology</title>
<section><title>7.1 Filesystem</title>
<p>
filesystem shall refer only to the POI formatted archive.
</p>
</section>
<section><title>7.2 File</title>
<p>
file shall refer to the embedded data stream within a
POI filesystem. This will be the actual embedded document.
</p>
</section>
</section>
</body>
</document>

594
src/documentation/content/xdocs/plan/POI20Vision.xml Normal file
View File

@ -0,0 +1,594 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
====================================================================
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
====================================================================
-->
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "document-v11.dtd">
<document>
<header>
<title>POI 2.0 Vision Document</title>
<authors>
<person name="Andrew C. Oliver" email="acoliver2@users.sourceforge.net"/>
<person name="Marcus W. Johnson" email="mjohnson@apache.org"/>
<person name="Glen Stampoultzis" email="user@poi.apache.org"/>
<person name="Nicola Ken Barozzi" email="barozzi@nicolaken.com"/>
</authors>
</header>
<body>
<section><title>Preface</title>
<p>
This is the POI 2.0 cycle vision document. Although the vision
has not changed and this document is certainly not out of date and
the vision has not changed, the structure of the project has
changed a bit. We're not going to change the vision document to
reflect this (however proper that may be) because it would only
involve deletion. There is no purpose in providing less
information provided we give clarification.
</p>
<p>
This document was created before the POI components for
<link href="http://xml.apache.org/cocoon">Apache Cocoon</link>
were accepted into the Cocoon project itself. It was also
written before POI was accepted into Jakarta. So while the
vision hasn't changed some of the components are actually now
part of other projects. We'll still be working on them on the
same timeline roughly (minus the overhead of coordination with
other groups), but they are no longer technically part of the
POI project itself.
</p>
</section>
<section><title>1. Introduction</title>
<section><title>1.1 Purpose of this document</title>
<p>
The purpose of this document is to
collect, analyze and define high-level requirements, user needs,
and features of the second release of the POI project software.
The POI project currently consists of the following components:
the HSSF Serializer, the HSSF library and the POIFS library.
</p>
<ul>
<li>
The HSSF Serializer is a set of Java classes whose main
class supports the Serializer interface from the Cocoon
2 project and outputs the serialized data in a format
compatible with the spreadsheet program Microsoft Excel
'97.
</li>
<li>
The HSSF library is a set of classes for reading and
writing Microsoft Excel 97 file format using pure Java.
</li>
<li>
The POIFS library is a set of classes for reading and
writing Microsoft's OLE 2 Compound Document format using
pure Java.
</li>
</ul>
<p>By the completion of this release cycle the POI project will also
include the HSSF Generator and the HWPF library.
</p>
<ul>
<li>The HSSF Generator will be responsible for using HSSF to read
in the XLS (Excel 97) file format and create SAX events. The HSSF
Generator will support the applicable interfaces specified by the
Apache Cocoon 2 project.
</li>
<li>The HWPF library will provide a set of high level interfaces
for reading and writing Microsoft Word 97 file format using pure
Java.</li>
</ul>
</section>
<section><title>1.2 Project Overview</title>
<p>
The first release of the POI project
was an astounding success. This release seeks to build on that
success by:
</p>
<ul>
<li>
Refactoring POIFS into imput and
output classes as well as an event-driven API for reading.
</li>
<li>
Refactor HSSF for greater
performance as well as an event-driven API for reading
</li>
<li>
Extend HSSF by adding the ability to read and write formulas.
</li>
<li>
Extend HSSF by adding the ability to read and write
user-defined styles.
</li>
<li>
Create a Cocoon 2 Generator for HSSF using the same tags
as the HSSF Serializer.
</li>
<li>
Create a new library (HWPF) for reading and writing
Microsoft Word DOC format.
</li>
<li>
Refactor the HSSFSerializer into a separate extensible
POIFSSerializer and HSSFSerializer
</li>
<li>
Providing the create excel charts. (write only)
</li>
</ul>
</section>
</section>
<section><title>2. User Description</title>
<section><title>2.1 User/Market Demographics</title>
<p>
There are a number of enthusiastic
users of XML, UNIX and Java technology. Furthermore, the Microsoft
solution for outputting Office Document formats often involves
actually manipulating the software as an OLE Server. This method
provides extremely low performance, extremely high overhead and is
only capable of handing one document at a time.
</p>
<ol>
<li>
Our intended audience for the HSSF
Serializer portion of this project are developers writing reports or
data extracts in XML format.
</li>
<li>
Our intended audience for the HSSF
library portion of this project is ourselves as we are developing
the HSSF serializer and anyone who needs to read and write Excel
spreadsheets in a non-XML Java environment, or who has specific
needs not addressed by the Serializer
</li>
<li>
Our intended audience for the
POIFS library is ourselves as we are developing the HSSF and HWPF
libraries and anyone wishing to provide other libraries for
reading/writing other file formats utilizing the OLE 2 Compound
Document Format in Java.
</li>
<li>
Our intended audience for the HSSF
generator are developers who need to export Excel spreadsheets to
XML in a non-proprietary environment.
</li>
<li>
Our intended audience for the HWPF
library is ourselves, as we will be developing a HWPF Serializer in a
later release, and anyone wishing to add .DOC file processing and
creation to their projects.
</li>
</ol>
</section>
<section><title>2.2. User environment</title>
<p>
The users of this software shall be
developers in a Java environment on any operating system, or power
users who are capable of XML document generation/deployment.
</p>
</section>
<section><title>2.3. Key User Needs</title>
<p>
The HSSF library currently requires a
full object representation to be created before reading values. This
results in very high memory utilization. We need to reduce this
substantially for reading. It would be preferable to do this for
writing, but it may not be possible due to the constraints imposed by
the file format itself. Memory utilization during read is our top
user complaint.
</p>
<p>
The POIFS library currently requires a
full object representation to be created before reading values. This
results in very high memory utilization. We need to reduce this
substantially for reading.
</p>
<p>
The HSSF library currently ignores
formula cells and identifies them as &quot;UnknownRecord&quot; at the
lower level of the API. We must provide a way to read and write
formulas. This is now the top requested feature.
</p>
<p>
The HSSF library currently does not support
charts. This is a key requirement of some users who wish to use HSSF
in a reporting engine.
</p>
<p>
The HSSF Serializer currently does not
provide serialization for cell styling. User's will want stylish
spreadsheets to result from their XML.
</p>
<p>
There is currently no way to generate
the XML from an XLS that is consistent with the format used by the
HSSF Serializer.
</p>
<p>
There should be a way to read and write
the DOC file format using pure Java.
</p>
</section>
</section>
<section><title>3. Project Overview</title>
<section><title>3.1. Project Perspective</title>
<p>
The produced code shall be licensed by
the Apache License as used by the Cocoon 2 project (APL 1.1) and
maintained on at <link href="http://poi.sourceforge.net/">http://poi.sourceforge.net</link>
and <link href="http://sourcefoge.net/projects/poi">http://sourcefoge.net/projects/poi</link>.
It is our hope to at some point integrate with the various Apache
projects (xml.apache.org and jakarta.apache.org), at which point we'd
turn the copyright over to them.
</p>
</section>
<section><title>3.2. Project Position Statement</title>
<p>
For developers on a Java and/or XML
environment this project will provide all the tools necessary for
outputting XML data in the Microsoft Excel format. This project seeks
to make the use of Microsoft Windows based servers unnecessary for
file format considerations and to fully document the OLE 2 Compound
Document format. The project aims not only to provide the tools for
serializing XML to Excel and Word file formats and the tools for
writing to those file formats from Java, but also to provide the
tools for later projects to convert other OLE 2 Compound Document
formats to pure Java APIs.
</p>
</section>
<section><title>3.3. Summary of Capabilities</title>
<p>
HSSF Serializer for Apache Cocoon 2
</p>
<table>
<tr>
<th>
Benefit
</th>
<th>
Supporting Features
</th>
</tr>
<tr>
<td>
Ability to serialize styles from XML spreadsheets.
</td>
<td>
HSSFSerialzier will support styles.
</td>
</tr>
<tr>
<td>
Ability to read and write formulas in XLS files.
</td>
<td>
HSSF will support reading/writing formulas.
</td>
</tr>
<tr>
<td>
Ability to output in MS Word on any platform using Java.
</td>
<td>
The project will develop an API that outputs in Word format
using pure Java.
</td>
</tr>
<tr>
<td>
Enhance performance for reading and writing XLS files.
</td>
<td>
HSSF will undergo a number of performance enhancements. HSSF
will include a new event-based API for reading XLS files. POIFS
will support a new event-based API for reading OLE2 CDF files.
</td>
</tr>
<tr>
<td>
Ability to generate XML from XLS files
</td>
<td>
The project will develop an HSSF Generator.
</td>
</tr>
<tr>
<td>
The ability to generate charts
</td>
<td>
HSSF will provide low level support for chart records as well
as high level API support for generating charts. The ability
to read chart information will not initially be provided.
</td>
</tr>
</table>
</section>
<section><title>3.4. Assumptions and Dependencies</title>
<ul>
<li>
The HSSF Serializer and Generator
will support the Gnumeric 1.0 XML tag language.
</li>
<li>
The HSSF Generator and HSSF
Serializer will be mutually validating. It should be possible to
have an XLS file created by the Serializer run through the Generator
and the output back through the Serializer (via the Cocoon pipeline)
and get the same file or a reasonable facimille (no one cares if it
differs by the order of the binary records in some minor but
non-visually recognizable manner).
</li>
<li>
The HSSF Generator will run on any
Java 2 supporting platform with Apache Cocoon 2 installed along with
the HSSF and POIFS APIs.
</li>
<li>
The HSSF Serializer will run on
any Java 2 supporting platform with Apache Cocoon 2 installed along
with the HSSF and POIFS APIs.
</li>
<li>
The HWPF API requires a Java 2
implementation and the POIFS API.
</li>
<li>
The HSSF API requires a Java 2
implementation and the POIFS API.
</li>
<li>
The POIFS API requires a Java 2
implementation.
</li>
</ul>
</section>
</section>
<section><title>4. Project Features</title>
<p>
Enhancements to the POIFS API will
include:
</p>
<ul>
<li>
An event driven API for reading
POIFS Filesystems.
</li>
<li>
A low-level API for
creating/manipulating POI filesystems.
</li>
<li>
Code improvements supporting
greater separation between read and write structures.
</li>
</ul>
<p>
Enhancements to the HSSF API will
include:
</p>
<ul>
<li>
An event driven API for reading
XLS files.
</li>
<li>
Performance improvements.
</li>
<li>
Formula support (read/write)
</li>
<li>
Support for user-defined data
formats
</li>
<li>
Better documentation of the file
format and structure.
</li>
<li>
An API for creation of charts.
</li>
</ul>
<p>
The HSSF Generator will include:
</p>
<ul>
<li>
A set of classes supporting the
Cocoon 2 Generator interfaces providing a method for reading XLS
files and outputting SAX events.
</li>
<li>
The same tag format used by the
HSSFSerializer in any given release.
</li>
</ul>
<p>
The HWPF API will include:
</p>
<ul>
<li>
An event driven API for reading
DOC files.
</li>
<li>
A set of high and low level APIs
for reading and writing DOC files.
</li>
<li>
Documentation of the DOC file
format or enhancements to existing documentation.
</li>
</ul>
</section>
<section><title>5. Other Product Requirements</title>
<section><title>5.1. Applicable Standards</title>
<p>
All Java code will be 100% pure Java.
</p>
</section>
<section><title>5.2. System Requirements</title>
<p>
The minimum system requirements for the POIFS API are:
</p>
<ul>
<li>64 Mbytes memory</li>
<li>Java 2 environment</li>
<li>Pentium or better processor (or equivalent on other platforms)</li>
</ul>
<p>
The minimum system requirements for the the HSSF API are:
</p>
<ul>
<li>64 Mbytes memory</li>
<li>Java 2 environment</li>
<li>Pentium or better processor (or equivalent on other platforms)</li>
<li>POIFS API</li>
</ul>
<p>
The minimum system requirements for the the HWPF API are:
</p>
<ul>
<li>64 Mbytes memory</li>
<li>Java 2 environment</li>
<li>Pentium or better processor (or equivalent on other platforms)</li>
<li>POIFS API</li>
</ul>
<p>
The minimum system requirements for the HSSF Serializer are:
</p>
<ul>
<li>64 Mbytes memory</li>
<li>Java 2 environment</li>
<li>Pentium or better processor (or equivalent on other platforms)</li>
<li>Cocoon 2</li>
<li>HSSF API</li>
<li>POI API</li>
</ul>
</section>
<section><title>5.3. Performance Requirements</title>
<p>
All components must perform well enough
to be practical for use in a webserver environment (especially
the "killer trio": Cocoon2/Tomcat/Apache combo)
</p>
</section>
<section><title>5.4. Environmental Requirements</title>
<p>
The software will run primarily in
developer environments. We should make some allowances for
not-highly-technical users to write XML documents for the HSSF
Serializer. All other components will assume intermediate Java 2
knowledge. No XML knowledge will be required except for using the
HSSF Serializer. As much documentation as is practical shall be
required for all components as XML is relatively new, and the
concepts introduced for writing spreadsheets and to POI filesystems
will be brand new to Java and many Java developers.
</p>
</section>
</section>
<section><title>6. Documentation Requirements</title>
<section><title>6.1 POI Filesystem</title>
<p>
The filesystem as read and written by
POI shall be fully documented and explained so that the average Java
developer can understand it.
</p>
</section>
<section><title>6.2. POI API</title>
<p>
The POI API will be fully documented
through Javadoc. A walkthrough of using the high level POI API shall
be provided. No documentation outside of the Javadoc shall be
provided for the low-level POI APIs.
</p>
</section>
<section><title>6.3. HSSF File Format</title>
<p>
The HSSF File Format as implemented by
the HSSF API will be fully documented. No documentation will be
provided for features that are not supported by HSSF API that are
supported by the Excel 97 File Format. Care will be taken not to
infringe on any &quot;legal stuff&quot;. Additionally, we are
collaborating with the fine folks at OpenOffice.org on
*free* documentation of the format.
</p>
</section>
<section><title>6.4. HSSF API</title>
<p>
The HSSF API will be documented by
javadoc. A walkthrough of using the high level HSSF API shall be
provided. No documentation outside of the Javadoc shall be provided
for the low level HSSF APIs.
</p>
</section>
<section><title>6.5 HWPF API</title>
<p>
The HWPF API will be documented by
javadoc. A walkthrough of using the high level HWPF API shall be
provided. No documentation outside of the Javadoc shall be provided
for the low level HWPF APIs.
</p>
</section>
<section><title>6.6 HSSF Serializer</title>
<p>
The HSSF Serializer will be documented
by javadoc.
</p>
</section>
<section><title>6.7 HSSF Generator</title>
<p>
The HSSF Generator will be documented
by javadoc.
</p>
</section>
<section><title>6.8 HSSF Serializer Tag language</title>
<p>
The XML tag language along with
function and usage shall be fully documented. Examples will be
provided as well.
</p>
</section>
</section>
<section><title>7. Terminology</title>
<section><title>7.1 Filesystem</title>
<p>
filesystem shall refer only to the POI formatted archive.
</p>
</section>
<section><title>7.2 File</title>
<p>
file shall refer to the embedded data stream within a
POI filesystem. This will be the actual embedded document.
</p>
</section>
</section>
</body>
</document>

39
src/documentation/content/xdocs/plan/book.xml Normal file
View File

@ -0,0 +1,39 @@
<?xml version="1.0"?>
<!--
====================================================================
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
====================================================================
-->
<!DOCTYPE book PUBLIC "-//APACHE//DTD Cocoon Documentation Book V1.0//EN" "../dtd/book-cocoon-v10.dtd">
<book software="POI Project"
title="POI Project planning"
copyright="@year@ POI Project">
<menu label="Apache POI">
<menu-item label="Top" href="../index.html"/>
</menu>
<menu label="Planning Documents">
<menu-item label="Overview" href="index.html"/>
<menu-item label="1.0 Vision" href="POI10Vision.html"/>
<menu-item label="2.0 Vision" href="POI20Vision.html"/>
</menu>
</book>

76
src/documentation/content/xdocs/plan/index.xml Normal file
View File

@ -0,0 +1,76 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
====================================================================
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
====================================================================
-->
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "../dtd/document-v11.dtd">
<document>
<header>
<title>Planning Documentation</title>
<subtitle>Overview</subtitle>
<authors>
<person name="David Crossley" email="crossley@apache.org"/>
<person name="Nicola Ken Barozzi" email="barozzi@nicolaken.com"/>
</authors>
</header>
<body>
<section><title>Overview</title>
<p>This is a collection of notes to assist with long-term planning and
development.
</p>
<p>There is much discussion of issues and research topics (RT) threads on
the <code>dev</code> mailing list (and elsewhere). However, details
get lost in the sheer volume. This is the place to document the summary of
discussions on some key topics. Some new and complex capabilities will take
lots of design and specification before they can be implemented.
</p>
<p>Another use for this collection of notes is as a place to quickly store
a snippet from an email discussion or even a link to a discussion thread.
The concepts can then be fleshed-out over time.
</p>
<p>Anyone can participate in this process. Please get involved in discussion
on <code>dev</code> and contribute patches for these summary planning
documents via the normal <link href="../guidelines.html">contribution</link>
process.
</p>
<p>These planning documents are intended to be concise notes only. They are
also ever-evolving, because as issues are addressed these notes will be
revised.
</p>
</section>
<section><title>Topics and Issues</title>
<ul>
<li><link href="POI20Vision.html">POI Version 2.0 Vision</link>
</li>
<li><link href="POI10Vision.html">POI Version 1.0 Vision</link>
</li>
<li>See the general <link href="../todo.html">To Do</link> list
and the <code>dev</code> email archives for other issues</li>
</ul>
</section>
</body>
</document>

81
src/documentation/content/xdocs/plan/release.xml Normal file
View File

@ -0,0 +1,81 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
====================================================================
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
====================================================================
-->
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "../dtd/document-v11.dtd">
<document>
<header>
<title>Release Plan 2.0</title>
<subtitle>Planning Documentation</subtitle>
<authors>
<person name="David Crossley" email="crossley@apache.org"/>
<person name="Nicola Ken Barozzi" email="barozzi@nicolaken.com"/>
</authors>
</header>
<body>
<section><title>Preparation for release of Poi</title>
<p>Todo</p>
<!-- NKB todo
<p>The 2.0 final release is scheduled for the end of November 2001.
</p>
<p>
The following is extracted from the thread
[C2]: Release Candidate 2 ... 2001-10-29
</p>
<source><![CDATA[
> The question is now, what has to be done until then?
>
> 1) We have many open bugs in bugzilla. These must be reviewed
> and then solved (or declared invalid etc).
>
> 2) Documentation updates (this area lacks most)
> We could move this to the final release.
Documentation must be happening all the time, and not left
until last.
> 3) Decide what to backport from the 2.1 head.
> I'm +1 on removing the CodeFactories completly in 2.0, too.
> This would avoid any backcompatibility problems.
>
> 4) Layout the distribution
> This is a point we haven't discussed yet. Currently our
> distribution is a mixture of a source and a binary one.
> We deliver the source and a compiled version, but in order
> to run Cocoon, the user has to build a war file.
> I propose to split this: one source distribution which is
> similar to the current one but without the precompiled
> cocoon jar and a binary distribution containing only the
> war file. This war file should work in most servlet engines,
> perhaps not in all.
>
> So anything missing here?
5) Ensure that licensing requirements have been met.
update jars.xml, ensure proper banner in *.java header,
verify the current LICENSE* files, ensure that external
components have suitable licensing requirements.
]]></source>
-->
</section>
</body>
</document>

148
src/documentation/content/xdocs/poi-ruby.xml Normal file
View File

@ -0,0 +1,148 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
====================================================================
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
====================================================================
-->
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.3//EN" "./dtd/document-v13.dtd">
<document>
<header>
<title>POI Ruby Bindings</title>
<authors>
<person id="AS" name="Avik Sengupta" email="avik@apache.org"/>
</authors>
</header>
<body>
<section><title>Intro</title>
<p>The POI library can now be compiled as a Ruby extension, allowing the API to be called from
Ruby language programs. Ruby users can therefore read and write OLE2 documents, such as Excel files
with ease
</p>
<p>The bindings are generated by compiling POI with <link href="http://gcc.gnu.org/java/">gcj</link>,
and generating the Ruby wrapper using <link href="http://www.swig.org">SWIG</link>. The aim is the keep
the POI api as-is. However, where java standard library objects are used, an effort is made to transform them smoothly
into Ruby objects. Therefore, where the POI API takes an OutputStream, you can pass an IO object. Where the POI works
java.util.Date or java.util.Calendar object, you can work with a Ruby Time object. </p>
</section>
<section><title>Getting Started</title>
<section><title>Pre-Requisites</title>
<p>The bindings have been developed with GCC 3.4.3 and Ruby 1.8.2. You are unlikely to get correct results with
versions of GCC prior to 3.4 or versions of Ruby prior to 1.8. To compile the Ruby extension, you must have
GCC (compiled with java language support), Ruby development headers, and SWIG. To run, you will need Ruby (obviously!) and
<em>libgcj </em>, presumably from the same version of GCC with which you compiled.
</p>
</section>
<section><title>Subversion</title>
<p>
The POI-Ruby module sits under the POI <link href="http://svn.apache.org/repos/asf/poi/trunk/src/contrib/poi-ruby/">Subversion</link>. Running <em>make</em>
inside that directory will create a loadable ruby extention <em>poi4r.so</em> in the release subdirectory. Tests
are in the <em>tests/</em> subdirectory, and should be run from the <em>poi-ruby</em> directory. Please read the tests to figure out the usage.
</p>
<p>Note that the makefile, though designed to work accross Linux/OS X/Cygwin, has been tested only on linux.
There are likely to be issues on other platform; fixes gratefully accepted! </p>
</section>
<section><title>Binary</title>
<p>A version of poi4r.so is available <link href="http://www.apache.org/~avik/dist/poi4r.so">here</link>. Its been compiled on a linux box
with GCC 3.4.3 and Ruby 1.8.2. It dynamically links to libgcj. No guarantees about working on any other box. </p>
</section>
</section>
<section>
<title>Usage</title>
<p>The following ruby code shows some of the things you can do with POI in Ruby</p>
<source>
h=Poi4r::HSSFWorkbook.new
#Test Sheet Creation
s=h.createSheet("Sheet1")
#Test setting cell values
s=h.getSheetAt(0)
r=s.createRow(0)
c=r.createCell(0)
c.setCellValue(1.5)
c=r.createCell(1)
c.setCellValue("Ruby")
#Test styles
st = h.createCellStyle()
c=r.createCell(2)
st.setAlignment(Poi4r::HSSFCellStyle.ALIGN_CENTER)
c.setCellStyle(st)
c.setCellValue("centr'd")
#Date handling
c=r.createCell(3)
t1=Time.now
c.setCellValue(Time.now)
t2= c.getDateCellValue().gmtime
st=h.createCellStyle();
st.setDataFormat(Poi4r::HSSFDataFormat.getBuiltinFormat("m/d/yy h:mm"))
c.setCellStyle(st)
#Formulas
c=r.createCell(4)
c.setCellFormula("A1*2")
c.getCellFormula()
#Writing
h.write(File.new("test.xls","w"))
</source>
<p> The <em>tc_base_tests.rb</em> file in the <em>tests</em> sub directory of the source distribution
contains examples of simple uses of the API. The <link href="spreadsheet/quick-guide.html">quick quide </link> is the best
place to learn HSSF API use. (Note however that none of the Drawing features are implemented in the Ruby binding.)
See also the <link href="apidocs/overview-summary.html">POI API documentation</link> for more details.
</p>
</section>
<section>
<title>Future Directions</title>
<section><title>TODO's</title>
<ul>
<li>Implement support for reading Excel files (easy)</li>
<li>Expose POIFS API to read raw OLE2 files from Ruby</li>
<li>Expose HPSF API to read property streams </li>
<li>Tests... Tests... Tests...</li>
</ul>
</section>
<section><title>Limitations</title>
<ul>
<li>Check operations in 64bit machines - Java primitive types are fixed irrespective of machine type, unlike C/C++ types. The wrapping code
that converts C/C++ primitive types to/from Java types is making assumptions on type sizes that MAY be incorrect on wide architectures. </li>
<li>The current implementation is with the POI 2.0 release. The 2.5 release adds support for Excel drawing primitives, and
thus has a dependency on java AWT. Since AWT is not very mature in gcj, leaving it out seemed to be the safer option.</li>
<li>Packaging - The current make file makes no effort to install the extension into the standard ruby directories. This should probably be
packaged as a <link href="http://www.rubygems.org">gem</link>.</li>
</ul>
</section>
</section>
</body>
<footer>
<legal>
Copyright 2005 The Apache Software Foundation or its licensors, as applicable.
</legal>
</footer>
</document>

40
src/documentation/content/xdocs/poifs/book.xml Normal file
View File

@ -0,0 +1,40 @@
<?xml version="1.0"?>
<!--
====================================================================
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
====================================================================
-->
<!DOCTYPE book PUBLIC "-//APACHE//DTD Cocoon Documentation Book V1.0//EN" "../dtd/book-cocoon-v10.dtd">
<book software="POI Project"
title="POIFS"
copyright="@year@ POI Project">
<menu label="Apache POI">
<menu-item label="Top" href="../index.html"/>
</menu>
<menu label="POIFS">
<menu-item label="Overview" href="index.html"/>
<menu-item label="How To" href="how-to.html"/>
<menu-item label="Embeded Documents" href="embeded.html"/>
<menu-item label="File System Documentation" href="fileformat.html"/>
<menu-item label="Use Cases" href="usecases.html"/>
</menu>
</book>

95
src/documentation/content/xdocs/poifs/embeded.xml Normal file
View File

@ -0,0 +1,95 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
====================================================================
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
====================================================================
-->
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "../dtd/document-v11.dtd">
<document>
<header>
<title>Apache POI - POIFS - Documents embeded in other documents</title>
<subtitle>Overview</subtitle>
<authors>
<person name="Nick Burch" email="nick@apache.org"/>
<person name="Yegor Kozlov" email="yegor@apache.org"/>
</authors>
</header>
<body>
<section><title>Overview</title>
<p>It is possible for one OLE 2 based document to have other
OLE 2 documents embeded in it. For example, and Excel file
may have a word document and a powerpoint slideshow
embeded as part of it.</p>
<p>Normally, these other documents are stored in subdirectories
of the OLE 2 (POIFS) filesystem. The exact location of the
embeded documents will vary depending on the type of the
master document, and the exact directory names will differ
each time. To figure out exactly which directory to look
in, you will either need to process the appropriate OLE 2
linking entry in the master document, or simple iterate
over all the directories in the filesystem.</p>
<p>As a general rule, you will find the same OLE 2 entries
in the subdirectories, as you would've found at the root
of the filesystem were a document to not be embeded.</p>
<section><title>Files embeded in Excel</title>
<p>Excel normally stores embeded files in subdirectories
of the filesystem root. Typically these subdirectories
are named starting with MBD, with 8 hex characters following.</p>
</section>
<section><title>Files embeded in Word</title>
<p>Word normally stores embeded files in subdirectories
of the ObjectPool directory, itself a subdirectory of the
filesystem root. Typically these subdirectories and named
starting with an underscore, followed by 10 numbers.</p>
</section>
<section><title>Files embeded in PowerPoint</title>
<p>PowerPoint does not normally store embeded files
in the OLE2 layer. Instead, they are held within records
of the main PowerPoint file.
<br/>See the <link href="./../slideshow/how-to-shapes.html#OLE">HSLF Tutorial</link>
for how to retrieve embedded OLE objects from a presentation</p>
</section>
</section>
<section><title>Listing POIFS contents</title>
<p>POIFS provides a simple tool for listing the contents of
OLE2 files. This can allow you to see what your POIFS file
contents, and hence if it has any embeded documents in it,
and where.</p>
<p>The tool to use is <em>org.apache.poi.poifs.dev.POIFSLister</em>.
This tool may be run from the command line, and takes a filename
as its parameter. It will print out all the directories and
files contained within the POIFS file.</p>
</section>
<section><title>Opening embeded files</title>
<p>All of the POIDocument classes (HSSFWorkbook, HSLFSlideShow,
HWPFDocument and HDGFDiagram) can either be opened from
a POIFSFileSystem, or from a specific directory within a
POIFSFileSystem. So, to open embeded files, simply locate the
appropriate DirectoryNode that represents the subdirectory
of interest, and pass this + the overall POIFSFileSystem to
the constructor.</p>
<p>I you want to extract the textual contents of the embeded file,
then open the appropriate POIDocument, and then pass this to
the extractor class, instead of simply passing the POIFSFilesystem
to the extractor.</p>
</section>
</body>
</document>

703
src/documentation/content/xdocs/poifs/fileformat.xml Normal file
View File

@ -0,0 +1,703 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
====================================================================
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
====================================================================
-->
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "../dtd/document-v11.dtd">
<document>
<header>
<title>POIFS File System Internals</title>
<authors>
<person email="mjohnson@apache.org" name="Marc Johnson" id="MJ"/>
</authors>
</header>
<body>
<section><title>POIFS File System Internals</title>
<section><title>Introduction</title>
<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
extension noting what type of data they contain. For
example, a file ending in &quot;.xls&quot; would likely
contain spreadsheet data, and a file ending in
&quot;.doc&quot; would probably contain a word processing
document. POIFS file systems are called &quot;file
system&quot;, because they contain multiple embedded files
in a manner similar to traditional file systems. Along
functional lines, it would be more accurate to call these
POIFS archives. For the remainder of this document it is
referred to as a file system in order to avoid confusion
with the &quot;files&quot; it contains.</p>
<p>POIFS file systems are compatible with those document
formats used by a well-known software company's popular
office productivity suite and programs outputting
compatible data. Because the POIFS file system does not
provide compression, encryption or any other worthwhile
feature, its not a good choice unless you require
interoperability with these programs.</p>
<p>The POIFS file system does not encode the documents
themselves. For example, if you had a word processor file
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>
<p>Note - this document is a good overview and explanation of
the file format, but for the very nitty-gritty details,
you should refer to
<link href="http://msdn.microsoft.com/en-us/library/dd942138%28v=prot.13%29.aspx">[MS-CFB].pdf</link>
in the (now public) Microsoft Documentation.</p>
</section>
<section><title>Document Conventions</title>
<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
short:</p>
<ul>
<li>A <em>byte</em> is an 8 bit signed integer ranging from
-128 to 127.</li>
<li>A <em>short</em> is a 16 bit signed integer ranging from
-32768 to 32767</li>
<li>An <em>int</em> is a 32 bit signed integer ranging from
-2147483648 to 2147483647</li>
<li>A <em>long</em> is a 64 bit signed integer ranging from
-9.22E18 to 9.22E18.</li>
</ul>
<p>The Java Language Specification spells out a number of
other types that are not referred to by this document.</p>
<p>Where this document makes references to &quot;endian
conversion&quot; it is referring to the byte order of
stored numbers. Numbers in &quot;little-endian order&quot;
are stored with the <em>least</em> significant byte first. In
order to properly read a short, for example, you'd read two
bytes and then shift the second byte 8 bits to the left
before performing an <code>or</code> operation to it
against the first byte. The following code illustrates this
method:</p>
<source>
public int getShort (byte[] rec)
{
return ((rec[1] &lt;&lt; 8) | (rec[0] &amp; 0x00ff));
}</source>
</section>
<section><title>File System Walkthrough</title>
<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
general structure and how it's interpreted.</p>
<p>A POIFS file system begins with a header. This header
identifies locations in the file by function and provides a
sanity check identifying a file as a POIFS file system.</p>
<p>The first 64 bits of the header compose a <em>magic number
identifier.</em> This identifier tells the client software
that this is indeed a POIFS file system and that it should
be treated as such. This is a &quot;sanity check&quot; to
make sure this is a POIFS file system and not some other
format. The header also contains an <em>array of block
numbers</em>. These block numbers refer to blocks in the
file. When these blocks are read together they form the
<em>Block Allocation Table</em>. The header also contains a
pointer to the first element in the <em>property table</em>,
also known as the <em>root element</em>, and a pointer to the
<em>small Block Allocation Table (SBAT)</em>.</p>
<p>The <em>block allocation table</em> or <em>BAT</em>, along with
the <em>property table</em>, specify which blocks in the file
system belong to which files. After the header block, the
file system is divided into identically sized blocks of
data, numbered from 0 to however many blocks there are in
the file system. For each file in the file system, its
entry in the property table includes the index of the first
block in the array of blocks. Each block's index into the
array of blocks is also its index into the BAT, and the
integer value stored at that index in the BAT gives the
index of the next block in the array (and thus the index of
the next BAT value). A special value is stored in the BAT
to indicate &quot;end of file&quot;.</p>
<p>The <em>property table</em> is essentially the directory
storage for the file system. It consists of the name of the
file or directory, its <em>start block</em> in both the file
system and <em>BAT</em>, and its actual size. The first
property in the property table is the <em>root
element</em>. It has two purposes: to be a directory entry
(the root of the directory tree, to be specific), and to
hold the start block for the <em>small block data</em>.</p>
<p>Small block data is a special file that contains the data
for small files (less than 4K bytes). It subdivides its
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>
</section>
<section><title>Header Block</title>
<p>The POIFS file system begins with a <em>header
block</em>. The first 64 bits of the header form a long
<em>file type id</em> or <em>magic number identifier</em> of
<code>0xE11AB1A1E011CFD0L</code>. This is basically a
sanity check. If this isn't the first thing in the header
(and consequently the file system) then this is not a
POIFS file system and should be read with some other
library.</p>
<p>It's important to know the most important parts of the
header. These are discussed in the rest of this
section.</p>
<section><title>BATs</title>
<p>At offset <em>0x2C</em> is an int specifying the number
of elements in the <em>BAT array</em>. The array at
<em>0x4C</em> an array of ints. This array contains the
indices of every block in the Block Allocation
Table.</p>
</section>
<section><title>XBATs</title>
<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
contain up to 109 BAT block indices; each BAT block
references up to 128 blocks, and each block is 512
bytes, so we're talking about 109 * 128 * 512 =
6.8MB. That's a pretty respectable document! But, you
could have much more data than that, and in today's
world of cheap gigabyte drives, why not? So, the BAT
may be extended in that event. The integer value at
offset <em>0x44</em> of the header is the index of the
first <em>extended BAT (XBAT) block</em>. At offset
<em>0x48</em> of the header, there is an int value that
specifies how many XBAT blocks there are. The XBAT
blocks begin at the specified index into the array of
blocks making up the POIFS file system, and are chained
for the specified count of XBAT blocks.</p>
<p>Each XBAT block contains the indices of up to 127 BAT
blocks, so the document size can be expanded by another
~8MB for each XBAT block. The BAT blocks indexed by an
XBAT block are appended to the end of the list of BAT
blocks enumerated in the header block. Thus the BAT
blocks enumerated in the header block are BAT blocks 0
through 108, the BAT blocks enumerated in the first
XBAT block are BAT blocks 109 through 235, the BAT
blocks enumerated in the second XBAT block are BAT
blocks 236 through 362, and so on.</p>
<p>While a normal BAT block holds 128 entries, each XBAT
only references 127 BAT blocks. The last, 128th entry
in an XBAT is the offset to the next XBAT block in the
chain (or -1 if this is the last XBAT).</p>
<p>Through the use of XBAT blocks, the limit on the
overall document size is that imposed by the 4-byte
block indices; if the indices are unsigned ints, the
maximum file size is 2 terabytes, 1 terabyte if the
indices are treated as signed ints. Either way, I have
yet to see a disk drive large enough to accommodate
such a file on the shelves at the local office supply
stores.</p>
</section>
<section><title>SBATs</title>
<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
blocks, up to 8 to a big block. As the main BAT is used
to navigate the array of big blocks, so the <em>small
block allocation table</em> is used to navigate the
array of small blocks. The SBAT's start block index is
found at offset <em>0x3C</em> of the header block, and
remaining blocks constituting the SBAT are found by
walking the main BAT as if it were an ordinary file in
the POIFS file system (this process is described
below).</p>
</section>
<section><title>Property Table Start Index</title>
<p>An integer at address <em>0x30</em> specifies the start
index of the property table. This integer is specified
as a <em>&quot;block index&quot;</em>. 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>
</section>
</section>
<section><title>Property Table</title>
<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
is always the Root Entry. The following applies to
individual properties within a property table:</p>
<ul>
<li>At offset <em>0x00</em> in the property is the
&quot;<em>name</em>&quot;. This is stored as an
uncompressed 16 bit unicode string. In short every
other byte corresponds to an &quot;ASCII&quot;
character. The size of this string is stored at offset
<em>0x40</em> (<em>string size</em>) as a short.</li>
<li>At offset <em>0x42</em> is the <em>property type</em>
(byte). The type is 1 for directory, 2 for file or 5
for the Root Entry.</li>
<li>At offset <em>0x43</em> is the <em>node color</em>
(byte). The color is either 1, (black), or 0,
(red). Properties are apparently meant to be arranged
in a red-black binary tree, subject to the following
rules:
<ol>
<li>The root of the tree is always black</li>
<li>Two consecutive nodes cannot both be red</li>
<li>A property is less than another property if its
name length is less than the other property's name
length</li>
<li>If two properties have the same name length, the
sort order is determined by the sort order of the
properties' names.</li>
</ol></li>
<li>At offset <em>0x44</em> is the index (int) of the
<em>previous property</em>.</li>
<li>At offset <em>0x48</em> is the index (int) of the
<em>next property</em>.</li>
<li>At offset <em>0x4C</em> is the index (int) of the
<em>first directory entry</em>. This is used by
directory entries.</li>
<li>At offset <em>0x74</em> is an integer giving the
<em>start block</em> for the file described by this
property. This index corresponds to an index in the
array of indices that is the Block Allocation Table
(or the Small Block Allocation Table) as well as the
index of the first block in the file. This is used by
files and the root entry.</li>
<li>At offset <em>0x78</em> is an integer giving the total
<em>actual size</em> of the file pointed at by this
property. If the file size is less than 4096, the file
is stored in small blocks and the SBAT is used to walk
the small blocks making up the file. If the file size
is 4096 or larger, the file is stored in big blocks
and the main BAT is used to walk the big blocks making
up the file. The exception to this rule is the <em>Root
Entry</em>, which, regardless of its size, is
<em>always</em> stored in big blocks and the main BAT is
used to walk the big blocks making up this special
file.</li>
</ul>
</section>
<section><title>Root Entry</title>
<p>The <em>Root Entry</em> in the <em>Property Table</em>
contains the information necessary to read and write
small files, which are files less than 4096 bytes
long. The start block field of the Root Entry is the
start index of the <em>Small Block Array</em>, which is
read like any other file in the POIFS file system. Since
the SBAT cannot be used without the Small Block Array,
the Root Entry MUST be read or written using the <em>Block
Allocation Table</em>. The blocks making up the Small
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>
</section>
<section><title>Walking the Nodes of the Property Table</title>
<p>The individual properties form a directory tree, with the
<em>Root Entry</em> as the directory tree's root, as shown
in the accompanying drawing. Note the numbers in
parentheses in each node; they represent the node's index
in the array of properties. The <em>NEXT_PROP</em>,
<em>PREVIOUS_PROP</em>, and <em>CHILD_PROP</em> fields hold
these indices, and are used to navigate the tree.</p>
<p><img alt="property set" src="images/PropertySet.jpg" /></p>
<p>Each directory entry (i.e., a property whose type is
<em>directory</em> or <em>root entry</em>) uses its
<em>CHILD_PROP</em> field to point to one of its
subordinate (child) properties. It doesn't seem to matter
which of its children it points to. Thus in the previous
drawing, the Root Entry's CHILD_PROP field may contain 1,
4, or the index of one of its other children. Similarly,
the directory node (index 1) may have, in its CHILD_PROP
field, 2, 3, or the index of one of its other
children.</p>
<p>The children of a given directory property point to each
other in a similar fashion by using their
<em>NEXT_PROP</em> and <em>PREVIOUS_PROP</em> fields.</p>
<p>Unused <em>NEXT_PROP</em>, <em>PREVIOUS_PROP</em>, and
<em>CHILD_PROP</em> fields contain the marker value of
-1. All file properties have a value of -1 for their
CHILD_PROP fields for example.</p>
</section>
<section><title>Block Allocation Table</title>
<p>The <em>BAT blocks</em> are pointed at by the bat array
contained in the header and supplemented, if necessary,
by the <em>XBAT blocks</em>. These blocks form a large
table of integers. These integers are block numbers. The
<em>Block Allocation Table</em> holds chains of integers.
These chains are terminated with -2. The elements in
these chains refer to blocks in the files. The starting
block of a file is NOT specified in the BAT. It is
specified by the <em>property</em> for a given file. The
elements in this BAT are both the block number (within
the file minus the header) <em>and</em> the number of the
next BAT element in the chain. This can be thought of as
a linked list of blocks. The BAT array contains the links
from one block to the next, including the end of chain
marker.</p>
<p>Here's an example: Let's assume that the BAT begins as
follows:</p>
<p><code>BAT[ 0 ] = 2</code></p>
<p><code>BAT[ 1 ] = 5</code></p>
<p><code>BAT[ 2 ] = 3</code></p>
<p><code>BAT[ 3 ] = 4</code></p>
<p><code>BAT[ 4 ] = 6</code></p>
<p><code>BAT[ 5 ] = -2</code></p>
<p><code>BAT[ 6 ] = 7</code></p>
<p><code>BAT[ 7 ] = -2</code></p>
<p><code>...</code></p>
<p>Now, if we have a file whose Property Table entry says it
begins with index 0, we walk the BAT array and see that
the file consists of blocks 0 (because the start block is
0), 2 (because BAT[ 0 ] is 2), 3 (BAT[ 2 ] is 3), 4 (BAT[
3 ] is 4), 6 (BAT[ 4 ] is 6), and 7 (BAT[ 6 ] is 7). It
ends at block 7 because BAT[ 7 ] is -2, which is the end
of chain marker.</p>
<p>Similarly, a file beginning at index 1 consists of
blocks 1 and 5.</p>
<p>Other special numbers in a BAT array are:</p>
<ul>
<li>-1, which indicates an unused block</li>
<li>-3, which indicates a &quot;special&quot; block, such
as a block used to make up the Small Block Array, the
Property Table, the main BAT, or the SBAT</li>
</ul>
</section>
<section><title>File System Structures</title>
<p>The following outlines the basic file system structures.</p>
<section><title>Header (block 1) -- 512 (0x200) bytes</title>
<table>
<tr>
<td><em>Field</em></td>
<td><em>Description</em></td>
<td><em>Offset</em></td>
<td><em>Length</em></td>
<td><em>Default value or const</em></td>
</tr>
<tr>
<td>FILETYPE</td>
<td>Magic number identifying this as a POIFS file
system.</td>
<td>0x0000</td>
<td>Long</td>
<td>0xE11AB1A1E011CFD0</td>
</tr>
<tr>
<td>UK1</td>
<td>Unknown constant</td>
<td>0x0008</td>
<td>Integer</td>
<td>0</td>
</tr>
<tr>
<td>UK2</td>
<td>Unknown Constant</td>
<td>0x000C</td>
<td>Integer</td>
<td>0</td>
</tr>
<tr>
<td>UK3</td>
<td>Unknown Constant</td>
<td>0x0014</td>
<td>Integer</td>
<td>0</td>
</tr>
<tr>
<td>UK4</td>
<td>Unknown Constant (revision?)</td>
<td>0x0018</td>
<td>Short</td>
<td>0x003B</td>
</tr>
<tr>
<td>UK5</td>
<td>Unknown Constant (version?)</td>
<td>0x001A</td>
<td>Short</td>
<td>0x0003</td>
</tr>
<tr>
<td>UK6</td>
<td>Unknown Constant</td>
<td>0x001C</td>
<td>Short</td>
<td>-2</td>
</tr>
<tr>
<td>LOG_2_BIG_BLOCK_SIZE</td>
<td>Log, base 2, of the big block size</td>
<td>0x001E</td>
<td>Short</td>
<td>9 (2 ^ 9 = 512 bytes)</td>
</tr>
<tr>
<td>LOG_2_SMALL_BLOCK_SIZE</td>
<td>Log, base 2, of the small block size</td>
<td>0x0020</td>
<td>Integer</td>
<td>6 (2 ^ 6 = 64 bytes)</td>
</tr>
<tr>
<td>UK7</td>
<td>Unknown Constant</td>
<td>0x0024</td>
<td>Integer</td>
<td>0</td>
</tr>
<tr>
<td>UK8</td>
<td>Unknown Constant</td>
<td>0x0028</td>
<td>Integer</td>
<td>0</td>
</tr>
<tr>
<td>BAT_COUNT</td>
<td>Number of elements in the BAT array</td>
<td>0x002C</td>
<td>Integer</td>
<td>required</td>
</tr>
<tr>
<td>PROPERTIES_START</td>
<td>Block index of the first block of the property
table</td>
<td>0x0030</td>
<td>Integer</td>
<td>required</td>
</tr>
<tr>
<td>UK9</td>
<td>Unknown Constant</td>
<td>0x0034</td>
<td>Integer</td>
<td>0</td>
</tr>
<tr>
<td>UK10</td>
<td>Unknown Constant</td>
<td>0x0038</td>
<td>Integer</td>
<td>0x00001000</td>
</tr>
<tr>
<td>SBAT_START</td>
<td>Block index of first big block containing the small
block allocation table (SBAT)</td>
<td>0x003C</td>
<td>Integer</td>
<td>-2</td>
</tr>
<tr>
<td>SBAT_Block_Count</td>
<td>Number of big blocks holding the SBAT</td>
<td>0x0040</td>
<td>Integer</td>
<td>1</td>
</tr>
<tr>
<td>XBAT_START</td>
<td>Block index of the first block in the Extended Block
Allocation Table (XBAT)</td>
<td>0x0044</td>
<td>Integer</td>
<td>-2</td>
</tr>
<tr>
<td>XBAT_COUNT</td>
<td>Number of elements in the Extended Block Allocation
Table (to be added to the BAT)</td>
<td>0x0048</td>
<td>Integer</td>
<td>0</td>
</tr>
<tr>
<td>BAT_ARRAY</td>
<td>Array of block indices constituting the Block
Allocation Table (BAT)</td>
<td>0x004C, 0x0050, 0x0054 ... 0x01FC</td>
<td>Integer[]</td>
<td>-1 for unused elements, at least first element must
be filled.</td>
</tr>
<tr>
<td>N/A</td>
<td>Header block data not otherwise described in this
table</td>
<td>N/A</td>
<td>N/A</td>
<td>-1</td>
</tr>
</table>
</section>
<section>
<title>Block Allocation Table Block -- 512 (0x200) bytes</title>
<table>
<tr>
<td>
<em>Field</em>
</td>
<td>
<em>Description</em>
</td>
<td>
<em>Offset</em>
</td>
<td>
<em>Length</em>
</td>
<td>
<em>Default value or const</em>
</td>
</tr>
<tr>
<td>BAT_ELEMENT</td>
<td>Any given element in the BAT block</td>
<td>0x0000, 0x0004, 0x0008, ... 0x01FC</td>
<td>Integer</td>
<td>
-1 = unused<br/>
-2 = end of chain<br/>
-3 = special (e.g., BAT block)<br/>
All other values point to the next element in the
chain and the next index of a block composing the
file.
</td>
</tr>
</table>
</section>
<section><title>Property Block -- 512 (0x200) byte block</title>
<table>
<tr>
<td><em>Field</em></td>
<td><em>Description</em></td>
<td><em>Offset</em></td>
<td><em>Length</em></td>
<td><em>Default value or const</em></td>
</tr>
<tr>
<td>Properties[]</td>
<td>This block contains the properties.</td>
<td>0x0000, 0x0080, 0x0100, 0x0180</td>
<td>128 bytes</td>
<td>All unused space is set to -1.</td>
</tr>
</table>
</section>
<section><title>Property -- 128 (0x80) byte block</title>
<table>
<tr>
<td><em>Field</em></td>
<td><em>Description</em></td>
<td><em>Offset</em></td>
<td><em>Length</em></td>
<td><em>Default value or const</em></td>
</tr>
<tr>
<td>NAME</td>
<td>A unicode null-terminated uncompressed 16bit string
(lose the high bytes) containing the name of the
property.</td>
<td>0x00, 0x02, 0x04, ... 0x3E</td>
<td>Short[]</td>
<td>0x0000 for unused elements, field required, 32
(0x40) element max</td>
</tr>
<tr>
<td>NAME_SIZE</td>
<td>Number of characters in the NAME field</td>
<td>0x40</td>
<td>Short</td>
<td>Required</td>
</tr>
<tr>
<td>PROPERTY_TYPE</td>
<td>Property type (directory, file, or root)</td>
<td>0x42</td>
<td>Byte</td>
<td>1 (directory), 2 (file), or 5 (root entry)</td>
</tr>
<tr>
<td>NODE_COLOR</td>
<td>Node color</td>
<td>0x43</td>
<td>Byte</td>
<td>0 (red) or 1 (black)</td>
</tr>
<tr>
<td>PREVIOUS_PROP</td>
<td>Previous property index</td>
<td>0x44</td>
<td>Integer</td>
<td>-1</td>
</tr>
<tr>
<td>NEXT_PROP</td>
<td>Next property index</td>
<td>0x48</td>
<td>Integer</td>
<td>-1</td>
</tr>
<tr>
<td>CHILD_PROP</td>
<td>First child property index</td>
<td>0x4c</td>
<td>Integer</td>
<td>-1</td>
</tr>
<tr>
<td>SECONDS_1</td>
<td>Seconds component of the created timestamp?</td>
<td>0x64</td>
<td>Integer</td>
<td>0</td>
</tr>
<tr>
<td>DAYS_1</td>
<td>Days component of the created timestamp?</td>
<td>0x68</td>
<td>Integer</td>
<td>0</td>
</tr>
<tr>
<td>SECONDS_2</td>
<td>Seconds component of the modified timestamp?</td>
<td>0x6C</td>
<td>Integer</td>
<td>0</td>
</tr>
<tr>
<td>DAYS_2</td>
<td>Days component of the modified timestamp?</td>
<td>0x70</td>
<td>Integer</td>
<td>0</td>
</tr>
<tr>
<td>START_BLOCK</td>
<td>Starting block of the file, used as the first block
in the file and the pointer to the next block from
the BAT</td>
<td>0x74</td>
<td>Integer</td>
<td>Required</td>
</tr>
<tr>
<td>SIZE</td>
<td>Actual size of the file this property points
to. (used to truncate the blocks to the real
size).</td>
<td>0x78</td>
<td>Integer</td>
<td>0</td>
</tr>
</table>
</section>
</section>
</section>
</body>
</document>

431
src/documentation/content/xdocs/poifs/how-to.xml Normal file
View File

@ -0,0 +1,431 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
====================================================================
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
====================================================================
-->
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "../dtd/document-v11.dtd">
<document>
<header>
<title>How To Use the POIFS APIs</title>
<authors>
<person email="mjohnson@apache.org" name="Marc Johnson" id="MJ"/>
</authors>
</header>
<body>
<section><title>How To Use the POIFS APIs</title>
<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>
<section><title>Target Audience</title>
<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>
</section>
<section><title>Glossary</title>
<p>This document attempts to be consistent in its terminology, which is defined here:</p>
<table>
<tr>
<td><em>Term</em></td>
<td><em>Definition</em></td>
</tr>
<tr>
<td>Directory</td>
<td>A special file that may contain other directories and documents.</td>
</tr>
<tr>
<td>DirectoryEntry</td>
<td>Representation of a directory within another directory.</td>
</tr>
<tr>
<td>Document</td>
<td>A file containing data, such as word processing data or a spreadsheet workbook.</td>
</tr>
<tr>
<td>DocumentEntry</td>
<td>Representation of a document within a directory.</td>
</tr>
<tr>
<td>Entry</td>
<td>Representation of a file in a directory.</td>
</tr>
<tr>
<td>File</td>
<td>A named entity, managed and contained by the file system.</td>
</tr>
<tr>
<td>File System</td>
<td>The POIFS data structures, plus the contained directories and documents, which are maintained in a hierarchical directory structure.</td>
</tr>
<tr>
<td>Root Directory</td>
<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>
</section>
</section>
<section><title>Reading a File System</title>
<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>
<td><em>Technique</em></td>
<td><em>Advantages</em></td>
<td><em>Disadvantages</em></td>
</tr>
<tr>
<td>Conventional Reading (POIFSFileSystem)</td>
<td>
Simpler API similar to reading a conventional file system.<br/>
Can read documents in any order.
</td>
<td>
All files are resident in memory, whether your application needs them or not.
</td>
</tr>
<tr>
<td>New NIO driven Reading (NPOIFSFileSystem)</td>
<td>
Simpler API similar to reading a conventional file system.<br/>
Can read documents in any order.<br/>
Lower memory than POIFSFileSystem
</td>
<td>
If created from an InputStream, all files are resident in memory.
(If created from a File, only certain key structures are)<br/>
Currently doesn't support writing
</td>
</tr>
<tr>
<td>Event-Driven Reading</td>
<td>
Reduced footprint -- only the documents you care about are processed.<br/>
Improved performance -- no time is wasted reading the documents you're not interested in.
</td>
<td>
More complicated API.<br/>
Need to know in advance which documents you want to read.<br/>
No control over the order in which the documents are read.<br/>
No way to go back and get additional documents except to re-read the file system, which may not be possible, e.g., if the file system is being read from an input stream that lacks random access support.
</td>
</tr>
</table>
<section><title>Conventional Reading</title>
<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>
<section><title>Preparation</title>
<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:
// InputStream stream = new FileInputStream(fileName);
POIFSFileSystem fs;
try
{
fs = new POIFSFileSystem(inputStream);
}
catch (IOException e)
{
// an I/O error occurred, or the InputStream did not provide a compatible
// POIFS data structure
}
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>
</section>
<section><title>Reading the Directory Tree</title>
<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 ...
for (Entry entry : dir)
{
System.out.println("found entry: " + entry.getName());
if (entry instanceof DirectoryEntry)
{
// .. recurse into this directory
}
else if (entry instanceof DocumentEntry)
{
// entry is a document, which you can read
}
else
{
// currently, either an Entry is a DirectoryEntry or a DocumentEntry,
// but in the future, there may be other entry subinterfaces. The
// internal data structure certainly allows for a lot more entry types.
}
}</source>
</section>
<section><title>Reading a Specific Document</title>
<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>
<section><title>DocumentInputStream</title>
<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>
<li><code>markSupported()</code> returns <code>true</code>.</li>
<li><code>mark(int limit)</code> ignores the limit parameter; basically the method marks the current position in the document.</li>
<li><code>reset()</code> takes you back to the position when <code>mark()</code> was last called, or to the beginning of the document if <code>mark()</code> has not been called.</li>
<li><code>skip(long n)</code> will take you to your current position + n (but not past the end of the document).</li>
</ul>
<p>The behavior of <code>available</code> means you can read in a document in a single read call like this:</p>
<source>
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>
</section>
<section><title>Reading a Document From the Root Directory</title>
<p>If the document resides in the root directory, you can obtain a <code>DocumentInputStream</code> like this:</p>
<source>
// load file system
try
{
DocumentInputStream stream = filesystem.createDocumentInputStream(documentName);
// process data from stream
}
catch (IOException e)
{
// no such document, or the Entry represented by documentName is not a
// DocumentEntry
}</source>
</section>
<section><title>Reading a Document From an Arbitrary Directory</title>
<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>
</section>
</section>
</section>
<section><title>NIO Reading using NPOIFSFileSystem</title>
<p>In this technique for reading, certain key structures are loaded
into memory, and the entire directory tree can be walked by the
application, reading specific documents at leisure.</p>
<p>If you create a NPOIFSFileSystem instance from a File, the memory
footprint is very small. However, if you createa a NPOIFSFileSystem
instance from an input stream, then the whole contents must be
buffered into memory to allow random access. As such, you should
budget on memory use of up to 20% of the file size when using a File,
or up to 120% of the file size when using an InputStream.</p>
<section><title>Preparation</title>
<p>Before an application can read a file from the file system, the
file system needs to be opened and core parts processed. This is done
using the <code>org.apache.poi.poifs.filesystem.NPOIFSFileSystem</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>
// This is the most memory efficient way to open the FileSystem
NPOIFSFileSystem fs;
try
{
fs = new NPOIFSFileSystem(new File(filename));
}
catch (IOException e)
{
// an I/O error occurred, or the InputStream did not provide a compatible
// POIFS data structure
}
DirectoryEntry root = fs.getRoot();
// Using an InputStream requires more memory than using a File
NPOIFSFileSystem fs;
try
{
fs = new NPOIFSFileSystem(inputStream);
}
catch (IOException e)
{
// an I/O error occurred, or the InputStream did not provide a compatible
// POIFS data structure
}
DirectoryEntry root = fs.getRoot();
</source>
<p>Assuming no exception was thrown, the file system can then be read.</p>
<p>One the NPOFSFileSytem is open, you can manipulate it just like
a POIFSFileSytem one.</p>
</section>
</section>
<section><title>Event-Driven Reading</title>
<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>
<section><title>Preparation</title>
<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();
// register for everything
reader.registerListener(myOmnivorousListener);
// register for selective files
reader.registerListener(myPickyListener, "foo");
reader.registerListener(myPickyListener, "bar");
// register for selective files
reader.registerListener(myOtherPickyListener, new POIFSDocumentPath(),
"fubar");
reader.registerListener(myOtherPickyListener, new POIFSDocumentPath(
new String[] { "usr", "bin" ), "fubar");</source>
</section>
<section><title>POIFSReaderListener</title>
<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>
<p>It is also permitted to register more than one <code>POIFSReaderListener</code> for the same document. There is no guarantee of ordering for notification of <code>POIFSReaderListener</code> instances that have registered for the same document when <code>POIFSReader</code> processes that document.</p>
<p>It is guaranteed that all notifications occur in the same thread. A future enhancement may be made to provide multi-threaded notifications, but such an enhancement would very probably be made in a new reader class, a <code>ThreadedPOIFSReader</code> perhaps.</p>
<p>The following table describes the three ways to register a <code>POIFSReaderListener</code> for a document or set of documents:</p>
<table>
<tr>
<td><em>Method Signature</em></td>
<td><em>What it does</em></td>
</tr>
<tr>
<td>registerListener(POIFSReaderListener <em>listener</em>)</td>
<td>registers <em>listener</em> for all documents.</td>
</tr>
<tr>
<td>registerListener(POIFSReaderListener <em>listener</em>, String <em>name</em>)</td>
<td>registers <em>listener</em> for a document with the specified <em>name</em> in the root directory.</td>
</tr>
<tr>
<td>registerListener(POIFSReaderListener <em>listener</em>, POIFSDocumentPath <em>path</em>, String <em>name</em>)</td>
<td>registers <em>listener</em> for a document with the specified <em>name</em> in the directory described by <em>path</em></td>
</tr>
</table>
</section>
<section><title>POIFSDocumentPath</title>
<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>
<td><em>Constructor example</em></td>
<td><em>Directory described</em></td>
</tr>
<tr>
<td>new POIFSDocumentPath()</td>
<td>The root directory.</td>
</tr>
<tr>
<td>new POIFSDocumentPath(null)</td>
<td>The root directory.</td>
</tr>
<tr>
<td>new POIFSDocumentPath(new String[ 0 ])</td>
<td>The root directory.</td>
</tr>
<tr>
<td>new POIFSDocumentPath(new String[ ] { "foo", "bar"} )</td>
<td>in Unix terminology, "/foo/bar".</td>
</tr>
<tr>
<td>new POIFSDocumentPath(new POIFSDocumentPath(new String[] { "foo" }), new String[ ] { "fu", "bar"} )</td>
<td>in Unix terminology, "/foo/fu/bar".</td>
</tr>
</table>
</section>
<section><title>Processing POIFSReaderEvent Events</title>
<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>
</section>
</section>
</section>
<section><title>Writing a File System</title>
<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>
<section><title>The Naming of Names</title>
<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 <em>after</em> the name has been truncated, if the original name was too long to begin with.</li>
</ol>
</section>
<section><title>Creating a Document</title>
<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>
<td><em>Method Signature</em></td>
<td><em>Advantages</em></td>
<td><em>Disadvantages</em></td>
</tr>
<tr>
<td>CreateDocument(String name, InputStream stream)</td>
<td>
Simple API.
</td>
<td>
Increased memory footprint (document is in memory until file system is written).
</td>
</tr>
<tr>
<td>CreateDocument(String name, int size, POIFSWriterListener writer)</td>
<td>
Decreased memory footprint (only very small documents are held in memory, and then only for a short time).
</td>
<td>
More complex API.<br/>
Determining document size in advance may be difficult.<br/>
Lose control over when document is to be written.
</td>
</tr>
</table>
<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>
</section>
<section><title>Creating a Directory</title>
<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>
</section>
<section><title>Using POIFSFileSystem Directly To Create a Document Or Directory</title>
<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>
<td>DirectoryEntry Method Signature</td>
<td>POIFSFileSystem Method Signature</td>
</tr>
<tr>
<td>createDocument(String name, InputStream stream)</td>
<td>createDocument(InputStream stream, String name)</td>
</tr>
<tr>
<td>createDocument(String name, int size, POIFSWriterListener writer)</td>
<td>createDocument(String name, int size, POIFSWriterListener writer)</td>
</tr>
<tr>
<td>createDirectory(String name)</td>
<td>createDirectory(String name)</td>
</tr>
</table>
</section>
</section>
<section><title>Modifying a File System</title>
<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>
<section><title>Removing a Document</title>
<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>
</section>
<section><title>Removing a Directory</title>
<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>
</section>
<section><title>Renaming a File</title>
<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 <em>will</em> 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>
</section>
</section>
</body>
</document>

1297
src/documentation/content/xdocs/poifs/html/POIFSDesignDocument.html Normal file
View File

File diff suppressed because it is too large Load Diff

58
src/documentation/content/xdocs/poifs/index.xml Normal file
View File

@ -0,0 +1,58 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
====================================================================
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
====================================================================
-->
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "../dtd/document-v11.dtd">
<document>
<header>
<title>Apache POI - POIFS - Java implementation of the OLE 2 Compound Document format</title>
<subtitle>Overview</subtitle>
<authors>
<person name="Andrew C. Oliver" email="acoliver@apache.org"/>
<person name="Nicola Ken Barozzi" email="barozzi@nicolaken.com"/>
</authors>
</header>
<body>
<section><title>Overview</title>
<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
based somehow on the POIFS API.</p>
<p>A common confusion is on just what POIFS buys you or what OLE
2 Compound Document format is exactly. POIFS does not buy you
DOC, or XLS, but is necessary to generate or read DOC or XLS
files. You see, all file formats based on the OLE 2 Compound
Document Format have a common structure. The OLE 2 Compound
Document Format is essentially a convoluted archive
format. Think of POIFS as a "zip" library. Once you can get
the data in a zip file you still need to interpret the
data. As a general rule, while all of our formats <em>use</em>
POIFS, most of them attempt to abstract you from it. There
are some circumstances where this is not possible, but as a
general rule this is true.</p>
<p>If you're an end user type just looking to generate XLS
files, then you'd be looking for HSSF not POIFS; however, if
you have legacy code that uses MFC property sets, POIFS is
for you! Regardless, you may or may not need to know how to
use POIFS but ultimately if you use technologies that come
from the POI project, you're using POIFS underneith. Perhaps
we should have a branding campaign "POIFS Inside!". ;-)</p>
</section>
</body>
</document>

653
src/documentation/content/xdocs/poifs/usecases.xml Normal file
View File

@ -0,0 +1,653 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
====================================================================
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
====================================================================
-->
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "../dtd/document-v11.dtd">
<document>
<header>
<title>POIFS Use Cases</title>
<authors>
<person email="mjohnson@apache.org" name="Marc Johnson" id="MJ"/>
</authors>
</header>
<body>
<section><title>POIFS Use Cases</title>
<section><title>Use Case 1: Read existing file system</title>
<table>
<tr>
<td><em>Primary Actor:</em></td>
<td>POIFS client</td>
</tr>
<tr>
<td><em>Scope:</em></td>
<td>POIFS</td>
</tr>
<tr>
<td><em>Level:</em></td>
<td>Summary</td>
</tr>
<tr>
<td><em>Stakeholders and Interests:</em></td>
<td>
POIFS client- wants to read content of file
system<br/>
POIFS - understands POIFS file system
</td>
</tr>
<tr>
<td><em>Precondition:</em></td>
<td>None</td>
</tr>
<tr>
<td><em>Minimal Guarantee:</em></td>
<td>None</td>
</tr>
<tr>
<td><em>Main Success Guarantee:</em></td>
<td>
1. POIFS client requests POIFS to read a POIFS file
system, providing an
<code>InputStream</code>
containing POIFS file system in question.<br/>
2. POIFS reads from the
<code>InputStream</code> in
512 byte blocks.<br/>
3. POIFS verifies that the first block begins with
the well known signature
(
<code>0xE11AB1A1E011CFD0</code>)<br/>
4. POIFS reads the Block Allocation Table from the
first block and, if necessary, from the XBAT
blocks.<br/>
5. POIFS obtains the start block of the Property
Table and reads the Property Table (use case 9,
read file)<br/>
6. POIFS reads the individual entries in the Property
Table<br/>
7. POIFS obtains the start block of the Small Block
Allocation Table and reads the Small Block
Allocation Table (use case 9, read file)<br/>
8. POIFS obtains the start block of the Small Block
store from the first entry in the Property Table
and reads the Small Block Array (use case 9, read
file)<br/>
</td>
</tr>
<tr>
<td><em>Extensions:</em></td>
<td>
2a. If the last block read is not a 512 byte
block, the
<code>InputStream</code> is not that of
a POIFS file system, and POIFS throws an
appropriate exception.
<br/>
3a. If the signature is incorrect, the
<code>InputStream</code> is not that of a POIFS
file system, and POIFS throws an appropriate
exception.<br/>
</td>
</tr>
</table>
</section>
<section><title>Use Case 2: Write file system</title>
<table>
<tr>
<th>Primary Actor:</th>
<th>POIFS client</th>
</tr>
<tr>
<th>Scope:</th>
<td>POIFS</td>
</tr>
<tr>
<th>Level:</th>
<td>Summary</td>
</tr>
<tr>
<th>Stakeholders and Interests:</th>
<td>
POIFS client- wants to write file system out.<br/>
POIFS - knows how to write file system out.
</td>
</tr>
<tr>
<th>Precondition:</th>
<td>
File system has been read (use case 1, read
existing file system) and subsequently modified
(use case 4, replace file in file system; use case
5, delete file from file system; or use case 6,
write new file to file system; in any
combination)
<br/>or<br/>
File system has been created (use case 3, create
new file system)
</td>
</tr>
<tr>
<th>Minimal Guarantee:</th>
<td>None</td>
</tr>
<tr>
<th>Main Success Guarantee:</th>
<td>
1. POIFS client provides an
<code>OutputStream</code>
to write the file system to.
<br/>
2. POIFS gets the sizes of the Property Table and
each file in the file system.<br/>
3. If any files in the file system requires storage
in a Small Block Array, POIFS creates a Small
Block Array of sufficient size to hold all of the
small files.<br/>
4. POIFS calculates the number of big blocks needed
to hold all of the large files, the Property
Table, and, if necessary, the Small Block Array
and the Small Block Allocation Table.<br/>
5. POIFS creates a set of big blocks sufficient to
store the Block Allocation Table<br/>
6. POIFS creates and writes the header block<br/>
7. POIFS writes out the XBAT blocks, if needed.<br/>
8. POIFS writes out the Small Block Array, if
needed<br/>
9. POIFS writes out the Small Block Allocation Table,
if needed<br/>
10. POIFS writes out the Property Table<br/>
11. POIFS writes out the large files, if needed<br/>
12. POIFS closes the <code>OutputStream</code>.
</td>
</tr>
<tr>
<th>Extensions:</th>
<td>
6a. Exceptions writing to the
<code>OutputStream</code> will be propagated back
to the POIFS client.
<br/>
7a. Exceptions writing to the
<code>OutputStream</code> will be propagated back
to the POIFS client.
<br/>
8a. Exceptions writing to the
<code>OutputStream</code> will be propagated back
to the POIFS client.
<br/>
9a. Exceptions writing to the
<code>OutputStream</code> will be propagated back
to the POIFS client.
<br/>
10a. Exceptions writing to the
<code>OutputStream</code> will be propagated back
to the POIFS client.
<br/>
11a. Exceptions writing to the
<code>OutputStream</code> will be propagated back
to the POIFS client.
<br/>
12a. Exceptions closing the
<code>OutputStream</code> will be propagated back
to the POIFS client.
<br/>
</td>
</tr>
</table>
</section>
<section><title>Use Case 3: Create new file system</title>
<table>
<tr>
<th>Primary Actor:</th>
<td>POIFS client</td>
</tr>
<tr>
<th>Scope:</th>
<td>POIFS</td>
</tr>
<tr>
<th>Level:</th>
<td>Summary</td>
</tr>
<tr>
<th>Stakeholders and Interests:</th>
<td>
POIFS client- wants to create a new file
system<br/>
POIFS - knows how to create a new file system
</td>
</tr>
<tr>
<th>Precondition:</th>
<td>None</td>
</tr>
<tr>
<th>Minimal Guarantee:</th>
<td>None</td>
</tr>
<tr>
<th>Main Success Guarantee:</th>
<td>
POIFS creates an empty Property Table.
</td>
</tr>
<tr>
<th>Extensions:</th>
<td>None</td>
</tr>
</table>
</section>
<section><title>Use Case 4: Replace file in file system</title>
<table>
<tr>
<td><em>Primary Actor:</em></td>
<td>POIFS client</td>
</tr>
<tr>
<td><em>Scope:</em></td>
<td>POIFS</td>
</tr>
<tr>
<td><em>Level:</em></td>
<td>Summary</td>
</tr>
<tr>
<td><em>Stakeholders and Interests:</em></td>
<td>
1. POIFS client- wants to replace an existing file in
the file system<br/>
2. POIFS - knows how to manage the file system
</td>
</tr>
<tr>
<td><em>Precondition:</em></td>
<td>
Either
<br/><br/>
The file system has been read (use case 1, read
existing file system) and a file has been
extracted from the file system (use case 7, read
existing file from file system)
<br/><br/>or<br/><br/>
The file system has been created (use case 3,
create new file system) and a file has been
written to the file system (use case 6, write new
file to file system)
</td>
</tr>
<tr>
<td><em>Minimal Guarantee:</em></td>
<td>None</td>
</tr>
<tr>
<td><em>Main Success Guarantee:</em></td>
<td>
1. POIFS discards storage of the existing file.<br/>
2. POIFS updates the existing file's entry in the
Property Table<br/>
3. POIFS stores the new file's data
</td>
</tr>
<tr>
<td><em>Extensions:</em></td>
<td>
1a. POIFS throws an exception if the file does not
exist.
</td>
</tr>
</table>
</section>
<section><title>Use Case 5: Delete file from file system</title>
<table>
<tr>
<td><em>Primary Actor:</em></td>
<td>POIFS client</td>
</tr>
<tr>
<td><em>Scope:</em></td>
<td>POIFS</td>
</tr>
<tr>
<td><em>Level:</em></td>
<td>Summary</td>
</tr>
<tr>
<td><em>Stakeholders and Interests:</em></td>
<td>
* POIFS client- wants to remove a file from a file
system<br/>
* POIFS - knows how to manage the file system
</td>
</tr>
<tr>
<td><em>Precondition:</em></td>
<td>
Either<br/><br/>
The file system has been read (use case 1, read
existing file system) and a file has been
extracted from the file system (use case 7, read
existing file from file system)<br/>
<br/>
or<br/>
<br/>
The file system has been created (use case 3,
create new file system) and a file has been
written to the file system (use case 6, write new
file to file system)
</td>
</tr>
<tr>
<td><em>Minimal Guarantee:</em></td>
<td>None</td>
</tr>
<tr>
<td><em>Main Success Guarantee:</em></td>
<td>
1. POIFS discards the specified file's storage.<br/>
2. POIFS discards the file's Property Table
entry.
</td>
</tr>
<tr>
<td><em>Extensions:</em></td>
<td>
1a. POIFS throws an exception if the file does not
exist.
</td>
</tr>
</table>
</section>
<section><title>Use Case 6: Write new file to file system</title>
<table>
<tr>
<td><em>Primary Actor:</em></td>
<td>POIFS client</td>
</tr>
<tr>
<td><em>Scope:</em></td>
<td>POIFS</td>
</tr>
<tr>
<td><em>Level:</em></td>
<td>Summary</td>
</tr>
<tr>
<td><em>Stakeholders and Interests:</em></td>
<td>
* POIFS client- wants to add a new file to the file
system<br/>
* POIFS - knows how to manage the file system
</td>
</tr>
<tr>
<td><em>Precondition:</em></td>
<td>The specified file does not yet exist in the file
system</td>
</tr>
<tr>
<td><em>Minimal Guarantee:</em></td>
<td>None</td>
</tr>
<tr>
<td><em>Main Success Guarantee:</em></td>
<td>
1. The POIFS client provides a file name<br/>
2. POIFS creates a new Property Table entry for the
new file<br/>
3. POIFS provides the POIFS client with an
<code>OutputStream</code> to write to.<br/>
4. The POIFS client writes data to the provided
<code>OutputStream</code>.<br/>
5. The POIFS client closes the provided
<code>OutputStream</code><br/>
6. POIFS updates the Property Table entry with the
new file's size
</td>
</tr>
<tr>
<td><em>Extensions:</em></td>
<td>
1a. POIFS throws an exception if a file with the
specified name already exists in the file
system.<br/>
1b. POIFS throws an exception if the file name is
too long. The limit on file name length is 31
characters.
</td>
</tr>
</table>
</section>
<section><title>Use Case 7: Read existing file from file system</title>
<table>
<tr>
<td><em>Primary Actor:</em></td>
<td>POIFS client</td>
</tr>
<tr>
<td><em>Scope:</em></td>
<td>POIFS</td>
</tr>
<tr>
<td><em>Level:</em></td>
<td>Summary</td>
</tr>
<tr>
<td><em>Stakeholders and Interests:</em></td>
<td>
* POIFS client- wants to read a file from the file
system<br/>
* POIFS - knows how to manage the file system
</td>
</tr>
<tr>
<td><em>Precondition:</em></td>
<td>
* The file system has been read (use case 1, read
existing file system) or has been created and
written to (use case 3, create new file system;
use case 6, write new file to file system).<br/>
* The specified file exists in the file system.
</td>
</tr>
<tr>
<td><em>Minimal Guarantee:</em></td>
<td>None</td>
</tr>
<tr>
<td><em>Main Success Guarantee:</em></td>
<td>
* The POIFS client provides the name of a file to be read <br/>
* POIFS provides an <code>InputStream</code> to read from. <br/>
* The POIFS client reads from the <code>InputStream</code>.<br/>
* The POIFS client closes the <code>InputStream</code>.
</td>
</tr>
<tr>
<td><em>Extensions:</em></td>
<td>1a. POIFS throws an exception if no file with the
specified name exists.</td>
</tr>
</table>
</section>
<section><title>Use Case 8: Read file system directory</title>
<table>
<tr>
<td><em>Primary Actor:</em></td>
<td>POIFS client</td>
</tr>
<tr>
<td><em>Scope:</em></td>
<td>POIFS</td>
</tr>
<tr>
<td><em>Level:</em></td>
<td>Summary</td>
</tr>
<tr>
<td><em>Stakeholders and Interests:</em></td>
<td>
* POIFS client- wants to know what files exist in
the file system<br/>
* POIFS - knows how to manage the file system
</td>
</tr>
<tr>
<td><em>Precondition:</em></td>
<td>The file system has been read (use case 1, read
existing file system) or created (use case 3, create
new file system)</td>
</tr>
<tr>
<td><em>Minimal Guarantee:</em></td>
<td>None</td>
</tr>
<tr>
<td><em>Main Success Guarantee:</em></td>
<td>
1. The POIFS client requests the file system
directory.
2. POIFS returns an <code>Iterator</code>. The
<code>Iterator</code> will not include the root
entry in the Property Table, and may be an
<code>Iterator</code> over an empty
<code>Collection</code>.
</td>
</tr>
<tr>
<td><em>Extensions:</em></td>
<td>None</td>
</tr>
</table>
</section>
<section><title>Use Case 9: Read file</title>
<table>
<tr>
<td><em>Primary Actor:</em></td>
<td>POIFS</td>
</tr>
<tr>
<td><em>Scope:</em></td>
<td>POIFS</td>
</tr>
<tr>
<td><em>Level:</em></td>
<td>Summary</td>
</tr>
<tr>
<td><em>Stakeholders and Interests:</em></td>
<td>
POIFS - POIFS needs to read a file, or something
resembling a file (i.e., the Property Table, the
Small Block Array, or the Small Block Allocation
Table)
</td>
</tr>
<tr>
<td><em>Precondition:</em></td>
<td>None</td>
</tr>
<tr>
<td><em>Minimal Guarantee:</em></td>
<td>None</td>
</tr>
<tr>
<td><em>Main Success Guarantee:</em></td>
<td>
1. POIFS begins with a start block, a file size, and
a flag indicating whether to use the Big Block
Allocation Table or the Small Block Allocation
Table<br/>
2. POIFS returns an <code>InputStream</code>.<br/>
3. Reads from the <code>InputStream</code> are
performed by walking the specified Block
Allocation Table and reading the blocks
indicated.<br/>
4. POIFS closes the <code>InputStream</code> when
finished reading the file, or its client wants to
close the <code>InputStream</code>.
</td>
</tr>
<tr>
<td><em>Extensions:</em></td>
<td>3a. An exception will be thrown if the specified Block
Allocation Table is corrupt, as evidenced by an index
pointing to a non-existent block, or by a chain
extending past the known size of the file.</td>
</tr>
</table>
</section>
<section><title>Use Case 10: Rename existing file in the file system</title>
<table>
<tr>
<td><em>Primary Actor:</em></td>
<td>POIFS client</td>
</tr>
<tr>
<td><em>Scope:</em></td>
<td>POIFS</td>
</tr>
<tr>
<td><em>Level:</em></td>
<td>Summary</td>
</tr>
<tr>
<td><em>Stakeholders and Interests:</em></td>
<td>
* POIFS client- wants to rename an existing file in
the file system.<br/>
* POIFS - knows how to manage the file system.
</td>
</tr>
<tr>
<td><em>Precondition:</em></td>
<td>
* The file system is has been read (use case 1, read
existing file system) or has been created and
written to (use case 3, create new file system;
use case 6, write new file to file system.<br/>
* The specified file exists in the file system.<br/>
* The new name for the file does not duplicate
another file in the file system.
</td>
</tr>
<tr>
<td><em>Minimal Guarantee:</em></td>
<td>None</td>
</tr>
<tr>
<td><em>Main Success Guarantee:</em></td>
<td>
1. POIFS updates the Property Table entry for the
specified file with its new name.
</td>
</tr>
<tr>
<td><em>Extensions:</em></td>
<td>
* 1a. If the old file name is not in the file
system, POIFS throws an exception.<br/>
* 1b. If the new file name already exists in the
file system, POIFS throws an exception.<br/>
* 1c. If the new file name is too long (the limit is
31 characters), POIFS throws an exception.
</td>
</tr>
</table>
</section>
</section>
</body>
</document>

38
src/documentation/content/xdocs/references/book.xml Normal file
View File

@ -0,0 +1,38 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
====================================================================
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
====================================================================
-->
<!DOCTYPE book PUBLIC "-//APACHE//DTD Cocoon Documentation Book V1.0//EN" "./dtd/book-cocoon-v10.dtd">
<book software="POI"
title="POI Project Documentation"
copyright="@year@ POI Project"
xmlns:xlink="http://www.w3.org/1999/xlink">
<menu label="Apache POI">
<menu-item label="Top" href="../index.html"/>
</menu>
<menu label="References">
<menu-item label="Live Sites" href="index.html"/>
<menu-item label="XLS spec [PDF]" href="http://sc.openoffice.org/excelfileformat.pdf"/>
<menu-item label="Apache Cocoon" href="http://xml.apache.org/cocoon/"/>
</menu>
</book>

66
src/documentation/content/xdocs/references/index.xml Normal file
View File

@ -0,0 +1,66 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
====================================================================
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
====================================================================
-->
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "./dtd/document-v11.dtd">
<document>
<header>
<title>Live Sites using Poi</title>
<authors>
<person name="Donald Ball" email="balld@webslingerZ.com"/>
<person name="Stefano Mazzocchi" email="stefano@apache.org"/>
<person name="Robin Green" email="greenrd@hotmail.com"/>
<person name="Nicola Ken Barozzi" email="barozzi@nicolaken.com"/>
<person name="Glen Stampoultzis" email="user@poi.apache.org"/>
<person name="Rainer Klute" email="klute@rainer-klute.org"/>
</authors>
</header>
<body>
<section><title>References</title>
<section><title>Live Sites using POI</title>
<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.</p>
<!--
<ul>
<li><link href=""></link></li>
</ul>
-->
</section>
<section><title>Products/Projects using POI</title>
<p>Publically available products/projects using POI include:</p>
<ul>
<li><link href="http://jtimetracker.sourceforge.net/">JTimeTracker</link></li>
</ul>
</section>
<section><title>File Format Descriptions</title>
<p>POI depends on publically available documents describing various
file formats. The list below contains links to some of them.</p>
<ul>
<li><link href="http://www.wotsit.org/">Wotsit's Format</link></li>
</ul>
</section>
</section>
</body>
</document>

40
src/documentation/content/xdocs/resolutions/book.xml Normal file
View File

@ -0,0 +1,40 @@
<?xml version="1.0"?>
<!--
====================================================================
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
====================================================================
-->
<!DOCTYPE book PUBLIC "-//APACHE//DTD Cocoon Documentation Book V1.0//EN" "../dtd/book-cocoon-v10.dtd">
<book software="POI Project"
title="Resolutions"
copyright="@year@ POI Project">
<menu label="Apache POI">
<menu-item label="Top" href="../index.html"/>
</menu>
<menu label="About">
<menu-item label="About" href="index.html"/>
</menu>
<menu label="Resolutions">
<menu-item label="Coding Standards" href="res001.html"/>
</menu>
</book>

55
src/documentation/content/xdocs/resolutions/index.xml Normal file
View File

@ -0,0 +1,55 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
====================================================================
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
====================================================================
-->
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "../dtd/document-v11.dtd">
<document>
<header>
<title>Resolutions</title>
<subtitle>About this section</subtitle>
<authors>
<person name="Andrew C. Oliver" email="acoliver@apache.org"/>
</authors>
</header>
<body>
<section><title>About Resolutions</title>
<p>
Every project in Apache has resolutions that they vote on.
Decisions are made, etc. But what happens once those decisions
are made? They are archived in the mail list archive never to
be read again (once its not in the top 10 or so posts). So they
get discussed again and again.
</p>
<p>
Rather than have that big waste of time, we have this section to
record important POI decisions. Once a decision is passed it
need only be linked to this page (either by creating a page for
it or by simply linking it to the archive messages). Wherever
possible a brief about how many votes for and against an maybe
some background should be posted.
</p>
<p>
This section is intended mainly to reduce big waste of time
discussions from taking away from whats important...developing
POI! :-D
</p>
</section>
</body>
</document>

113
src/documentation/content/xdocs/resolutions/res001.xml Normal file
View File

@ -0,0 +1,113 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
====================================================================
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
====================================================================
-->
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "../dtd/document-v11.dtd">
<document>
<header>
<title>POI Resoluton</title>
<subtitle>Resolution 001 - Minimal Coding Standards</subtitle>
<authors>
<person name="Andrew C. Oliver" email="acoliver@apache.org"/>
</authors>
</header>
<body>
<section><title>Resolution 001 - Minimal Coding Standards</title>
<section><title>Majority Position</title>
<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
can be a good thing. Each can learn from the different
styles by working with different code. That being said
there are some universal "good quality" guidelines that
must be adopted on a project of any proportions.
</p>
<p>
Marc Johnson Authored the following resolution:
</p>
<p>
On Tue, 2002-01-08 at 22:23, Marc Johnson wrote:
Standards are wonderful; everyone should have a set.
Here's what I propose for coding standards for POI WRT comments (should I
feel the need, I'll post more of these little gems):
</p>
<ol>
<li>
All classes and interfaces MUST have, right at the
beginning of the file, the Apache Software License
2.0 License Header. (see /legal/LICENSE).
</li>
<li>
All classes and interfaces MUST include class javadoc. Conventionally,
this goes after the package and imports, and before the start of the class
or interface.
<!-- No more author tags -->
<!-- The class javadoc MUST have at least one @author tag -->
</li>
<li>
All methods that are accessible outside the class MUST have javadoc
comments. In other words, if it isn't private, it MUST have javadoc
comments. Simple getters can consist of a simple @return tag; simple setters
can consist of a simple @param tag. Anything else requires some verbiage
plus all the standard javadoc tags as appropriate. You MUST include @throws
or @exception for any non-runtime exceptions, and you SHOULD document any
runtime exceptions you expect to throw. @throws/@exception tags SHOULD
include an explanation of why that exception would be thrown. If your method
might return null, you MUST say so. An accompanying explanation of the
circumstances for doing so would be nice.
</li>
</ol>
</section>
<section><title>Amendments (informal by extension and not by vote)</title>
<section><title>License</title>
<p>
As opposed to the formerly used POI License (which was
based on the Apache Public License), now that POI is
part of Apache, use the standard Apache Software
License 2.0 header. As per standard Apache Software
Foundation policy, the full (long) version of the
header should be used.
</p>
</section>
<section><title>2 cents</title>
<p>
Tip: No laughing or joking allowed in conversations regarding coding
standards.
Any mail on coding standards will be treated very seriously,
and sent here with a RTFM.
</p>
</section>
</section>
<section><title>Dissent</title>
<p>
The motion was passed unanimously with no negative or
neutral votes.
</p>
</section>
<section><title>Comments</title>
<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>
</section>
</section>
</body>
</document>

51
src/documentation/content/xdocs/site.xml Normal file
View File

@ -0,0 +1,51 @@
<?xml version="1.0"?>
<!--
====================================================================
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
====================================================================
-->
<!--
Forrest site.xml
This file contains an outline of the site's information content. It is used to:
- Generate the website menus (though these can be overridden - see docs)
- Provide semantic, location-independent aliases for internal 'site:' URIs, eg
<link href="site:changes"> links to changes.html (or ../changes.html if in
subdir).
- Provide aliases for external URLs in the external-refs section. Eg, <link
href="ext:cocoon"> links to http://xml.apache.org/cocoon/
See http://xml.apache.org/forrest/linking.html for more info
-->
<site label="POI" href="" xmlns="http://apache.org/forrest/linkmap/1.0">
<external-refs>
<xml.apache.org href="http://xml.apache.org/">
<forrest href="forrest/">
<validation href="validation.html"/>
<webapp href="your-project.html#webapp"/>
</forrest>
<cocoon href="cocoon/"/>
</xml.apache.org>
<junit href="junit/index.html"/>
<jdepend href="jdepend/index.html"/>
<javadoc href="apidocs/index.html"/>
<download href="http://www.apache.org/dyn/closer.cgi/poi/"/>
</external-refs>
</site>

38
src/documentation/content/xdocs/slideshow/book.xml Normal file
View File

@ -0,0 +1,38 @@
<?xml version="1.0"?>
<!--
====================================================================
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
====================================================================
-->
<!DOCTYPE book PUBLIC "-//APACHE//DTD Cocoon Documentation Book V1.0//EN" "../dtd/book-cocoon-v10.dtd">
<book software="POI Project"
title="HSLF"
copyright="@year@ POI Project">
<menu label="Apache POI">
<menu-item label="Top" href="../index.html"/>
</menu>
<menu label="HSLF">
<menu-item label="Overview" href="index.html"/>
<menu-item label="Quick Guide" href="quick-guide.html"/>
<menu-item label="HSLF Cookbok" href="how-to-shapes.html"/>
<menu-item label="XSLF Cookbok" href="xslf-cookbook.html"/>
<menu-item label="PPT File Format" href="ppt-file-format.html"/>
</menu>
</book>

668
src/documentation/content/xdocs/slideshow/how-to-shapes.xml Normal file
View File

@ -0,0 +1,668 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
====================================================================
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
====================================================================
-->
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "../dtd/document-v11.dtd">
<document>
<header>
<title>Busy Developers' Guide to HSLF drawing layer</title>
<authors>
<person email="yegor@dinom.ru" name="Yegor Kozlov" id="CO"/>
</authors>
</header>
<body>
<section><title>Busy Developers' Guide to HSLF drawing layer</title>
<section><title>Index of Features</title>
<ul>
<li><link href="#NewPresentation">How to create a new presentation and add new slides to it</link></li>
<li><link href="#PageSize">How to retrieve or change slide size</link></li>
<li><link href="#GetShapes">How to get shapes contained in a particular slide</link></li>
<li><link href="#Shapes">Drawing a shape on a slide</link></li>
<li><link href="#Pictures">How to work with pictures</link></li>
<li><link href="#SlideTitle">How to set slide title</link></li>
<li><link href="#Fill">How to work with slide/shape background</link></li>
<li><link href="#Bullets">How to create bulleted lists</link></li>
<li><link href="#Hyperlinks">Hyperlinks</link></li>
<li><link href="#Tables">Tables</link></li>
<li><link href="#RemoveShape">How to remove shapes</link></li>
<li><link href="#OLE">How to retrieve embedded OLE objects</link></li>
<li><link href="#Sound">How to retrieve embedded sounds</link></li>
<li><link href="#Freeform">How to create shapes of arbitrary geometry</link></li>
<li><link href="#Graphics2D">Shapes and Graphics2D</link></li>
<li><link href="#Render">How to convert slides into images</link></li>
<li><link href="#HeadersFooters">Headers / Footers</link></li>
</ul>
</section>
<section><title>Features</title>
<anchor id="NewPresentation"/>
<section><title>New Presentation</title>
<source>
//create a new empty slide show
SlideShow ppt = new SlideShow();
//add first slide
Slide s1 = ppt.createSlide();
//add second slide
Slide s2 = ppt.createSlide();
//save changes in a file
FileOutputStream out = new FileOutputStream("slideshow.ppt");
ppt.write(out);
out.close();
</source>
</section>
<anchor id="PageSize"/>
<section><title>How to retrieve or change slide size</title>
<source>
SlideShow ppt = new SlideShow(new HSLFSlideShow("slideshow.ppt"));
//retrieve page size. Coordinates are expressed in points (72 dpi)
java.awt.Dimension pgsize = ppt.getPageSize();
int pgx = pgsize.width; //slide width
int pgy = pgsize.height; //slide height
//set new page size
ppt.setPageSize(new java.awt.Dimension(1024, 768));
//save changes
FileOutputStream out = new FileOutputStream("slideshow.ppt");
ppt.write(out);
out.close();
</source>
</section>
<anchor id="GetShapes"/>
<section><title>How to get shapes contained in a particular slide</title>
<p>
The following code demonstrates how to iterate over shapes for each slide.
</p>
<source>
SlideShow ppt = new SlideShow(new HSLFSlideShow("slideshow.ppt"));
//get slides
Slide[] slide = ppt.getSlides();
for (int i = 0; i &lt; slide.length; i++){
Shape[] sh = slide[i].getShapes();
for (int j = 0; j &lt; sh.length; j++){
//name of the shape
String name = sh[j].getShapeName();
//shapes's anchor which defines the position of this shape in the slide
java.awt.Rectangle anchor = sh[j].getAnchor();
if (sh[j] instanceof Line){
Line line = (Line)sh[j];
//work with Line
} else if (sh[j] instanceof AutoShape){
AutoShape shape = (AutoShape)sh[j];
//work with AutoShape
} else if (sh[j] instanceof TextBox){
TextBox shape = (TextBox)sh[j];
//work with TextBox
} else if (sh[j] instanceof Picture){
Picture shape = (Picture)sh[j];
//work with Picture
}
}
}
</source>
</section>
<anchor id="Shapes"/>
<section><title>Drawing a shape on a slide</title>
<warning>
To work with graphic objects HSLF uses Java2D classes
that may throw exceptions if graphical environment is not available. In case if graphical environment
is not available, you must tell Java that you are running in headless mode and
set the following system property: <code> java.awt.headless=true </code>
(either via <code>-Djava.awt.headless=true</code> startup parameter or via <code>System.setProperty("java.awt.headless", "true")</code>).
</warning>
<p>
When you add a shape, you usually specify the dimensions of the shape and the position
of the upper left corner of the bounding box for the shape relative to the upper left
corner of the slide. Distances in the drawing layer are measured in points (72 points = 1 inch).
</p>
<source>
SlideShow ppt = new SlideShow();
Slide slide = ppt.createSlide();
//Line shape
Line line = new Line();
line.setAnchor(new java.awt.Rectangle(50, 50, 100, 20));
line.setLineColor(new Color(0, 128, 0));
line.setLineStyle(Line.LINE_DOUBLE);
slide.addShape(line);
//TextBox
TextBox txt = new TextBox();
txt.setText("Hello, World!");
txt.setAnchor(new java.awt.Rectangle(300, 100, 300, 50));
//use RichTextRun to work with the text format
RichTextRun rt = txt.getTextRun().getRichTextRuns()[0];
rt.setFontSize(32);
rt.setFontName("Arial");
rt.setBold(true);
rt.setItalic(true);
rt.setUnderlined(true);
rt.setFontColor(Color.red);
rt.setAlignment(TextBox.AlignRight);
slide.addShape(txt);
//Autoshape
//32-point star
AutoShape sh1 = new AutoShape(ShapeTypes.Star32);
sh1.setAnchor(new java.awt.Rectangle(50, 50, 100, 200));
sh1.setFillColor(Color.red);
slide.addShape(sh1);
//Trapezoid
AutoShape sh2 = new AutoShape(ShapeTypes.Trapezoid);
sh2.setAnchor(new java.awt.Rectangle(150, 150, 100, 200));
sh2.setFillColor(Color.blue);
slide.addShape(sh2);
FileOutputStream out = new FileOutputStream("slideshow.ppt");
ppt.write(out);
out.close();
</source>
</section>
<anchor id="Pictures"/>
<section><title>How to work with pictures</title>
<p>
Currently, HSLF API supports the following types of pictures:
</p>
<ul>
<li>Windows Metafiles (WMF)</li>
<li>Enhanced Metafiles (EMF)</li>
<li>JPEG Interchange Format</li>
<li>Portable Network Graphics (PNG)</li>
<li>Macintosh PICT</li>
</ul>
<source>
SlideShow ppt = new SlideShow(new HSLFSlideShow("slideshow.ppt"));
//extract all pictures contained in the presentation
PictureData[] pdata = ppt.getPictureData();
for (int i = 0; i &lt; pdata.length; i++){
PictureData pict = pdata[i];
// picture data
byte[] data = pict.getData();
int type = pict.getType();
String ext;
switch (type){
case Picture.JPEG: ext=".jpg"; break;
case Picture.PNG: ext=".png"; break;
case Picture.WMF: ext=".wmf"; break;
case Picture.EMF: ext=".emf"; break;
case Picture.PICT: ext=".pict"; break;
default: continue;
}
FileOutputStream out = new FileOutputStream("pict_"+i + ext);
out.write(data);
out.close();
}
// add a new picture to this slideshow and insert it in a new slide
int idx = ppt.addPicture(new File("clock.jpg"), Picture.JPEG);
Picture pict = new Picture(idx);
//set image position in the slide
pict.setAnchor(new java.awt.Rectangle(100, 100, 300, 200));
Slide slide = ppt.createSlide();
slide.addShape(pict);
//now retrieve pictures containes in the first slide and save them on disk
slide = ppt.getSlides()[0];
Shape[] sh = slide.getShapes();
for (int i = 0; i &lt; sh.length; i++){
if (sh[i] instanceof Picture){
Picture pict = (Picture)sh[i];
PictureData pictData = pict.getPictureData();
byte[] data = pictData.getData();
int type = pictData.getType();
if (type == Picture.JPEG){
FileOutputStream out = new FileOutputStream("slide0_"+i+".jpg");
out.write(data);
out.close();
} else if (type == Picture.PNG){
FileOutputStream out = new FileOutputStream("slide0_"+i+".png");
out.write(data);
out.close();
}
}
}
FileOutputStream out = new FileOutputStream("slideshow.ppt");
ppt.write(out);
out.close();
</source>
</section>
<anchor id="SlideTitle"/>
<section><title>How to set slide title</title>
<source>
SlideShow ppt = new SlideShow();
Slide slide = ppt.createSlide();
TextBox title = slide.addTitle();
title.setText("Hello, World!");
//save changes
FileOutputStream out = new FileOutputStream("slideshow.ppt");
ppt.write(out);
out.close();
</source>
<p>
Below is the equivalent code in PowerPoint VBA:
</p>
<source>
Set myDocument = ActivePresentation.Slides(1)
myDocument.Shapes.AddTitle.TextFrame.TextRange.Text = "Hello, World!"
</source>
</section>
<anchor id="Fill"/>
<section><title>How to modify background of a slide master</title>
<source>
SlideShow ppt = new SlideShow();
SlideMaster master = ppt.getSlidesMasters()[0];
Fill fill = master.getBackground().getFill();
int idx = ppt.addPicture(new File("background.png"), Picture.PNG);
fill.setFillType(Fill.FILL_PICTURE);
fill.setPictureData(idx);
</source>
</section>
<section><title>How to modify background of a slide</title>
<source>
SlideShow ppt = new SlideShow();
Slide slide = ppt.createSlide();
//This slide has its own background.
//Without this line it will use master's background.
slide.setFollowMasterBackground(false);
Fill fill = slide.getBackground().getFill();
int idx = ppt.addPicture(new File("background.png"), Picture.PNG);
fill.setFillType(Fill.FILL_PATTERN);
fill.setPictureData(idx);
</source>
</section>
<section><title>How to modify background of a shape</title>
<source>
SlideShow ppt = new SlideShow();
Slide slide = ppt.createSlide();
Shape shape = new AutoShape(ShapeTypes.Rectangle);
shape.setAnchor(new java.awt.Rectangle(100, 100, 200, 200));
Fill fill = shape.getFill();
fill.setFillType(Fill.FILL_SHADE);
fill.setBackgroundColor(Color.red);
fill.setForegroundColor(Color.green);
slide.addShape(shape);
</source>
</section>
<anchor id="Bullets"/>
<section><title>How to create bulleted lists</title>
<source>
SlideShow ppt = new SlideShow();
Slide slide = ppt.createSlide();
TextBox shape = new TextBox();
RichTextRun rt = shape.getTextRun().getRichTextRuns()[0];
shape.setText(
"January\r" +
"February\r" +
"March\r" +
"April");
rt.setFontSize(42);
rt.setBullet(true);
rt.setBulletOffset(0); //bullet offset
rt.setTextOffset(50); //text offset (should be greater than bullet offset)
rt.setBulletChar('\u263A'); //bullet character
slide.addShape(shape);
shape.setAnchor(new java.awt.Rectangle(50, 50, 500, 300)); //position of the text box in the slide
slide.addShape(shape);
FileOutputStream out = new FileOutputStream("bullets.ppt");
ppt.write(out);
out.close();
</source>
</section>
<anchor id="Hyperlinks"/>
<section><title>How to read hyperlinks from a slide show</title>
<source>
FileInputStream is = new FileInputStream("slideshow.ppt");
SlideShow ppt = new SlideShow(is);
is.close();
Slide[] slide = ppt.getSlides();
for (int j = 0; j &lt; slide.length; j++) {
//read hyperlinks from the text runs
TextRun[] txt = slide[j].getTextRuns();
for (int k = 0; k &lt; txt.length; k++) {
String text = txt[k].getText();
Hyperlink[] links = txt[k].getHyperlinks();
if(links != null) for (int l = 0; l &lt; links.length; l++) {
Hyperlink link = links[l];
String title = link.getTitle();
String address = link.getAddress();
String substring = text.substring(link.getStartIndex(), link.getEndIndex()-1); //in ppt end index is inclusive
}
}
//in PowerPoint you can assign a hyperlink to a shape without text,
//for example to a Line object. The code below demonstrates how to
//read such hyperlinks
Shape[] sh = slide[j].getShapes();
for (int k = 0; k &lt; sh.length; k++) {
Hyperlink link = sh[k].getHyperlink();
if(link != null) {
String title = link.getTitle();
String address = link.getAddress();
}
}
}
</source>
</section>
<anchor id="Tables"/>
<section><title>How to create tables</title>
<source>
//table data
String[][] data = {
{"INPUT FILE", "NUMBER OF RECORDS"},
{"Item File", "11,559"},
{"Vendor File", "300"},
{"Purchase History File", "10,000"},
{"Total # of requisitions", "10,200,038"}
};
SlideShow ppt = new SlideShow();
Slide slide = ppt.createSlide();
//create a table of 5 rows and 2 columns
Table table = new Table(5, 2);
for (int i = 0; i &lt; data.length; i++) {
for (int j = 0; j &lt; data[i].length; j++) {
TableCell cell = table.getCell(i, j);
cell.setText(data[i][j]);
RichTextRun rt = cell.getTextRun().getRichTextRuns()[0];
rt.setFontName("Arial");
rt.setFontSize(10);
cell.setVerticalAlignment(TextBox.AnchorMiddle);
cell.setHorizontalAlignment(TextBox.AlignCenter);
}
}
//set table borders
Line border = table.createBorder();
border.setLineColor(Color.black);
border.setLineWidth(1.0);
table.setAllBorders(border);
//set width of the 1st column
table.setColumnWidth(0, 300);
//set width of the 2nd column
table.setColumnWidth(1, 150);
slide.addShape(table);
table.moveTo(100, 100);
FileOutputStream out = new FileOutputStream("hslf-table.ppt");
ppt.write(out);
out.close();
</source>
</section>
<anchor id="RemoveShape"/>
<section><title>How to remove shapes from a slide</title>
<source>
Shape[] shape = slide.getShapes();
for (int i = 0; i &lt; shape.length; i++) {
//remove the shape
boolean ok = slide.removeShape(shape[i]);
if(ok){
//the shape was removed. Do something.
}
}
</source>
</section>
<anchor id="OLE"/>
<section><title>How to retrieve embedded OLE objects</title>
<source>
Shape[] shape = slide.getShapes();
for (int i = 0; i &lt; shape.length; i++) {
if (shape[i] instanceof OLEShape) {
OLEShape ole = (OLEShape) shape[i];
ObjectData data = ole.getObjectData();
String name = ole.getInstanceName();
if ("Worksheet".equals(name)) {
HSSFWorkbook wb = new HSSFWorkbook(data.getData());
} else if ("Document".equals(name)) {
HWPFDocument doc = new HWPFDocument(data.getData());
}
}
}
</source>
</section>
<anchor id="Sound"/>
<section><title>How to retrieve embedded sounds</title>
<source>
FileInputStream is = new FileInputStream(args[0]);
SlideShow ppt = new SlideShow(is);
is.close();
SoundData[] sound = ppt.getSoundData();
for (int i = 0; i &lt; sound.length; i++) {
//save *WAV sounds on disk
if(sound[i].getSoundType().equals(".WAV")){
FileOutputStream out = new FileOutputStream(sound[i].getSoundName());
out.write(sound[i].getData());
out.close();
}
}
</source>
</section>
<anchor id="Freeform"/>
<section><title>How to create shapes of arbitrary geometry</title>
<source>
SlideShow ppt = new SlideShow();
Slide slide = ppt.createSlide();
java.awt.geom.GeneralPath path = new java.awt.geom.GeneralPath();
path.moveTo(100, 100);
path.lineTo(200, 100);
path.curveTo(50, 45, 134, 22, 78, 133);
path.curveTo(10, 45, 134, 56, 78, 100);
path.lineTo(100, 200);
path.closePath();
Freeform shape = new Freeform();
shape.setPath(path);
slide.addShape(shape);
</source>
</section>
<anchor id="Graphics2D"/>
<section><title>How to draw into a slide using Graphics2D</title>
<warning>
Current implementation of the PowerPoint Graphics2D driver is not fully compliant with the java.awt.Graphics2D specification.
Some features like clipping, drawing of images are not yet supported.
</warning>
<source>
SlideShow ppt = new SlideShow();
Slide slide = ppt.createSlide();
//draw a simple bar graph
//bar chart data. The first value is the bar color, the second is the width
Object[] def = new Object[]{
Color.yellow, new Integer(100),
Color.green, new Integer(150),
Color.gray, new Integer(75),
Color.red, new Integer(200),
};
//all objects are drawn into a shape group so we need to create one
ShapeGroup group = new ShapeGroup();
//define position of the drawing in the slide
Rectangle bounds = new java.awt.Rectangle(200, 100, 350, 300);
//if you want to draw in the entire slide area then define the anchor as follows:
//Dimension pgsize = ppt.getPageSize();
//java.awt.Rectangle bounds = new java.awt.Rectangle(0, 0, pgsize.width, pgsize.height);
group.setAnchor(bounds);
slide.addShape(group);
//draw a simple bar chart
Graphics2D graphics = new PPGraphics2D(group);
int x = bounds.x + 50, y = bounds.y + 50;
graphics.setFont(new Font("Arial", Font.BOLD, 10));
for (int i = 0, idx = 1; i &lt; def.length; i+=2, idx++) {
graphics.setColor(Color.black);
int width = ((Integer)def[i+1]).intValue();
graphics.drawString("Q" + idx, x-20, y+20);
graphics.drawString(width + "%", x + width + 10, y + 20);
graphics.setColor((Color)def[i]);
graphics.fill(new Rectangle(x, y, width, 30));
y += 40;
}
graphics.setColor(Color.black);
graphics.setFont(new Font("Arial", Font.BOLD, 14));
graphics.draw(bounds);
graphics.drawString("Performance", x + 70, y + 40);
FileOutputStream out = new FileOutputStream("hslf-graphics2d.ppt");
ppt.write(out);
out.close();
</source>
</section>
<anchor id="Render"/>
<section><title>Export PowerPoint slides into java.awt.Graphics2D</title>
<p>
HSLF provides a way to export slides into images. You can capture slides into java.awt.Graphics2D object (or any other)
and serialize it into a PNG or JPEG format. Please note, although HSLF attempts to render slides as close to PowerPoint as possible,
the output may look differently from PowerPoint due to the following reasons:
</p>
<ul>
<li>Java2D renders fonts differently vs PowerPoint. There are always some differences in the way the font glyphs are painted</li>
<li>HSLF uses java.awt.font.LineBreakMeasurer to break text into lines. PowerPoint may do it in a different way.</li>
<li>If a font from the presentation is not avaiable, then the JDK default font will be used.</li>
</ul>
<p>
Current Limitations:
</p>
<ul>
<li>Some types of shapes are not yet supported (WordArt, complex auto-shapes)</li>
<li>Only Bitmap images (PNG, JPEG, DIB) can be rendered in Java</li>
</ul>
<source>
FileInputStream is = new FileInputStream("slideshow.ppt");
SlideShow ppt = new SlideShow(is);
is.close();
Dimension pgsize = ppt.getPageSize();
Slide[] slide = ppt.getSlides();
for (int i = 0; i &lt; slide.length; i++) {
BufferedImage img = new BufferedImage(pgsize.width, pgsize.height, BufferedImage.TYPE_INT_RGB);
Graphics2D graphics = img.createGraphics();
//clear the drawing area
graphics.setPaint(Color.white);
graphics.fill(new Rectangle2D.Float(0, 0, pgsize.width, pgsize.height));
//render
slide[i].draw(graphics);
//save the output
FileOutputStream out = new FileOutputStream("slide-" + (i+1) + ".png");
javax.imageio.ImageIO.write(img, "png", out);
out.close();
}
</source>
</section>
</section>
<anchor id="HeadersFooters"/>
<section><title>How to extract Headers / Footers from an existing presentation</title>
<source>
FileInputStream is = new FileInputStream("slideshow.ppt");
SlideShow ppt = new SlideShow(is);
is.close();
Slide[] slides = ppt.getSlides();
//presentation-scope headers / footers
HeadersFooters hdd = ppt.getSlideHeadersFooters();
if(hdd.isFooterVisible()) {
String footerText = hdd.getFooterText();
}
//per-slide headers / footers
for (int i=0; i &lt; slides.length; i++){
HeadersFooters hdd2 = slides[i].getHeadersFooters();
if(hdd2.isFooterVisible()) {
String footerText = hdd2.getFooterText();
}
if(hdd2.isUserDateVisible()) {
String customDate = hdd2.getDateTimeText();
}
if(hdd2.isSlideNumberVisible()){
int slideNUm = slides[i].getSlideNumber();
}
}
</source>
</section>
<section><title>How to set Headers / Footers</title>
<source>
SlideShow ppt = new SlideShow();
//presentation-scope headers / footers
HeadersFooters hdd = ppt.getSlideHeadersFooters();
hdd.setSlideNumberVisible(true);
hdd.setFootersText("Created by POI-HSLF");
</source>
</section>
</section>
</body>
</document>

70
src/documentation/content/xdocs/slideshow/index.xml Normal file
View File

@ -0,0 +1,70 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
====================================================================
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
====================================================================
-->
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "../dtd/document-v11.dtd">
<document>
<header>
<title>POI-HSLF and and POI-XLSF - Java API To Access Microsoft Powerpoint Format Files</title>
<subtitle>Overview</subtitle>
<authors>
<person name="Avik Sengupta" email="avik at apache dot org"/>
<person name="Nick Burch" email="nick at apache dot org"/>
<person name="Yegor Kozlov" email="yegor at apache dot org"/>
</authors>
</header>
<body>
<section>
<title>POI-HSLF</title>
<p>HSLF is the POI Project's pure Java implementation of the Powerpoint '97(-2007) file format. </p>
<p>HSLF provides a way to read, create or modify PowerPoint presentations. In particular, it provides:
</p>
<ul>
<li>api for data extraction (text, pictures, embedded objects, sounds)</li>
<li>usermodel api for creating, reading and modifying ppt files</li>
</ul>
<note>
This code currently lives the
<link href="http://svn.apache.org/viewcvs.cgi/poi/trunk/src/scratchpad/">scratchpad area</link>
of the POI SVN repository.
Ensure that you have the scratchpad jar or the scratchpad
build area in your classpath before experimenting with
this code - the main POI jar is not enough.
</note>
<p>The <link href="./quick-guide.html">quick guide</link> documentation provides
information on using this API. Comments and fixes gratefully accepted on the POI
dev mailing lists.</p>
</section>
<section>
<title>POI-XSLF</title>
<p>
XSLF is the POI Project's pure Java implementation of the PowerPoint 2007 OOXML (.xlsx) file format.
Whilst HSLF and XSLF provide similar features, there is not a common interface across the two of them at this time.
</p>
<p>
Please note that XSLF is still in early development and is a subject to incompatible changes in future.
</p>
<p>
A quick guide is available in the <link href="./xslf-cookbook.html">XSLF Cookbook</link>
</p>
</section>
</body>
</document>

367
src/documentation/content/xdocs/slideshow/ppt-file-format.xml Normal file
View File

@ -0,0 +1,367 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
====================================================================
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
====================================================================
-->
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "../dtd/document-v11.dtd">
<document>
<header>
<title>POI-HSLF - A Guide to the PowerPoint File Format</title>
<subtitle>Overview</subtitle>
<authors>
<person name="Nick Burch" email="nick at torchbox dot com"/>
<person name="Yegor Kozlov" email="yegor at dinom dot ru"/>
</authors>
</header>
<body>
<section><title>Records, Containers and Atoms</title>
<p>
PowerPoint documents are made up of a tree of records. A record may
contain either other records (in which case it is a Container),
or data (in which case it's an Atom). A record can't hold both.
</p>
<p>
PowerPoint documents don't have one overall container record. Instead,
there are a number of different container records to be found at
the top level.
</p>
<p>
Any numbers or strings stored in the records are always stored in
Little Endian format (least important bytes first). This is the case
no matter what platform the file was written on - be that a
Little Endian or a Big Endian system.
</p>
<p>
PowerPoint may have Escher (DDF) records embeded in it. These
are always held as the children of a PPDrawing record (record
type 1036). Escher records have the same format as PowerPoint
records.
</p>
</section>
<section><title>Record Headers</title>
<p>
All records, be they containers or atoms, have the same standard
8 byte header. It is:
</p>
<ul><li>1/2 byte container flag</li>
<li>1.5 byte option field</li>
<li>2 byte record type</li>
<li>4 byte record length</li></ul>
<p>
If the first byte of the header, BINARY_AND with 0x0f, is 0x0f,
then the record is a container. Otherwise, it's an atom. The rest
of the first two bytes are used to store the "options" for the
record. Most commonly, this is used to indicate the version of
the record, but the exact useage is record specific.
</p>
<p>
The record type is a little endian number, which tells you what
kind of record you're dealing with. Each different kind of record
has it's own value that gets stored here. PowerPoint records have
a type that's normally less than 6000 (decimal). Escher records
normally have a type between 0xF000 and 0xF1FF.
</p>
<p>
The record length is another little endian number. For an atom,
it's the size of the data part of the record, i.e. the length
of the record <em>less</em> its 8 byte record header. For a
container, it's the size of all the records that are children of
this record. That means that the size of a container record is the
length, plus 8 bytes for its record header.
</p>
</section>
<section><title>CurrentUserAtom, UserEditAtom and PersistPtrIncrementalBlock</title>
<p><strong>aka Records that care about the byte level position of other records</strong></p>
<p>
A small number of records contain byte level position offsets to other
records. If you change the position of any records in the file, then
there's a good chance that you will need to update some of these
special records.
</p>
<p>
First up, CurrentUserAtom. This is actually stored in a different
OLE2 (POIFS) stream to the main PowerPoint document. It contains
a few bits of information on who lasted edited the file. Most
importantly, at byte 8 of its contents, it stores (as a 32 bit
little endian number) the offset in the main stream to the most
recent UserEditAtom.
</p>
<p>
The UserEditAtom contains two byte level offsets (again as 32 bit
little endian numbers). At byte 12 is the offset to the
PersistPtrIncrementalBlock associated with this UserEditAtom
(each UserEditAtom has one and only one PersistPtrIncrementalBlock).
At byte 8, there's the offset to the previous UserEditAtom. If this
is 0, then you're at the first one.
</p>
<p>
Every time you do a non full save in PowerPoint, it tacks on another
UserEditAtom and another PersistPtrIncrementalBlock. The
CurrentUserAtom is updated to point to this new UserEditAtom, and the
new UserEditAtom points back to the previous UserEditAtom. You then
end up with a chain, starting from the CurrentUserAtom, linking
back through all the UserEditAtoms, until you reach the first one
from a full save.
</p>
<source>
/-------------------------------\
| CurrentUserAtom (own stream) |
| OffsetToCurrentEdit = 10562 |==\
\-------------------------------/ |
|
/==================================/
| /-----------------------------------\
| | PersistPtrIncrementalBlock @ 6144 |
| \-----------------------------------/
| /---------------------------------\ |
| | UserEditAtom @ 6176 | |
| | LastUserEditAtomOffset = 0 | |
| | PersistPointersOffset = 6144 |==================/
| \---------------------------------/
| | /-----------------------------------\
| \====================\ | PersistPtrIncrementalBlock @ 8646 |
| | \-----------------------------------/
| /---------------------------------\ | |
| | UserEditAtom @ 8674 | | |
| | LastUserEditAtomOffset = 6176 |=/ |
| | PersistPointersOffset = 8646 |==================/
| \---------------------------------/
| | /------------------------------------\
| \====================\ | PersistPtrIncrementalBlock @ 10538 |
| | \------------------------------------/
| /---------------------------------\ | |
\==| UserEditAtom @ 10562 | | |
| LastUserEditAtomOffset = 8674 |=/ |
| PersistPointersOffset = 10538 |==================/
\---------------------------------/
</source>
<p>
The PersistPtrIncrementalBlock contains byte offsets to all the
Slides, Notes, Documents and MasterSlides in the file. The first
PersistPtrIncrementalBlock will point to all the ones that
were present the first time the file was saved. Subsequent
PersistPtrIncrementalBlocks will contain pointers to all the ones
that were changed in that edit. To find the offset to a given
sheet in the latest version, then start with the most recent
PersistPtrIncrementalBlock. If this knows about the sheet, use the
offset it has. If it doesn't, then work back through older
PersistPtrIncrementalBlocks until you find one which does, and
use that.
</p>
<p>
Each PersistPtrIncrementalBlock can contain a number of entries
blocks. Each block holds information on a sequence of sheets.
Each block starts with a 32 bit little endian integer. Once read
into memory, the lower 20 bits contain the starting number for the
sequence of sheets to be described. The higher 12 bits contain
the count of the number of sheets described. Following that is
one 32 bit little endian integer for each sheet in the sequence,
the value being the offset to that sheet. If there is any data
left after parsing a block, then it corresponds to the next block.
</p>
<source>
hex on disk decimal description
----------- ------- -----------
0000 0 No options
7217 6002 Record type is 6002
2000 0000 32 Length of data is 32 bytes
0100 5000 5242881 Count is 5 (12 highest bits)
Starting number is 1 (20 lowest bits)
0000 0000 0 Sheet (1+0)=1 starts at offset 0
900D 0000 3472 Sheet (1+1)=2 starts at offset 3472
E403 0000 996 Sheet (1+2)=3 starts at offset 996
9213 0000 5010 Sheet (1+3)=4 starts at offset 5010
BE15 0000 5566 Sheet (1+4)=5 starts at offset 5566
0900 1000 1048585 Count is 1 (12 highest bits)
Starting number is 9 (20 lowest bits)
4418 0000 6212 Sheet (9+0)=9 starts at offset 9212
</source>
</section>
<section><title>Paragraph and Text Styling</title>
<p>
There are quite a number of records that affect the styling
of text, and a smaller number that are responsible for the
styling of paragraphs.
</p>
<p>
By default, a given set of text will inherit paragraph and text
stylings from the appropriate master sheet. If anything differs
from the master sheet, then appropriate styling records will
follow the text record.
</p>
<p>
<em>(We don't currently know enough about master sheet styling
to write about it)</em>
</p>
<p>
Normally, powerpoint will have one text record (TextBytesAtom
or TextCharsAtom) for every paragraph, with a preceeding
TextHeaderAtom to describe what sort of paragraph it is.
If any of the stylings differ from the master's, then a
StyleTextPropAtom will follow the text record. This contains
the paragraph style information, and the styling information
for each section of the text which has a different style.
(More on StyleTextPropAtom later)
</p>
<p>
For every font used, a FontEntityAtom must exist for that font.
The FontEntityAtoms live inside a FontCollection record, and
there's one of those inside Environment record inside the
Document record. <em>(More on Fonts to be discovered)</em>
</p>
</section>
<section><title>StyleTextPropAtom</title>
<p>
If the text or paragraph stylings for a given text record
differ from those of the appropriate master, then there will
be one of these records.
</p>
<p>
This record is made up of two lists of lists. Firstly,
there's a list of paragraph stylings - each made up of the
number of characters it applies two, followed by the matching
styling elements. Following that is the equivalent for
character stylings.
</p>
<p>
Each styling list (in either list) starts with the number
of characters it applies to, stored in a 2 byte little
endian number. If it is a paragraph styling, it will be
followed by a 2 byte number (of unknown use). After this is
a four byte number, which is a mask indicating which stylings
will follow. You then have an entry for each of the stylings
indicated in the mask. Finally, you move onto the next set
of stylings.
</p>
<p>
Each styling has a specific mask flag to indicate its
presence. (The list may be found towards the top of
org.apache.poi.hslf.record.StyleTextPropAtom.java, and is
too long to sensibly include here). For each styling entry
will occur in the order of its mask value (so one with mask
1 will come first, followed by the next higest mask value).
Depending on the styling, it is either made up of a 2 byte
or 4 byte numeric value. The meaning of the value will
depend on the styling (eg for font.size, it is the font
size in points).
</p>
<p>
Some stylings are actually mask stylings. For these, the
value will be a 4 byte number. This is then processed as
mask, to indicate a number of different sub-stylings.
The styling for bold/italic/underline is one such example.
</p>
<source>
hex on disk decimal description
----------- ------- -----------
0000 0 No options
A10F 4001 Record type is 4001
8000 0000 128 Length of data is 128 bytes
1E00 0000 30 The paragraph styling applies to 30 characters
0000 0 Paragraph options are 0
0018 0000 6144 0x0800=Text Alignment, 0x1000=Line Spacing
0000 0 Text Alignment = Left
5000 80 Line Spacing = 80
1C00 0000 28 The paragraph styling applies to 28 characters
0000 0 Paragraph options are 0
0010 0000 4096 0x1000=Line Spacing
5000 80 Line Spacing = 80
1900 0000 25 The paragraph styling applies to 25 characters
0000 0 Paragraph options are 0
0018 0000 6144 0x0800=Text Alignment, 0x1000=Line Spacing
0200 0 Text Alignment = Right
5000 80 Line Spacing = 80
6100 0000 61 The paragraph styling applies to 61 characters
(includes final CR)
0000 0 Paragraph options are 0
0018 0000 6144 0x0800=Text Alignment, 0x1000=Line Spacing
0000 0 Text Alignment = Left
5000 80 Line Spacing = 80
1E00 0000 30 The character styling applies to 30 characters
0100 0200 131073 0x0001=Char Props Mask, 0x20000=Font Size
0100 1 Char Props 0x0001=Bold
1400 20 Font Size = 20
1C00 0000 28 The character styling applies to 28 characters
0200 0600 393218 0x0002=Char Props Mask, 0x20000=Font Size, 0x40000=Font Color
0200 2 Char Props 0x0002=Italic
1400 20 Font Size = 20
0000 0005 83886080 Blue
1900 0000 25 The character styling applies to 25 characters
0000 0600 393216 0x20000=Font Size, 0x40000=Font Color
1400 20 Font Size = 20
FF33 00FE 4261426175 Red
6000 0000 96 The character styling applies to 96 characters
0400 0300 196612 0x0004=Char Props Mask, 0x10000=Font Index, 0x20000=Font Size
0400 4 Char Props 0x0004=Underlined
0100 1 Font Index = 1 (2nd Font in table)
1800 24 Font Size = 24
</source>
</section>
<section><title>Fonts in PowerPoint</title>
<p>
PowerPoint stores information about the fonts used in FontEntityAtoms,
which live inside Document.Environment.FontCollection. For every different
font used, a FontEntityAtom must exist for that font. There is always at
least one FontEntityAtom in Document.Environment.FontCollection,
which describes the default font.
</p>
</section>
<section><title>FontEntityAtom</title>
<p>
The instance field of the record header contains the zero based index of the
font. Font index entries in StyleTextPropAtoms will refer to their required
font via this index.
</p>
<p>
The length of FontEntityAtoms is always 68 bytes. The first 64 bytes of
it hold the typeface name of the font to be used. This is stored as
a null-terminated string, and encoded as little endian unicode. (The
length of the string must not exceed 32 characters including the null
termination, so the typeface name cannot exceed 31 characters).
</p>
<p>
After the typeface name there are 4 bytes of bitmask flags. The details of these
can be found in the Windows API, under the LOGFONT structure.
The 65th byte is the output precision, which defines how closely the system chosen
font must match the requested font, in terms of heigh, width, pitch etc.
The 66th byte is the clipping precision, which defines how to clip characters
that occur partly outside the clipping region.
The 67th byte is the output quality, which defines how closely the system
must match the logical font's attributes to those of the physical font used.
The 68th (and final) byte is the pitch and family, which is used by the
system when matching fonts.
</p>
</section>
</body>
</document>

136
src/documentation/content/xdocs/slideshow/quick-guide.xml Normal file
View File

@ -0,0 +1,136 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
====================================================================
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
====================================================================
-->
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "../dtd/document-v11.dtd">
<document>
<header>
<title>POI-HSLF - A Quick Guide</title>
<subtitle>Overview</subtitle>
<authors>
<person name="Nick Burch" email="nick at torchbox dot com"/>
</authors>
</header>
<body>
<section><title>Basic Text Extraction</title>
<p>For basic text extraction, make use of
<code>org.apache.poi.hslf.extractor.PowerPointExtractor</code>. It accepts a file or an input
stream. The <code>getText()</code> method can be used to get the text from the slides, and the <code>getNotes()</code> method can be used to get the text
from the notes. Finally, <code>getText(true,true)</code> will get the text
from both.
</p>
</section>
<section><title>Specific Text Extraction</title>
<p>To get specific bits of text, first create a <code>org.apache.poi.hslf.usermodel.SlideShow</code>
(from a <code>org.apache.poi.hslf.HSLFSlideShow</code>, which accepts a file or an input
stream). Use <code>getSlides()</code> and <code>getNotes()</code> to get the slides and notes.
These can be queried to get their page ID (though they should be returned
in the right order).</p>
<p>You can then call <code>getTextRuns()</code> on these, to get
their blocks of text. (One TextRun normally holds all the text in a
given area of the page, eg in the title bar, or in a box).
From the <code>TextRun</code>, you can extract the text, and check
what type of text it is (eg Body, Title). You can allso call
<code>getRichTextRuns()</code>, which will return the
<code>RichTextRun</code>s that make up the <code>TextRun</code>. A
<code>RichTextRun</code> is made up of a sequence of text, all having the
same character and paragraph formatting.
</p>
</section>
<section><title>Poor Quality Text Extraction</title>
<p>If speed is the most important thing for you, you don't care
about getting duplicate blocks of text, you don't care about
getting text from master sheets, and you don't care about getting
old text, then
<code>org.apache.poi.hslf.extractor.QuickButCruddyTextExtractor</code>
might be of use.</p>
<p>QuickButCruddyTextExtractor doesn't use the normal record
parsing code, instead it uses a tree structure blind search
method to get all text holding records. You will get all the text,
including lots of text you normally wouldn't ever want. However,
you will get it back very very fast!</p>
<p>There are two ways of getting the text back.
<code>getTextAsString()</code> will return a single string with all
the text in it. <code>getTextAsVector()</code> will return a
vector of strings, one for each text record found in the file.
</p>
</section>
<section><title>Changing Text</title>
<p>It is possible to change the text via
<code>TextRun.setText(String)</code> or
<code>RichTextRun.setText(String)</code>. It is not yet possible
to add additional TextRuns or RichTextRuns.</p>
<p>When calling <code>TextRun.setText(String)</code>, all
the text will end up with the same formatting. When calling
<code>RichTextRun.setText(String)</code>, the text will retain
the old formatting of that <code>RichTextRun</code>.
</p>
</section>
<section><title>Adding Slides</title>
<p>You may add new slides by calling
<code>SlideShow.createSlide()</code>, which will add a new slide
to the end of the SlideShow. It is not currently possible to
re-order slides, nor to add new text to slides (currently only
adding Escher objects to new slides is supported).
</p>
</section>
<section><title>Guide to key classes</title>
<ul>
<li><code>org.apache.poi.hslf.HSLFSlideShow</code>
Handles reading in and writing out files. Calls
<code>org.apache.poi.hslf.record.record</code> to build a tree
of all the records in the file, which it allows access to.
</li>
<li><code>org.apache.poi.hslf.record.record</code>
Base class of all records. Also provides the main record generation
code, which will build up a tree of records for a file.
</li>
<li><code>org.apache.poi.hslf.usermodel.SlideShow</code>
Builds up model entries from the records, and presents a user facing
view of the file
</li>
<li><code>org.apache.poi.hslf.model.Slide</code>
A user facing view of a Slide in a slidesow. Allows you to get at the
Text of the slide, and at any drawing objects on it.
</li>
<li><code>org.apache.poi.hslf.model.TextRun</code>
Holds all the Text in a given area of the Slide, and will
contain one or more <code>RichTextRun</code>s.
</li>
<li><code>org.apache.poi.hslf.usermodel.RichTextRun</code>
Holds a run of text, all having the same character and
paragraph stylings. It is possible to modify text, and/or text stylings.
</li>
<li><code>org.apache.poi.hslf.extractor.PowerPointExtractor</code>
Uses the model code to allow extraction of text from files
</li>
<li><code>org.apache.poi.hslf.extractor.QuickButCruddyTextExtractor</code>
Uses the record code to extract all the text from files very fast,
but including deleted text (and other bits of Crud).
</li>
</ul>
</section>
</body>
</document>

305
src/documentation/content/xdocs/slideshow/xslf-cookbook.xml Normal file
View File

@ -0,0 +1,305 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
====================================================================
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
====================================================================
-->
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "../dtd/document-v11.dtd">
<document>
<header>
<title>XSLF Cookbook</title>
<authors>
<person email="yegor@apache.org" name="Yegor Kozlov" id="YK"/>
</authors>
</header>
<body>
<section><title>XSLF Cookbook</title>
<p>
This page offers a short introduction into the XSLF API. More examples can be found in the
<link href="http://svn.apache.org/repos/asf/poi/trunk/src/examples/src/org/apache/poi/xslf/usermodel/"> XSLF Examples</link>
in the POI SVN repository.
</p>
<note>
Please note that XSLF is still in early development and is a subject to incompatible changes in a future release.
</note>
<section><title>Index of Features</title>
<ul>
<li><link href="#NewPresentation">Create a new presentation</link></li>
<li><link href="#ReadPresentation">Read an existing presentation</link></li>
<li><link href="#SlideLayout">Create a slide with a predefined layout</link></li>
<li><link href="#DeleteSlide">Delete slide</link></li>
<li><link href="#MoveSlide">Re-order slides</link></li>
<li><link href="#SlideSize">Change slide size</link></li>
<li><link href="#GetShapes">Read shapes</link></li>
<li><link href="#AddImage">Add image</link></li>
<li><link href="#ReadImages">Read images contained in a presentation</link></li>
<li><link href="#Text">Format text</link></li>
<li><link href="#Hyperlinks">Hyperlinks</link></li>
<li><link href="#PPTX2PNG">Convert .pptx slides into images</link></li>
<li><link href="#Merge">Merge multiple presentations together</link></li>
</ul>
</section>
<section><title>Cookbok</title>
<anchor id="NewPresentation"/>
<section><title>New Presentation</title>
<p>
The following code creates a new .pptx slide show and adds a blank slide to it:
</p>
<source>
//create a new empty slide show
XMLSlideShow ppt = new XMLSlideShow();
//add first slide
XSLFSlide blankSlide = ppt.createSlide();
</source>
</section>
<anchor id="ReadPresentation"/>
<section><title>Read an existing presentation and append a slide to it</title>
<source>
XMLSlideShow ppt = new XMLSlideShow(new FileInputStream("slideshow.pptx"));
//append a new slide to the end
XSLFSlide blankSlide = ppt.createSlide();
</source>
</section>
<anchor id="SlideLayout"/>
<section><title>Create a new slide from a predefined slide layout</title>
<source>
XMLSlideShow ppt = new XMLSlideShow(new FileInputStream("slideshow.pptx"));
// first see what slide layouts are available :
System.out.println("Available slide layouts:");
for(XSLFSlideMaster master : ppt.getSlideMasters()){
for(XSLFSlideLayout layout : master.getSlideLayouts()){
System.out.println(layout.getType());
}
}
// blank slide
XSLFSlide blankSlide = ppt.createSlide();
// there can be multiple masters each referencing a number of layouts
// for demonstration purposes we use the first (default) slide master
XSLFSlideMaster defaultMaster = ppt.getSlideMasters()[0];
// title slide
XSLFSlideLayout titleLayout = defaultMaster.getLayout(SlideLayout.TITLE);
// fill the placeholders
XSLFSlide slide1 = ppt.createSlide(titleLayout);
XSLFTextShape title1 = slide1.getPlaceholder(0);
title1.setText("First Title");
// title and content
XSLFSlideLayout titleBodyLayout = defaultMaster.getLayout(SlideLayout.TITLE_AND_CONTENT);
XSLFSlide slide2 = ppt.createSlide(titleBodyLayout);
XSLFTextShape title2 = slide2.getPlaceholder(0);
title2.setText("Second Title");
XSLFTextShape body2 = slide2.getPlaceholder(1);
body2.clearText(); // unset any existing text
body2.addNewTextParagraph().addNewTextRun().setText("First paragraph");
body2.addNewTextParagraph().addNewTextRun().setText("Second paragraph");
body2.addNewTextParagraph().addNewTextRun().setText("Third paragraph");
</source>
</section>
<anchor id="DeleteSlide"/>
<section><title>Delete slide</title>
<source>
XMLSlideShow ppt = new XMLSlideShow(new FileInputStream("slideshow.pptx"));
ppt.removeSlide(0); // 0-based index of a slide to be removed
</source>
</section>
<anchor id="MoveSlide"/>
<section><title>Re-order slides</title>
<source>
XMLSlideShow ppt = new XMLSlideShow(new FileInputStream("slideshow.pptx"));
XSLFSlide[] slides = ppt.getSlides();
XSLFSlide thirdSlide = slides[2];
ppt.setSlideOrder(thirdSlide, 0); // move the third slide to the beginning
</source>
</section>
<anchor id="SlideSize"/>
<section><title>How to retrieve or change slide size</title>
<source>
XMLSlideShow ppt = new XMLSlideShow();
//retrieve page size. Coordinates are expressed in points (72 dpi)
java.awt.Dimension pgsize = ppt.getPageSize();
int pgx = pgsize.width; //slide width in points
int pgy = pgsize.height; //slide height in points
//set new page size
ppt.setPageSize(new java.awt.Dimension(1024, 768));
</source>
</section>
<anchor id="GetShapes"/>
<section><title>How to read shapes contained in a particular slide</title>
<p>
The following code demonstrates how to iterate over shapes for each slide.
</p>
<source>
XMLSlideShow ppt = new XMLSlideShow(new FileInputStream("slideshow.pptx"));
//get slides
XSLFSlide[] slide = ppt.getSlides();
for (int i = 0; i &lt; slide.length; i++){
XSLFShape[] sh = slide[i].getShapes();
for (int j = 0; j &lt; sh.length; j++){
//name of the shape
String name = sh[j].getShapeName();
//shapes's anchor which defines the position of this shape in the slide
java.awt.geom.Rectangle2D anchor = sh[j].getAnchor();
if (sh[j] instanceof XSLFConnectorShape){
XSLFConnectorShape line = (XSLFConnectorShape)sh[j];
//work with Line
} else if (sh[j] instanceof XSLFTextShape){
XSLFTextShape shape = (XSLFTextShape)sh[j];
//work with a shape that can hold text
} else if (sh[j] instanceof XSLFPictureShape){
XSLFPictureShape shape = (XSLFPictureShape)sh[j];
//work with Picture
}
}
}
</source>
</section>
<anchor id="AddImage"/>
<section><title>Add Image to Slide</title>
<source>
XMLSlideShow ppt = new XMLSlideShow();
XSLFSlide slide = ppt.createSlide();
byte[] pictureData = IOUtils.toByteArray(new FileInputStream("image.png"));
int idx = ppt.addPicture(pictureData, XSLFPictureData.PICTURE_TYPE_PNG);
XSLFPictureShape pic = slide.createPicture(idx);
</source>
</section>
<anchor id="ReadImages"/>
<section><title>Read Images contained within a presentation</title>
<source>
XMLSlideShow ppt = new XMLSlideShow(new FileInputStream("slideshow.pptx"));
for(XSLFPictureData data : ppt.getAllPictures()){
byte[] bytes = data.getData();
String fileName = data.getFileName();
}
</source>
</section>
<anchor id="Text"/>
<section><title>Basic text formatting</title>
<source>
XMLSlideShow ppt = new XMLSlideShow();
XSLFSlide slide = ppt.createSlide();
XSLFTextBox shape = slide.createTextBox();
XSLFTextParagraph p = shape.addNewTextParagraph();
XSLFTextRun r1 = p.addNewTextRun();
r1.setText("The");
r1.setFontColor(Color.blue);
r1.setFontSize(24);
XSLFTextRun r2 = p.addNewTextRun();
r2.setText(" quick");
r2.setFontColor(Color.red);
r2.setBold(true);
XSLFTextRun r3 = p.addNewTextRun();
r3.setText(" brown");
r3.setFontSize(12);
r3.setItalic(true);
r3.setStrikethrough(true);
XSLFTextRun r4 = p.addNewTextRun();
r4.setText(" fox");
r4.setUnderline(true);
</source>
</section>
<anchor id="Hyperlinks"/>
<section><title>How to read hyperlinks from a slide show</title>
<source>
XMLSlideShow ppt = new XMLSlideShow();
XSLFSlide slide = ppt.createSlide();
// assign a hyperlink to a text run
XSLFTextBox shape = slide.createTextBox();
XSLFTextRun r = shape.addNewTextParagraph().addNewTextRun();
r.setText("Apache POI");
XSLFHyperlink link = r.createHyperlink();
link.setAddress("http://poi.apache.org");
</source>
</section>
<anchor id="PPTX2PNG"/>
<section><title>PPTX2PNG is an application that converts each slide of a .pptx slideshow into a PNG image</title>
<source>
Usage: PPTX2PNG [options] &lt;pptx file&gt;
Options:
-scale &lt;float&gt; scale factor (default is 1.0)
-slide &lt;integer&gt; 1-based index of a slide to render. Default is to render all slides.
</source>
<p>How it works:</p>
<p>
The XSLFSlide object implements a draw(Graphics2D graphics) method that recursively paints all shapes
in the slide into the supplied graphics canvas:
</p>
<source>
slide.draw(graphics);
</source>
<p>
where graphics is a class implementing java.awt.Graphics2D. In PPTX2PNG the graphic canvas is derived from
java.awt.image.BufferedImage, i.e. the destination is an image in memory, but in general case you can pass
any compliant implementation of java.awt.Graphics2D. The
<link href="http://svn.apache.org/repos/asf/poi/trunk/src/examples/src/org/apache/poi/xslf/usermodel/PPTX2SVG.txt">PPTX2SVG</link>
example demonstrates how to use Apache Batik to convert .pptx slides into SVG format.
</p>
</section>
<anchor id="Merge"/>
<section>
<title>Merge multiple presentations together</title>
<source>
XMLSlideShow ppt = new XMLSlideShow();
String[] inputs = {"presentations1.pptx", "presentation2.pptx"};
for(String arg : inputs){
FileInputStream is = new FileInputStream(arg);
XMLSlideShow src = new XMLSlideShow(is);
is.close();
for(XSLFSlide srcSlide : src.getSlides()){
ppt.createSlide().importContent(srcSlide);
}
}
FileOutputStream out = new FileOutputStream("merged.pptx");
ppt.write(out);
out.close();
</source>
</section>
</section>
</section>
</body>
</document>

53
src/documentation/content/xdocs/spreadsheet/book.xml Normal file
View File

@ -0,0 +1,53 @@
<?xml version="1.0"?>
<!--
====================================================================
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
====================================================================
-->
<!DOCTYPE book PUBLIC "-//APACHE//DTD Cocoon Documentation Book V1.0//EN" "../dtd/book-cocoon-v10.dtd">
<book software="POI Project"
title="HSSF+XSSF"
copyright="@year@ POI Project">
<menu label="Apache POI">
<menu-item label="Top" href="../index.html"/>
</menu>
<menu label="HSSF+XSSF">
<menu-item label="Overview" href="index.html"/>
<menu-item label="Quick Guide" href="quick-guide.html"/>
<menu-item label="HOWTO" href="how-to.html"/>
<menu-item label="HSSF to SS Converting" href="converting.html"/>
<menu-item label="Formula Support" href="formula.html" />
<menu-item label="Formula Evaluation" href="eval.html" />
<menu-item label="Eval Dev Guide" href="eval-devguide.html" />
<menu-item label="Examples" href="examples.html"/>
<menu-item label="Use Case" href="use-case.html"/>
<menu-item label="Pictorial Docs" href="diagrams.html"/>
<menu-item label="Limitations" href="limitations.html"/>
<menu-item label="User Defined Functions" href="user-defined-functions.html"/>
<menu-item label="ExcelAnt Tests" href="excelant.html"/>
</menu>
<menu label="Contributer's Guide">
<menu-item label="Hacking HSSF" href="hacking-hssf.html"/>
<menu-item label="Record Generator" href="record-generator.html"/>
<menu-item label="Charts" href="chart.html"/>
</menu>
</book>

1532
src/documentation/content/xdocs/spreadsheet/chart.xml Normal file
View File

File diff suppressed because it is too large Load Diff

232
src/documentation/content/xdocs/spreadsheet/converting.xml Normal file
View File

@ -0,0 +1,232 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
====================================================================
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
====================================================================
-->
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "../dtd/document-v11.dtd">
<document>
<header>
<title>Upgrading to POI 3.5, including converting existing HSSF Usermodel code to SS Usermodel (for XSSF and HSSF)</title>
<authors>
<person email="nick@apache.org" name="Nick Burch" id="NB"/>
</authors>
</header>
<body>
<section><title>Things that have to be changed when upgrading to POI 3.5</title>
<p>Wherever possible, we have tried to ensure that you can use your
existing POI code with POI 3.5 without requiring any changes. However,
Java doesn't always make that easy, and unfortunately there are a
few changes that may be required for some users.</p>
<section><title>org.apache.poi.hssf.usermodel.HSSFFormulaEvaluator.CellValue</title>
<p>Annoyingly, java will not let you access a static inner class via
a child of the parent one. So, all references to
<em>org.apache.poi.hssf.usermodel.HSSFFormulaEvaluator.CellValue</em>
will need to be changed to
<em>org.apache.poi.ss.usermodel.FormulaEvaluator.CellValue</em>
</p>
</section>
<section><title>org.apache.poi.hssf.usermodel.HSSFRow.MissingCellPolicy</title>
<p>Annoyingly, java will not let you access a static inner class via
a child of the parent one. So, all references to
<em>org.apache.poi.hssf.usermodel.HSSFRow.MissingCellPolicy</em>
will need to be changed to
<em>org.apache.poi.ss.usermodel.Row.MissingCellPolicy</em>
</p>
</section>
<section><title>DDF and org.apache.poi.hssf.record.RecordFormatException</title>
<p>Previously, record level errors within DDF would throw an
exception from the hssf class heirachy. Now, record level errors
within DDF will throw a more general RecordFormatException,
<em>org.apache.poi.util.RecordFormatException</em></p>
<p>In addition, org.apache.poi.hssf.record.RecordFormatException
has been changed to inherit from the new
<em>org.apache.poi.util.RecordFormatException</em>, so you may
wish to change catches of the hssf version to the new util version.
</p>
</section>
</section>
<section><title>Converting existing HSSF Usermodel code to SS Usermodel (for XSSF and HSSF)</title>
<section><title>Why change?</title>
<p>If you have existing HSSF usermodel code that works just
fine, and you don't want to use the new OOXML XSSF support,
then you probably don't need to. Your existing HSSF only code
will continue to work just fine.</p>
<p>However, if you want to be able to work with both HSSF for
your .xls files, and also XSSF for .xslx files, then you will
need to make some slight tweaks to your code.</p>
</section>
<section><title>org.apache.poi.ss.usermodel</title>
<p>The new SS usermodel (org.apache.poi.ss.usermodel) is very
heavily based on the old HSSF usermodel
(org.apache.poi.hssf.usermodel). The main difference is that
the package name and class names have been tweaked to remove
HSSF from them. Otherwise, the new SS Usermodel interfaces
should provide the same functionality.</p>
</section>
<section><title>Constructors</title>
<p>Calling the empty HSSFWorkbook remains as the way to
create a new, empty Workbook object. To open an existing
Worbook, you should now call WorkbookFactory.create(inp).</p>
<p>For all other cases when you would have called a
Usermodel constructor, such as 'new HSSFRichTextString()' or
'new HSSFDataFormat', you should instead use a CreationHelper.
There's a method on the Workbook to get a CreationHelper, and
the CreationHelper will then handle constructing new objects
for you.</p>
</section>
<section><title>Other Code</title>
<p>For all other code, generally change a reference from
org.apache.poi.hssf.usermodel.HSSFFoo to a reference to
org.apache.poi.ss.usermodel.Foo. Method signatures should
otherwise remain the same, and it should all then work for
both XSSF and HSSF.</p>
</section>
</section>
<section><title>Worked Examples</title>
<section><title>Old HSSF Code</title>
<source><![CDATA[
// import org.apache.poi.hssf.usermodel.*;
HSSFWorkbook wb = new HSSFWorkbook();
// create a new sheet
HSSFSheet s = wb.createSheet();
// declare a row object reference
HSSFRow r = null;
// declare a cell object reference
HSSFCell c = null;
// create 2 cell styles
HSSFCellStyle cs = wb.createCellStyle();
HSSFCellStyle cs2 = wb.createCellStyle();
HSSFDataFormat df = wb.createDataFormat();
// create 2 fonts objects
HSSFFont f = wb.createFont();
HSSFFont f2 = wb.createFont();
// Set font 1 to 12 point type, blue and bold
f.setFontHeightInPoints((short) 12);
f.setColor( HSSFColor.RED.index );
f.setBoldweight(HSSFFont.BOLDWEIGHT_BOLD);
// Set font 2 to 10 point type, red and bold
f2.setFontHeightInPoints((short) 10);
f2.setColor( HSSFFont.RED.index );
f2.setBoldweight(HSSFFont.BOLDWEIGHT_BOLD);
// Set cell style and formatting
cs.setFont(f);
cs.setDataFormat(df.getFormat("#,##0.0"));
// Set the other cell style and formatting
cs2.setBorderBottom(cs2.BORDER_THIN);
cs2.setDataFormat(HSSFDataFormat.getBuiltinFormat("text"));
cs2.setFont(f2);
// Define a few rows
for(short rownum = (short)0; rownum < 30; rownum++) {
HSSFRow r = s.createRow(rownum);
for(short cellnum = (short)0; cellnum < 10; cellnum += 2) {
HSSFCell c = r.createCell(cellnum);
HSSFCell c2 = r.createCell(cellnum+1);
c.setCellValue((double)rownum + (cellnum/10));
c2.setCellValue(new HSSFRichTextString("Hello! " + cellnum);
}
}
// Save
FileOutputStream out = new FileOutputStream("workbook.xls");
wb.write(out);
out.close();
]]></source>
</section>
<section><title>New, generic SS Usermodel Code</title>
<source><![CDATA[
// import org.apache.poi.ss.usermodel.*;
Workbook[] wbs = new Workbook[] { new HSSFWorkbook(), new XSSFWorkbook() };
for(int i=0; i<wbs.length; i++) {
Workbook wb = wbs[i];
CreationHelper createHelper = wb.getCreationHelper();
// create a new sheet
Sheet s = wb.createSheet();
// declare a row object reference
Row r = null;
// declare a cell object reference
Cell c = null;
// create 2 cell styles
CellStyle cs = wb.createCellStyle();
CellStyle cs2 = wb.createCellStyle();
DataFormat df = wb.createDataFormat();
// create 2 fonts objects
Font f = wb.createFont();
Font f2 = wb.createFont();
// Set font 1 to 12 point type, blue and bold
f.setFontHeightInPoints((short) 12);
f.setColor( IndexedColors.RED.getIndex() );
f.setBoldweight(Font.BOLDWEIGHT_BOLD);
// Set font 2 to 10 point type, red and bold
f2.setFontHeightInPoints((short) 10);
f2.setColor( IndexedColors.RED.getIndex() );
f2.setBoldweight(Font.BOLDWEIGHT_BOLD);
// Set cell style and formatting
cs.setFont(f);
cs.setDataFormat(df.getFormat("#,##0.0"));
// Set the other cell style and formatting
cs2.setBorderBottom(cs2.BORDER_THIN);
cs2.setDataFormat(df.getFormat("text"));
cs2.setFont(f2);
// Define a few rows
for(int rownum = 0; rownum < 30; rownum++) {
Row r = s.createRow(rownum);
for(int cellnum = 0; cellnum < 10; cellnum += 2) {
Cell c = r.createCell(cellnum);
Cell c2 = r.createCell(cellnum+1);
c.setCellValue((double)rownum + (cellnum/10));
c2.setCellValue(
createHelper.createRichTextString("Hello! " + cellnum)
);
}
}
// Save
String filename = "workbook.xls";
if(wb instanceof XSSFWorkbook) {
filename = filename + "x";
}
FileOutputStream out = new FileOutputStream(filename);
wb.write(out);
out.close();
}
]]></source>
</section>
</section>
</body>
</document>

40
src/documentation/content/xdocs/spreadsheet/diagram1.xml Normal file
View File

@ -0,0 +1,40 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
====================================================================
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
====================================================================
-->
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "../dtd/document-v11.dtd">
<document>
<header>
<title>HSSF</title>
<subtitle>Overview</subtitle>
<authors>
<person name="Andrew C. Oliver" email="acoliver@apache.org"/>
<person name="Nicola Ken Barozzi" email="barozzi@nicolaken.com"/>
</authors>
</header>
<body>
<section>
<title>Usermodel Class Diagram by Matthew Young</title>
<p>
<img src="images/usermodel.gif" alt="Usermodel"/>
</p>
</section>
</body>
</document>

Some files were not shown because too many files have changed in this diff Show More