From: Uwe Schindler Date: Wed, 13 Aug 2014 12:36:10 +0000 (+0000) Subject: Replace release branch documentation by the old state of previous stable release... X-Git-Tag: REL_3_10_1~6 X-Git-Url: https://source.dussan.org/?a=commitdiff_plain;h=b0ca3b186418350aa7c01a1251f65bdf3f977609;p=poi.git Replace release branch documentation by the old state of previous stable release via svn copy instead of externals git-svn-id: https://svn.apache.org/repos/asf/poi/branches/REL_3_10_BRANCH@1617714 13f79535-47bb-0310-9956-ffa450edef68 --- diff --git a/src/documentation/README.txt b/src/documentation/README.txt new file mode 100644 index 0000000000..4545b58cba --- /dev/null +++ b/src/documentation/README.txt @@ -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. + diff --git a/src/documentation/RELEASE-NOTES.txt b/src/documentation/RELEASE-NOTES.txt new file mode 100644 index 0000000000..26a65d76a5 --- /dev/null +++ b/src/documentation/RELEASE-NOTES.txt @@ -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 + diff --git a/src/documentation/Release-Checklist.txt b/src/documentation/Release-Checklist.txt new file mode 100644 index 0000000000..1e22e75f2f --- /dev/null +++ b/src/documentation/Release-Checklist.txt @@ -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 /-RC-/ + 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) diff --git a/src/documentation/content/xdocs/3rdparty.xml b/src/documentation/content/xdocs/3rdparty.xml new file mode 100644 index 0000000000..b627e26fdb --- /dev/null +++ b/src/documentation/content/xdocs/3rdparty.xml @@ -0,0 +1,86 @@ + + + + + +
+ Third Party Contributions + + + +
+ + + +
How to Contribute +

+ See How to contribute to Poi. +

+ +
+ +
Contributed Components +

+ These are not necessarily deemed to be high enough quality to be included in the + core distribution, but they have been tested under + several key environments, they are provided under the same license + as Poi, and they are included in the POI distribution under the + contrib/ directory. +

+ +

+ None as yet! - 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. +

+
+ +
Patch Queue +

Submissions of modifications + to POI which are awaiting review. Anyone can + comment on them on the dev mailing list - code reviewers are needed! + Use these at your own risk - although POI has no guarantee + either, these patches have not been reviewed, let alone accepted. +

+
+ +
Other Extensions +

The other extensions listed here are not endorsed by the POI + project either - they are provided as a convenience only. They may or may not work, + they may or may not be open source, etc. +

+ +

To have a link added to this table, see How to contribute + to POI.

+ + + + + + + + + + +
Name and LinkTypeDescriptionStatusLicensingContact
+ +
+ + diff --git a/src/documentation/content/xdocs/book.xml b/src/documentation/content/xdocs/book.xml new file mode 100644 index 0000000000..92d41fcdea --- /dev/null +++ b/src/documentation/content/xdocs/book.xml @@ -0,0 +1,72 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/src/documentation/content/xdocs/casestudies.xml b/src/documentation/content/xdocs/casestudies.xml new file mode 100644 index 0000000000..0e55ddd8fd --- /dev/null +++ b/src/documentation/content/xdocs/casestudies.xml @@ -0,0 +1,321 @@ + + + + + +
+ Apache POI - Case Studies + + + + + + +
+ + +
+ Introduction +

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

+
+
+ Submitting a Case Study +

+ We are actively seeking case studies for this page (after all it + just started). To submit a case study, either + + submit a patch for this page or email it to the + mailing list + (with [PATCH] prefixed subject, please). +

+
+
+ Case Studies +
REWOO Scope +

+ REWOO Scope 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. +

+

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

+
+ +
QuestionPro +

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

+

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

+

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

+

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

+ +

+ Vivek Bhaskaran +

+

+ QuestionPro, Inc +

+ +

+ POI In Action - http://www.questionpro.com/marketing/SurveyReport-289.xls +

+ +
+ +
Sunshine Systems +

+ Sunshine Systems deveveloped a + POI based reporting solution for a price optimization software package which + is used by major retail chains. +

+

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

+

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

+

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

+

Rob Stevenson (rstevenson at sunshinesys dot com) +

+
+
+ Bank of Lithuania +

+ The + Bank of Lithuania + reports financial statistical data to Excel format using the + Apache POI + project's + + HSSF 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) +

+
+ + + + + + + + + +
+ Edwards And Kelcey Technology +

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

+

+ Cameron Riley (crileyNO@ SPAMekmail.com) +

+
+
+ ClickFind +

+ ClickFind Inc. 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) +

+
+
+ IKAN Software NV +

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.

+ +

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

+ +

It is obvious that Microsoft Excel files are also supported. + POI has been used to successfully implement this support in ETL4ALL.

+
+
+ JM Lafferty Associates, Inc. +

+ On its ForecastWorks website + JM Lafferty Associates, Inc. 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. +

+
    +
  • The PPT files produced are of high quality which is on a par with similar PDF files.
    • +
  • The XLS files produced contain a complex forecasting model built from a template with a VBA Macro.
    • +
+

+ David Fisher (dfisher@jmlafferty.com) +

+
+ +
+ iDATA Development Ltd (IDD) +

+ IDD have developed the iEXL product to + generate Excel spreadsheets directly on the Iseries/AS400 IBM I on Power platform. +

+

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

+

+ Design spreadsheets with: +

+
    +
  • Fonts down to cell level
    • +
  • Colours (Background and text) down to cell level
    • +
  • Shading down to cell level
    • +
  • Cell patterns down to cell level
    • +
  • Cell initialization
    • +
  • Freeze Panes
    • +
  • Passwords
    • +
  • Images/Pictures both static and dynamic
    • +
  • Headings
    • +
  • Page breaks
    • +
  • Sheet breaks
    • +
  • Text insertion and much more
    • +
  • Functions/Formula
    • +
  • Merge cells
    • +
  • Row Height
    • +
  • Cell text alignment
    • +
  • Text Rotation
    • +
  • 50 Database files per workbook.
    • +
  • E-mail the spreadsheet
    • +
+

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

+

+ All spreadsheets can be archived if required so that historical spreadsheets can be retrieved. +

+

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

+

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

+

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

+

+ Within the iEXLSOFTWARE.COM website you will find a full user manual, + installation instructions, a call log (Ticket) system and a downloadable 45 day trial version. +

+

+ Author: Mark.D.Golden +

+
+
+ Ugly Duckling +

+ Ugly Duckling focus on Software, Management and Finance. + We have recently been using Apache POI to create tools for the mortgage group of + ABN AMRO in the Netherlands. + During this project we created a number of what we call 'Robots' using the HSSF API. +

+

+ These robots 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. +

+

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

+
+ +
+ +
+ + Copyright (c) @year@ The Apache Software Foundation All rights reserved. +
+ Apache POI, POI, Apache, the Apache feather logo, and the Apache + POI project logo are trademarks of The Apache Software Foundation. + +
+ diff --git a/src/documentation/content/xdocs/download.xml b/src/documentation/content/xdocs/download.xml new file mode 100644 index 0000000000..1c81a56817 --- /dev/null +++ b/src/documentation/content/xdocs/download.xml @@ -0,0 +1,189 @@ + + + + + +
+ Apache POI - Download Release Artifacts +
+ + +
Available Downloads +

+ 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 + the project homepage. +

+
    +
  • The latest stable release is Apache POI 3.10-FINAL
    • +
  • Archives of all prior releases
    • +
+

+ Apache POI releases are available under the Apache License, Version 2.0. + See the NOTICE file contained in each release artifact for applicable copyright attribution notices. +

+

+ To insure that you have downloaded the true release you should verify the integrity + of the files using the signatures and checksums available from this page. +

+
+ +
23 January 2013 - POI 3.10-FINAL available +

The Apache POI team is pleased to announce the release of 3.10-FINAL. + This includes a large number of bug fixes and enhancements. +

+

A full list of changes is available in the change log. + People interested should also follow the dev list to track progress.

+

+ The POI source release as well as the pre-built binary deployment packages are listed below. + Pre-built versions of all POI components are available in the central Maven repository + under Group ID "org.apache.poi" and Version "3.10-FINAL". +

+
Binary Distribution +
    +
  • poi-bin-3.10-FINAL-20140208.tar.gz ( + 16MB, signed) +
    + MD5 checksum: + 818d1e99a2efe539ba49f622b554950c +
    + SHA1 checksum: + 38b61905d780e09604fb8053fd46ab1b8b18392f +
    • +
  • poi-bin-3.10-FINAL-20140208.zip ( + 23MB, signed) +
    + MD5 checksum: + e304be0a3169697d31e029f63458a963 +
    + SHA1 checksum: + 704f103bca893e3d4df5c2cc95d275b0cd5d0b33 +
    • +
+
+
Source Distribution +
    +
  • poi-src-3.10-FINAL-20140208.tar.gz ( + 48MB, signed) +
    + MD5 checksum: + 438157bfee9fe74869abd898820c7dae +
    + SHA1 checksum: + d0d5f596a649d1a852916fbadec4bdd9bdf70b9e +
    • +
  • poi-src-3.10-FINAL-20140208.zip ( + 58MB, signed) +
    + MD5 checksum: + 95536ea16e0e97a3f02f0294a1835b74 +
    + SHA1 checksum: + 8cc6ad470852295a8af7f08848a8ad9c84f177d1 +
    • +
+
+
+ +
Nightly Builds +

The POI nightly builds are run on Jenkins continuous integration server. + Note that these are no official builds and they are not endorsed or even supported by the POI team. +
+ These builds should not be used in production: they are only intended for use by developers + to help with resolving bugs and evaluating new features. +

+
    +
  • + Last Successful Jenkins build for POI-trunk
    • +
+
+ +
Verify +

+ It is essential that you verify the integrity of the downloaded files using the PGP or MD5 signatures. + Please read Verifying Apache HTTP Server Releases + for more information on why you should verify our releases. This page provides detailed instructions which you can use for POI artifacts. +

+

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

+ +% pgpk -a KEYS +% pgpv poi-X.Y.Z.jar.asc + +

or

+ +% pgp -ka KEYS +% pgp poi-X.Y.Z.jar.asc + +

or

+ +% gpg --import KEYS +% gpg --verify poi-X.Y.Z.jar.asc + +

Sample verification of poi-bin-3.5-FINAL-20090928.tar.gz

+ +% gpg --import KEYS +gpg: key 12DAE9BE: "Glen Stampoultzis <glens at apache dot org>" not changed +gpg: key 4CEED75F: "Nick Burch <nick at gagravarr dot org>" not changed +gpg: key 84B5A42E: "Rainer Klute <rainer.klute at gmx dot de>" not changed +gpg: key F5BB52CD: "Yegor Kozlov <yegor.kozlov at gmail dot com>" 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 <yegor.kozlov at gmail dot com>" +gpg: aka "Yegor Kozlov <yegor at dinom dot ru>" +gpg: aka "Yegor Kozlov <yegor at apache dot org>" +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 <yegor.kozlov at gmail dot com> +uid Yegor Kozlov <yegor at dinom dot ru> +uid Yegor Kozlov <yegor at apache dot org> +sub 4096g/7B45A98A 2007-06-18 [expires: 2012-06-16] + +
+
Release Archives +

+ 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 Apache Jakarta. +

+
    +
  • Binary Artifacts
    • +
  • Source Artifacts
    • +
  • Keys
    • +
  • Artifacts from prior to 3.0
    • +
+
+ +
+ + Copyright (c) @year@ The Apache Software Foundation. All rights reserved. +
+ Apache POI, POI, Apache, the Apache feather logo, and the Apache + POI project logo are trademarks of The Apache Software Foundation. + +
+ diff --git a/src/documentation/content/xdocs/dtd/ISOdia.pen b/src/documentation/content/xdocs/dtd/ISOdia.pen new file mode 100644 index 0000000000..df5c05d2ed --- /dev/null +++ b/src/documentation/content/xdocs/dtd/ISOdia.pen @@ -0,0 +1,34 @@ + + + + + + + + + + + + + + + + + + diff --git a/src/documentation/content/xdocs/dtd/ISOlat1.pen b/src/documentation/content/xdocs/dtd/ISOlat1.pen new file mode 100644 index 0000000000..6222e2f929 --- /dev/null +++ b/src/documentation/content/xdocs/dtd/ISOlat1.pen @@ -0,0 +1,79 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/src/documentation/content/xdocs/dtd/ISOnum.pen b/src/documentation/content/xdocs/dtd/ISOnum.pen new file mode 100644 index 0000000000..02605bfb58 --- /dev/null +++ b/src/documentation/content/xdocs/dtd/ISOnum.pen @@ -0,0 +1,109 @@ + + + + + + + + + + + + + + + + + + + + + + + + + +" > + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/src/documentation/content/xdocs/dtd/ISOpub.pen b/src/documentation/content/xdocs/dtd/ISOpub.pen new file mode 100644 index 0000000000..04a5732b45 --- /dev/null +++ b/src/documentation/content/xdocs/dtd/ISOpub.pen @@ -0,0 +1,110 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/src/documentation/content/xdocs/dtd/ISOtech.pen b/src/documentation/content/xdocs/dtd/ISOtech.pen new file mode 100644 index 0000000000..b3b39f9f1b --- /dev/null +++ b/src/documentation/content/xdocs/dtd/ISOtech.pen @@ -0,0 +1,85 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/src/documentation/content/xdocs/dtd/book-cocoon-v10.dtd b/src/documentation/content/xdocs/dtd/book-cocoon-v10.dtd new file mode 100644 index 0000000000..abd4410672 --- /dev/null +++ b/src/documentation/content/xdocs/dtd/book-cocoon-v10.dtd @@ -0,0 +1,70 @@ + + + + + + + + + + + + + + diff --git a/src/documentation/content/xdocs/dtd/changes-v11.dtd b/src/documentation/content/xdocs/dtd/changes-v11.dtd new file mode 100644 index 0000000000..2ec8c50128 --- /dev/null +++ b/src/documentation/content/xdocs/dtd/changes-v11.dtd @@ -0,0 +1,93 @@ + + + + + + + +%document; + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/src/documentation/content/xdocs/dtd/changes-v11.mod b/src/documentation/content/xdocs/dtd/changes-v11.mod new file mode 100644 index 0000000000..f9cd5cd835 --- /dev/null +++ b/src/documentation/content/xdocs/dtd/changes-v11.mod @@ -0,0 +1,71 @@ + + + + + + + + + + + + + + + + diff --git a/src/documentation/content/xdocs/dtd/changes-v13.dtd b/src/documentation/content/xdocs/dtd/changes-v13.dtd new file mode 100644 index 0000000000..8ffed7b69e --- /dev/null +++ b/src/documentation/content/xdocs/dtd/changes-v13.dtd @@ -0,0 +1,95 @@ + + + + + + + + +%document; + + + + + + +%common-charents; + + + + + + +%common; + + + + + + +%changes; + + + + diff --git a/src/documentation/content/xdocs/dtd/common-charents-v10.mod b/src/documentation/content/xdocs/dtd/common-charents-v10.mod new file mode 100644 index 0000000000..d495c1daa3 --- /dev/null +++ b/src/documentation/content/xdocs/dtd/common-charents-v10.mod @@ -0,0 +1,74 @@ + + + + + + + + +%ISOlat1; + + +%ISOpub; + + +%ISOtech; + + +%ISOnum; + + +%ISOdia; + + + + diff --git a/src/documentation/content/xdocs/dtd/common-elems-v10.mod b/src/documentation/content/xdocs/dtd/common-elems-v10.mod new file mode 100644 index 0000000000..ba7581cba6 --- /dev/null +++ b/src/documentation/content/xdocs/dtd/common-elems-v10.mod @@ -0,0 +1,68 @@ + + + + + + + + + + + + + + + + + + + + + + + diff --git a/src/documentation/content/xdocs/dtd/document-v11.dtd b/src/documentation/content/xdocs/dtd/document-v11.dtd new file mode 100644 index 0000000000..64252b6734 --- /dev/null +++ b/src/documentation/content/xdocs/dtd/document-v11.dtd @@ -0,0 +1,541 @@ + + + + + + + + + + +%ISOlat1; + + +%ISOpub; + + +%ISOtech; + + +%ISOnum; + + +%ISOdia; + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/src/documentation/content/xdocs/dtd/document-v13.dtd b/src/documentation/content/xdocs/dtd/document-v13.dtd new file mode 100644 index 0000000000..801a317f51 --- /dev/null +++ b/src/documentation/content/xdocs/dtd/document-v13.dtd @@ -0,0 +1,145 @@ + + + + + + + + + +%common-charents; + + + + + + +%document; + + + + diff --git a/src/documentation/content/xdocs/dtd/document-v13.mod b/src/documentation/content/xdocs/dtd/document-v13.mod new file mode 100644 index 0000000000..4c60b803bc --- /dev/null +++ b/src/documentation/content/xdocs/dtd/document-v13.mod @@ -0,0 +1,432 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/src/documentation/content/xdocs/dtd/faq-v11.dtd b/src/documentation/content/xdocs/dtd/faq-v11.dtd new file mode 100644 index 0000000000..abaa043865 --- /dev/null +++ b/src/documentation/content/xdocs/dtd/faq-v11.dtd @@ -0,0 +1,76 @@ + + + + + + + +%document; + + + + + + + + + + + + + + + + + + + + diff --git a/src/documentation/content/xdocs/dtd/faq-v12.mod b/src/documentation/content/xdocs/dtd/faq-v12.mod new file mode 100644 index 0000000000..3065a804d3 --- /dev/null +++ b/src/documentation/content/xdocs/dtd/faq-v12.mod @@ -0,0 +1,69 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/src/documentation/content/xdocs/dtd/faq-v13.dtd b/src/documentation/content/xdocs/dtd/faq-v13.dtd new file mode 100644 index 0000000000..2588ea8d45 --- /dev/null +++ b/src/documentation/content/xdocs/dtd/faq-v13.dtd @@ -0,0 +1,86 @@ + + + + + + + + +%document; + + + + + + +%common-charents; + + + + + + +%faq; + + + + diff --git a/src/documentation/content/xdocs/dtd/javadoc-v04draft.dtd b/src/documentation/content/xdocs/dtd/javadoc-v04draft.dtd new file mode 100644 index 0000000000..3a4301a4d1 --- /dev/null +++ b/src/documentation/content/xdocs/dtd/javadoc-v04draft.dtd @@ -0,0 +1,254 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/src/documentation/content/xdocs/dtd/specification-v11.dtd b/src/documentation/content/xdocs/dtd/specification-v11.dtd new file mode 100644 index 0000000000..b61242728b --- /dev/null +++ b/src/documentation/content/xdocs/dtd/specification-v11.dtd @@ -0,0 +1,92 @@ + + + + + + + +%document; + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/src/documentation/content/xdocs/dtd/todo-v11.dtd b/src/documentation/content/xdocs/dtd/todo-v11.dtd new file mode 100644 index 0000000000..476395d9a2 --- /dev/null +++ b/src/documentation/content/xdocs/dtd/todo-v11.dtd @@ -0,0 +1,96 @@ + + + + + + + + +%document; + + + + + + +%common-charents; + + + + + + +%common; + + + + + + +%todo; + + + + diff --git a/src/documentation/content/xdocs/dtd/todo-v11.mod b/src/documentation/content/xdocs/dtd/todo-v11.mod new file mode 100644 index 0000000000..102fca01f3 --- /dev/null +++ b/src/documentation/content/xdocs/dtd/todo-v11.mod @@ -0,0 +1,76 @@ + + + + + + + + + + + + + + + + + diff --git a/src/documentation/content/xdocs/dtd/todo-v13.dtd b/src/documentation/content/xdocs/dtd/todo-v13.dtd new file mode 100644 index 0000000000..9c28ec853d --- /dev/null +++ b/src/documentation/content/xdocs/dtd/todo-v13.dtd @@ -0,0 +1,99 @@ + + + + + + + + +%document; + + + + + + +%common-charents; + + + + + + +%common; + + + + + + +%todo; + + + + diff --git a/src/documentation/content/xdocs/encryption.xml b/src/documentation/content/xdocs/encryption.xml new file mode 100644 index 0000000000..8b88481940 --- /dev/null +++ b/src/documentation/content/xdocs/encryption.xml @@ -0,0 +1,112 @@ + + + + + + +
+ Apache POI - Encryption support + + + +
+ + +
Overview +

Apache POI contains support for reading few variants of encrypted office files:

+
    +
  • XLS - RC4 Encryption
    • +
  • XML-based formats (XLSX, DOCX and etc) - AES and Agile Encryption
    • +
+ +

Some "write-protected" files are encrypted with build-in password, POI can read that files too.

+
+ +
XLS +

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

+
+ +
XML-based formats - Decryption +

XML-based formats are stored in OLE-package stream "EncryptedPackage". Use org.apache.poi.poifs.crypt.Decryptor + to decode file:

+ + +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); +} + + +

If you want to read file encrypted with build-in password, use Decryptor.DEFAULT_PASSWORD.

+
+ +
XML-based formats - Encryption +

Encrypting a file is similar to the above decryption process. Basically you'll need to choose between + standard and agile encryption. + Apart of the CipherMode, the EncryptionInfo class provides further parameters to specify the cipher and + hashing algorithm to be used.

+ + +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(); + +
+ + +
+ + Copyright (c) @year@ The Apache Software Foundation. All rights reserved. +
+ Apache POI, POI, Apache, the Apache feather logo, and the Apache + POI project logo are trademarks of The Apache Software Foundation. + +
+ + + + + diff --git a/src/documentation/content/xdocs/entity/ISOdia.pen b/src/documentation/content/xdocs/entity/ISOdia.pen new file mode 100644 index 0000000000..df5c05d2ed --- /dev/null +++ b/src/documentation/content/xdocs/entity/ISOdia.pen @@ -0,0 +1,34 @@ + + + + + + + + + + + + + + + + + + diff --git a/src/documentation/content/xdocs/entity/ISOgrk1.pen b/src/documentation/content/xdocs/entity/ISOgrk1.pen new file mode 100644 index 0000000000..cdab380fc3 --- /dev/null +++ b/src/documentation/content/xdocs/entity/ISOgrk1.pen @@ -0,0 +1,74 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/src/documentation/content/xdocs/entity/ISOlat1.pen b/src/documentation/content/xdocs/entity/ISOlat1.pen new file mode 100644 index 0000000000..6222e2f929 --- /dev/null +++ b/src/documentation/content/xdocs/entity/ISOlat1.pen @@ -0,0 +1,79 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/src/documentation/content/xdocs/entity/ISOnum.pen b/src/documentation/content/xdocs/entity/ISOnum.pen new file mode 100644 index 0000000000..02605bfb58 --- /dev/null +++ b/src/documentation/content/xdocs/entity/ISOnum.pen @@ -0,0 +1,109 @@ + + + + + + + + + + + + + + + + + + + + + + + + + +" > + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/src/documentation/content/xdocs/entity/ISOpub.pen b/src/documentation/content/xdocs/entity/ISOpub.pen new file mode 100644 index 0000000000..04a5732b45 --- /dev/null +++ b/src/documentation/content/xdocs/entity/ISOpub.pen @@ -0,0 +1,110 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/src/documentation/content/xdocs/entity/ISOtech.pen b/src/documentation/content/xdocs/entity/ISOtech.pen new file mode 100644 index 0000000000..b3b39f9f1b --- /dev/null +++ b/src/documentation/content/xdocs/entity/ISOtech.pen @@ -0,0 +1,85 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/src/documentation/content/xdocs/faq.xml b/src/documentation/content/xdocs/faq.xml new file mode 100644 index 0000000000..09e3c10a28 --- /dev/null +++ b/src/documentation/content/xdocs/faq.xml @@ -0,0 +1,393 @@ + + + + + + + + My code uses some new feature, compiles fine but fails when live with a "MethodNotFoundException" or "IncompatibleClassChangeError" + + +

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.

+

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.

+ +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); + + + + + + My code uses the scratchpad, compiles fine but fails to run with a "MethodNotFoundException" + + +

You almost certainly have an older version earlier on your + classpath. See the prior answer.

+ + + + + I'm using the poi-ooxml-schemas jar, but my code is failing with "java.lang.NoClassDefFoundError: org/openxmlformats/schemas/*something*" + + +

To use the new OOXML file formats, POI requires a jar containing + the file format XSDs, as compiled by + XMLBeans. These + XSDs, once compiled into Java classes, live in the + org.openxmlformats.schemas namespace.

+

There are two jar files available, as described in + the components overview section. + The full jar of all of the schemas is ooxml-schemas-1.1.jar, + and it is currently around 15mb. The smaller poi-ooxml-schemas + jar is only about 4mb. This latter jar file only contains the + typically used parts though.

+

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.

+

There are a number of ways to get the full ooxml-schemas-1.1.jar. + If you are a maven user, see the + the components overview section + 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 subversion, + 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 + POI + Maven Repository.

+

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

+ + + + + Why is reading a simple sheet taking so long? + + +

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.

+ + + + + What is the HSSF "eventmodel"? + + +

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.

+ + + + + Why can't read the document I created using Star Office 5.1? + + +

Star Office 5.1 writes some records using the older BIFF standard. This causes some problems + with POI which supports only BIFF8.

+ + + + + Why am I getting an exception each time I attempt to read my spreadsheet? + + +

It's possible your spreadsheet contains a feature that is not currently supported by POI. + If you encounter this then please create the simplest file that demonstrates the trouble and submit it to + Bugzilla.

+ + + + + How do you tell if a spreadsheet cell contains a date? + + +

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.

+ + 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; + } + + + + + + I'm trying to stream an XLS file from a servlet and I'm having some trouble. What's the problem? + + +

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

+

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

+

+ 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 + .xls to your request + string. For example + http://yourserver.com/myServelet.xls?param1=xx. This is + easily accomplished through URL mapping in any servlet container. Sometimes + a request like + http://yourserver.com/myServelet?param1=xx&dummy=file.xls is also + known to work. +

+

+ 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) +

+

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

+

+ 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 + FOP, you will come across many of the same issues. +

+ + + + + + I want to set a cell format (Data format of a cell) of a excel sheet as ###,###,###.#### or ###,###,###.0000. Is it possible using POI ? + + +

+ Yes. You first need to get a DataFormat object from the workbook and call getFormat with the desired format. Some examples are here. +

+ + + + + I want to set a cell format (Data format of a cell) of a excel sheet as text. Is it possible using POI ? + + +

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

+ + + + + How do I add a border around a merged cell? + + +

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.

+ + + + + I am using styles when creating a workbook in POI, but Excel refuses to open the file, complaining about "Too Many Styles". + + +

You just create the styles OUTSIDE of the loop in which you create cells.

+

GOOD:

+ + 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 < 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 < 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(); + +

BAD:

+ + HSSFWorkbook wb = new HSSFWorkbook(); + HSSFSheet sheet = wb.createSheet("new sheet"); + HSSFRow row = null; + + for (int x = 0; x < 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 < 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(); + + + + + + I can't seem to find the source for the OOXML CT.. classes, where do they + come from? + + +

The OOXML support in Apache POI is built on top of the file format + XML Schemas, as compiled into Java using + XMLBeans. 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).

+

All of the org.openxmlformats.schemas.spreadsheetml.x2006 CT... + classes are auto-generated by XMLBeans. The resulting generated Java goes + in the ooxml-schemas-src jar, and the compiled version into the + ooxml-schemas jar.

+

The full ooxml-schemas jar is distributed with Apache POI, + along with the cut-down poi-ooxml-schemas 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 ooxml-schemas-src 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.

+ + + + + An OLE2 ("binary") file is giving me problems, but I can't share it. How can I investigate the problem on my own? + + +

The first thing to try is running the + Binary File Format Validator + 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 + latest codebase, report a new + POI bug and include the details of the validation failure.

+

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 org.apache.poi.hssf.dev.BiffViewer + 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.

+ + + + + An OOXML ("xml") file is giving me problems, but I can't share it. How can I investigate the problem on my own? + + +

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.

+

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?

+

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.

+ + + diff --git a/src/documentation/content/xdocs/guidelines.xml b/src/documentation/content/xdocs/guidelines.xml new file mode 100644 index 0000000000..66376b58f5 --- /dev/null +++ b/src/documentation/content/xdocs/guidelines.xml @@ -0,0 +1,329 @@ + + + + + +
+ Apache POI - Contribution Guidelines + + + + +
+ + + +
Index of Contribution Guidelines +
    +
  • Introduction
    • +
  • I just want to get involved, but don't know where to start?
    • +
  • Submitting Patches
    • +
  • Code Style
    • +
  • Mentoring and Committership
    • +
+
+ + +
Introduction + +
Disclaimer +

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

+
+ +
The Licensing +

+ The POI project is OpenSource + and developed/distributed under the + Apache Software License. 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. +

+
+
Publicly Available Information on the file formats +

+ 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 Open + Specification Promise, which does allow us to use them for + building open source software under the + Apache Software License. +

+

+ You can download the documentation on Excel, Word, PowerPoint and + Escher (drawing) from + http://msdn.microsoft.com/en-us/library/cc313118.aspx. + Documentation on a few of the supporting technologies used in these + file formats can be downloaded from + http://msdn.microsoft.com/en-us/library/jj633110.aspx. +

+

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

+

+ 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 + http://www.ecma-international.org/publications/standards/Ecma-376.htm, + and is also under the OSP. +

+

+ It is also worth checking the documentation and code of the other + open source implementations of the file formats. +

+
+
I just signed an NDA to get a spec from Microsoft and I'd like to contribute +

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

+

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

+

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

+
+
+ + +
I just want to get involved, but don't know where to start? +
    +
  • Read the rest of the website, understand what POI is and what it does, + the project vision, etc.
    • +
  • Use POI a bit, look for gaps in the documentation and examples.
    • +
  • Join the mailing lists and share your knowledge with others.
    • +
  • Get Subversion and check out the POI source tree
    • +
  • 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.
    • +
  • Contribute examples - if there's something people are often asking about on the user list which isn't covered in the documentation or current examples, try writing an example of this and uploading it as a patch.
    • +
  • Get used to building POI, you'll be doing it a lot, be one with the build, know its targets, etc.
    • +
  • 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.
    • +
  • Download the file format documentation from Microsoft - + OLE2 Binary File Formats or + OOXML XML File Formats
    • +
  • Submit patches (see below) of your contributions, modifications.
    • +
  • Check the bug database for simple problem reports, and write a patch to fix the problem
    • +
  • Review existing patches in the bug database, and report if they still apply, if they need unit tests atc.
    • +
  • Take a look at all the unresolved issues in the bug database, and see if you can help with testing or patches for them
    • +
  • Add in new features, see Bug database for suggestions.
    • +
+ +

The Apache Contributors Tech Guide gives a good overview how to start contributing patches.

+ +

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 + http://wiki.apache.org/nutch/Becoming_A_Nutch_Developer. The + Apache Community Development + Project also provides guidance and mentoring for new contributors.

+
+ + +
Submitting Patches +

+ Patches are submitted via the Bug Database. + 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?). +

+

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

+

+ 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 + Apache Commons one + is fairly similar as a starting point. +

+

You may create your patch file using either of the following approaches (the committers recommend the first):

+
Approach 1 - use Ant +

Use Ant to generate a patch file to POI:

+ + ant -f patch.xml + +

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

+
+
Approach 2 - the manual way +

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

+

If you use a unix shell, you may find the following following + sequence of commands useful for building the files to attach.

+ + # 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" + +
+
checklist before submitting a patch +
    +
  • added code complies with coding standards
    • +
  • added code compiles and runs on java 1.5
    • +
  • new java files begin with the + apache software license statement.
    • +
  • the code does not depend on gpl or lgpl code.
    • +
  • the code doesn't include @author tags
    • +
  • existing test cases succeed.
    • +
  • new test cases written and succeed.
    • +
  • documentation page extended as appropriate.
    • +
  • diff files generated using svn diff
    • +
  • the bugzilla subject dev contains [patch], task name and patch reason in subject.
    • +
  • the bugzilla description contains a rationale for the patch.
    • +
  • attachment to the bugzilla entry contains the patch file(s).
    • +
+
+
+ + +
Code Style +

The long standing + Minimal + Coding Standards from 2002 still largely apply to the project.

+

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.

+

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.

+

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.

+

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!

+
+ + +
Mentoring and Committership +

The POI project will generally offer committership to contributors who send + in consistently good patches over a period of several months.

+

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 dev mailing list.

+

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.

+

Where possible, patches should be submitted early and often. For more details + on this, please see the "Submitting Patches" section above.

+ +

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 + dev mailing list so that other + contributors can assist you!

+

For more information on getting started at Apache, mentoring, and local + Apache Committers near you who can offer advice, please see the + Apache Community Development + Project website.

+
+ + +
+ + Copyright (c) @year@ The Apache Software Foundation. All rights reserved. +
+ Apache POI, POI, Apache, the Apache feather logo, and the Apache + POI project logo are trademarks of The Apache Software Foundation. + +
+ diff --git a/src/documentation/content/xdocs/hdgf/book.xml b/src/documentation/content/xdocs/hdgf/book.xml new file mode 100644 index 0000000000..dcee53a814 --- /dev/null +++ b/src/documentation/content/xdocs/hdgf/book.xml @@ -0,0 +1,34 @@ + + + + + + + + + + + + + + + diff --git a/src/documentation/content/xdocs/hdgf/index.xml b/src/documentation/content/xdocs/hdgf/index.xml new file mode 100644 index 0000000000..fc24c108d7 --- /dev/null +++ b/src/documentation/content/xdocs/hdgf/index.xml @@ -0,0 +1,101 @@ + + + + + +
+ POI-HDGF - Java API To Access Microsoft Visio Format Files + Overview + + + +
+ + +
+ Overview + +

HDGF is the POI Project's pure Java implementation of the Visio file format.

+

Currently, HDGF provides a low-level, read-only api for + accessing Visio documents. It also provides a + way + to extract the textual content from a file. +

+

At this time, there is no usermodel 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 + vsdump + to get a feel for how Visio files are structured.

+

To get a feel for the contents of a file, and to track down + where data of interest is stored, HDGF comes with + VSDDumper + to print out the contents of the file. Users should also make + use of + vsdump + to probe the structure of files.

+ + This code currently lives the + scratchpad area + 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. + + +
+ Steps required for write support +

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.

+
    +
  1. Re-write the decompression support in LZW4HDGF as + HDGFLZW, which will be much better documented, and also + under the ASL. Completed October 2007
    2. +
  2. Add compression support to HDGFLZW. + In progress - works for small streams but encoding + goes wrong on larger ones
    3. +
  3. Have HDGF just write back the raw bytes it read in, and + have a test to ensure the file is un-changed.
    4. +
  4. 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.
    5. +
  5. 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.
    6. +
  6. Have HDGF re-generate the offsets in pointers for the + locations of the streams. Plus test to ensure file is + un-changed.
    7. +
  7. 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
    8. +
  8. Alter the data of one command, but keep it the same + length, and check visio can open the file when written + out.
    9. +
  9. Alter the data of one command, to a new length, and + check that visio can open the file when written out.
    10. +
+
+
+ + diff --git a/src/documentation/content/xdocs/historyandfuture.xml b/src/documentation/content/xdocs/historyandfuture.xml new file mode 100644 index 0000000000..74faebf520 --- /dev/null +++ b/src/documentation/content/xdocs/historyandfuture.xml @@ -0,0 +1,158 @@ + + + + + +
+ Apache POI - Project History + + + +
+ + + + +
Apache POI - Brief Project History + +

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

+ +

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

+ +

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 +

+ +

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

+ +

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

+ +

Somewhere in there we decided to finally submit the project + to The Apache + Cocoon Project, 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! +

+ +

In Early 2007, we graduated from + Jakarta, and became + our own Top Level Project (TLP) within Apache.

+
+ + + + +
+ + Copyright (c) @year@ The Apache Software Foundation All rights reserved. +
+ Apache POI, POI, Apache, the Apache feather logo, and the Apache + POI project logo are trademarks of The Apache Software Foundation. + +
+ + + diff --git a/src/documentation/content/xdocs/hmef/book.xml b/src/documentation/content/xdocs/hmef/book.xml new file mode 100644 index 0000000000..6e42baf15f --- /dev/null +++ b/src/documentation/content/xdocs/hmef/book.xml @@ -0,0 +1,34 @@ + + + + + + + + + + + + + + + diff --git a/src/documentation/content/xdocs/hmef/index.xml b/src/documentation/content/xdocs/hmef/index.xml new file mode 100644 index 0000000000..adf1624252 --- /dev/null +++ b/src/documentation/content/xdocs/hmef/index.xml @@ -0,0 +1,212 @@ + + + + + +
+ POI-HMEF - Java API To Access Microsoft Transport Neutral Encoding Files (TNEF) + Overview + + + +
+ + +
+ Overview + +

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.

+

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.

+

HMEF also provides a command line tool for extracting out + the message body and attachment files from a TNEF (winmail.dat) + file.

+ + + This code currently lives the + scratchpad area + 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. + + + 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 svn + checkout. + +
+ +
+ Using HMEF to access TNEF (winmail.dat) files + +
+ Easy extraction of message body and attachment files + +

The class org.apache.poi.hmef.extractor.HMEFContentsExtractor + 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.

+ +

From the command line, simply call the class specifying the + TNEF file to extract, and the directory to place the extracted + files into, eg:

+ + java -classpath poi-3.8-FINAL.jar:poi-scratchpad-3.8-FINAL.jar org.apache.poi.hmef.extractor.HMEFContentsExtractor winmail.dat /tmp/extracted/ + + +

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:

+ +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"); +} + +
+ +
+ Attachment attributes and contents + +

To get at your attachments, simply call the + getAttachments() method on a HMEFMessage + instance, and you'll receive a list of all the attachments.

+

When you have a org.apache.poi.hmef.Attachment 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.

+
    +
  • getFilename() - returns the name of the attachment + file, possibly in 8.3 format
    • +
  • getLongFilename() - returns the full name of the + attachment file
    • +
  • getExtension() - returns the extension of the + attachment file, including the "."
    • +
  • getModifiedDate() - returns the date that the + attachment file was last edited on
    • +
  • getContents() - returns a byte array of the contents + of the attached file
    • +
  • getRenderedMetaFile() - returns a byte array of + a windows meta file representation of the attached file
    • +
+
+ +
+ Message attributes and message body + +

A org.apache.poi.hmef.HMEFMessage instance is created + from an InputStream of the underlying TNEF (winmail.dat) + file.

+

From a HMEFMessage, there are three main methods of + interest to call:

+
    +
  • getBody() - returns a String containing the RTF + contents of the message body.
    • +
  • getSubject() - returns the message subject
    • +
  • getAttachments() - returns the list of + Attachment objects for the message
    • +
+
+ +
+ Low level attribute access + +

Both Messages and Attachments contain two kinds of attributes. + These are TNEFAttribute and MAPIAttribute.

+

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.

+

MAPIAttributes hold standard MAPI properties and values, and + work in a similar way to HSMF + (Outlook) does. There are typically many of these on both + Messages and Attachments. Note - see limitations

+

Both HMEFMessage and Attachment 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.

+ +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)); +} + +
+
+ +
+ Investigating a TNEF file + +

To get a feel for the contents of a file, and to track down + where data of interest is stored, HMEF comes with + HMEFDumper + to print out the contents of the file.

+
+ +
+ Limitations + +

HMEF is currently a work-in-progress, and not everything + works yet. The current limitations are:

+
    +
  • 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.
    • +
  • 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!
    • +
+
+ + diff --git a/src/documentation/content/xdocs/howtobuild.xml b/src/documentation/content/xdocs/howtobuild.xml new file mode 100644 index 0000000000..ad2cd1cf87 --- /dev/null +++ b/src/documentation/content/xdocs/howtobuild.xml @@ -0,0 +1,125 @@ + + + + + +
+ Apache POI - How To Build + + + + + +
+ +
+ JDK Version +

+ POI 3.5 and later requires the JDK version 1.5 or later. + Versions prior to 3.5 require JDK 1.4+ +

+
+
+ Install Apache Ant +

+ The POI build system requires Apache Ant +

+

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

+

+ Remember to set the ANT_HOME environment variable and add ANT_HOME/bin + to your shell's PATH. +

+
+
+ Install JUnit +

+ Running unit tests and building a distribution requires JUnit. +

+

+ Just pick the latest versions of the jars from + SourceForge and place + them in ANT_HOME/lib. Make sure that optional.jar is in ANT_HOME/lib. +

+
+
+ Install Apache Forrest +

+ The POI build system requires Apache Forrest to build the documentation. +

+

+ Specifically the build has been tested to work with Forrest 0.5. This is an old release which is available + here. +

+

+ Remember to set the FORREST_HOME environment variable. +

+
+
+ Building Targets with Ant +

+ The main targets of interest to our users are: +

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Ant TargetDescription
cleanErase all build work products (ie. everything in the + build directory
compileCompiles all files from main, ooxml and scratchpad
testRun all unit tests from main, ooxml and scratchpad
jarProduce jar files
assembleProduce .zip and tar.gz distribution packages
docsGenerate all documentation (Requires Apache Forrest)
+
+ +
+ + Copyright (c) @year@ The Apache Software Foundation. All rights reserved. +
+ Apache POI, POI, Apache, the Apache feather logo, and the Apache + POI project logo are trademarks of The Apache Software Foundation. + +
+ + + diff --git a/src/documentation/content/xdocs/hpbf/book.xml b/src/documentation/content/xdocs/hpbf/book.xml new file mode 100644 index 0000000000..9aceee7a36 --- /dev/null +++ b/src/documentation/content/xdocs/hpbf/book.xml @@ -0,0 +1,35 @@ + + + + + + + + + + + + + + + + diff --git a/src/documentation/content/xdocs/hpbf/file-format.xml b/src/documentation/content/xdocs/hpbf/file-format.xml new file mode 100644 index 0000000000..ed01858288 --- /dev/null +++ b/src/documentation/content/xdocs/hpbf/file-format.xml @@ -0,0 +1,197 @@ + + + + + +
+ POI-HPBF - A Guide to the Publisher File Format + Overview + + + +
+ + +
Document Streams +

+ The file is made up of a number of POIFS streams. A typical + file will be made up as follows: +

+ +Root Entry - + Objects - + (no children) + SummaryInformation <(0x05)SummaryInformation> + DocumentSummaryInformation <(0x05)DocumentSummaryInformation> + Escher - + EscherStm + EscherDelayStm + Quill - + QuillSub - + CONTENTS + CompObj <(0x01)CompObj> + Envelope + Contents + Internal <(0x03)Internal> + CompObj <(0x01)CompObj> + VBA - + (no children) + +
+
Changing Text +

If you make a change to the text of a file, but not change + how much text there is, then the CONTENTS stream + will undergo a small change, and the Contents stream + will undergo a large change.

+

If you make a change to the text of a file, and change the + amount of text there is, then both the Contents and + the CONTENTS streams change.

+
+
Changing Shapes +

If you alter the size of a textbox, but make no text changes, + then both Contents and CONTENTS streams + change. There are no changes to the Escher streams.

+

If you set the background colour of a textbox, but make + no changes to the text, (to finish off)

+
+
Structure of CONTENTS +

First we have "CHNKINK ", followed by 24 bytes.

+

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.

+

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.

+

At 0x200 we have the text, stored as little endian 16 bit unicode.

+

After the text comes all sorts of other stuff, presumably as + described by the sequences.

+

For a contents stream of length 7168 / 0x1c00 bytes, the start + looks something like:

+ +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) + +

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.

+ +
Structure of TEXT bit +

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.

+
+
Structure of PLC bit +

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.

+

Type 0 has 4 2 byte unsigned ints, then a pair of 2 byte + unsigned ints for each entry.

+

Type 4 has 4 2 byte unsigned ints, then a pair of 4 byte + unsigned ints for each entry.

+

Type 8 has 7 2 byte unsigned ints, then a pair of 4 byte + unsigned ints for each entry.

+

Type 12 holds hyperlinks, and is very much more complex. + See org.apache.poi.hpbf.model.qcbits.QCPLCBit + for our best guess as to how the contents match up.

+
+
+ + diff --git a/src/documentation/content/xdocs/hpbf/index.xml b/src/documentation/content/xdocs/hpbf/index.xml new file mode 100644 index 0000000000..4443db97c9 --- /dev/null +++ b/src/documentation/content/xdocs/hpbf/index.xml @@ -0,0 +1,66 @@ + + + + + +
+ POI-HPBF - Java API To Access Microsoft Publisher Format Files + Overview + + + +
+ + +
+ Overview + +

HPBF is the POI Project's pure Java implementation of the + Publisher file format.

+

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.

+

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.

+

Text Extraction is available via the + org.apache.poi.hpbf.extractor.PublisherTextExtractor + class.

+

At this time, there is no usermodel api or similar. + There is only low level support for certain parts of + the file, but by no means all of it.

+

Our current understanding of the file format is documented + here.

+ + This code currently lives the + scratchpad area + 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. + +
+ + diff --git a/src/documentation/content/xdocs/hpsf/book.xml b/src/documentation/content/xdocs/hpsf/book.xml new file mode 100644 index 0000000000..6f45e54d97 --- /dev/null +++ b/src/documentation/content/xdocs/hpsf/book.xml @@ -0,0 +1,36 @@ + + + + + + + + + + + + + + + + + diff --git a/src/documentation/content/xdocs/hpsf/how-to.xml b/src/documentation/content/xdocs/hpsf/how-to.xml new file mode 100644 index 0000000000..520f9d0c03 --- /dev/null +++ b/src/documentation/content/xdocs/hpsf/how-to.xml @@ -0,0 +1,1500 @@ + + + + + +
+ HPSF HOW-TO + + + +
+ +
How To Use the HPSF API + +

This HOW-TO is organized in four sections. You should read them + sequentially because the later sections build upon the earlier ones.

+ +
    +
  1. + The first section explains how to read + the most important standard properties of a Microsoft Office + document. Standard properties are things like title, author, creation + date etc. It is quite likely that you will find here what you need and + don't have to read the other sections. +
    2. + +
  2. + The second section goes a small step + further and focusses on reading additional standard + properties. It also talks about exceptions that + may be thrown when dealing with HPSF and shows how you can read + properties of embedded objects. +
    3. + +
  3. + The third section explains how to write + standard properties. HPSF provides some high-level classes and + methods which make writing of standard properties easy. They are based on + the low-level writing functions explained in the fifth + section. +
    4. + +
  4. + The fourth section tells how to read + non-standard properties. Non-standard properties are + application-specific triples consisting of an ID, a type, and a value. +
    5. + +
  5. + The fifth section tells you how to write + property set streams using HPSF's low-level methods. You have to + understand the fourth section before you should + think about low-level writing properties. Check the Javadoc API + documentation to find out about the details! +
    6. +
+ + Please note: HPSF's writing functionality is + not present in POI releases up to and including 2.5. In + order to write properties you have to download a 3.0.x POI release, + or retrieve the POI development version from the Subversion repository. + + + + +
Reading Standard Properties + + This section explains how to read the most important standard + properties of a Microsoft Office document. Standard properties are things + like title, author, creation date etc. This section introduces the + summary information stream which is used to keep these + properties. Chances are that you will find here what you need and don't + have to read the other sections. + +

If all you are interested in is getting the textual content of + all the document properties, such as for full text indexing, then + take a look at + org.apache.poi.hpsf.extractor.HPSFPropertiesExtractor. However, + if you want full access to the properties, please read on!

+ +

The first thing you should understand is that a Microsoft Office file is + not one large bunch of bytes but has an internal filesystem structure with + files and directories. You can access these files and directories using + the POI filesystem (POIFS) + provides. A file or document in a POI filesystem is also called a + stream - The properties of, say, an Excel document are + stored apart of the actual spreadsheet data in separate streams. The good + new is that this separation makes the properties independent of the + concrete Microsoft Office file. In the following text we will always say + "POI filesystem" instead of "Microsoft Office file" because a POI + filesystem is not necessarily created by or for a Microsoft Office + application, because it is shorter, and because we want to avoid the name + of That Redmond Company.

+ +

The following example shows how to read the "title" property. Reading + other properties is similar. Consider the API documentation of the class + org.apache.poi.hpsf.SummaryInformation to learn which methods + are available.

+ +

The standard properties this section focusses on can be found in a + document called \005SummaryInformation located in the root of the + POI filesystem. The notation \005 in the document's name means + the character with a decimal value of 5. In order to read the "title" + property, an application has to perform the following steps:

+ +
    +
  1. + Open the document \005SummaryInformation located in the root + of the POI filesystem. +
    2. +
  2. + Create an instance of the class SummaryInformation from + that document. +
    3. +
  3. + Call the SummaryInformation instance's + getTitle() method. +
    4. +
+ +

Sounds easy, doesn't it? Here are the steps in detail.

+ + +
Open the document \005SummaryInformation in the root of the + POI filesystem + +

An application that wants to open a document in a POI filesystem + (POIFS) proceeds as shown by the following code fragment. The full + source code of the sample application is available in the + examples section of the POI source tree as + ReadTitle.java.

+ + +import java.io.*; +import org.apache.poi.hpsf.*; +import org.apache.poi.poifs.eventfilesystem.*; + +// ... + +public static void main(String[] args) + throws IOException +{ + final String filename = args[0]; + POIFSReader r = new POIFSReader(); + r.registerListener(new MyPOIFSReaderListener(), + "\005SummaryInformation"); + r.read(new FileInputStream(filename)); +} + +

The first interesting statement is

+ + POIFSReader r = new POIFSReader(); + +

It creates a + org.apache.poi.poifs.eventfilesystem.POIFSReader instance + which we shall need to read the POI filesystem. Before the application + actually opens the POI filesystem we have to tell the + POIFSReader which documents we are interested in. In this + case the application should do something with the document + \005SummaryInformation.

+ + +r.registerListener(new MyPOIFSReaderListener(), + "\005SummaryInformation"); + +

This method call registers a + org.apache.poi.poifs.eventfilesystem.POIFSReaderListener + with the POIFSReader. The POIFSReaderListener + interface specifies the method processPOIFSReaderEvent() + which processes a document. The class + MyPOIFSReaderListener implements the + POIFSReaderListener and thus the + processPOIFSReaderEvent() method. The eventing POI + filesystem calls this method when it finds the + \005SummaryInformation document. In the sample application + MyPOIFSReaderListener is a static class in the + ReadTitle.java source file.

+ +

Now everything is prepared and reading the POI filesystem can + start:

+ + r.read(new FileInputStream(filename)); + +

The following source code fragment shows the + MyPOIFSReaderListener class and how it retrieves the + title.

+ + +static class MyPOIFSReaderListener implements POIFSReaderListener +{ + public void processPOIFSReaderEvent(POIFSReaderEvent event) + { + SummaryInformation si = null; + try + { + si = (SummaryInformation) + PropertySetFactory.create(event.getStream()); + } + catch (Exception ex) + { + throw new RuntimeException + ("Property set stream \"" + + event.getPath() + event.getName() + "\": " + ex); + } + final String title = si.getTitle(); + if (title != null) + System.out.println("Title: \"" + title + "\""); + else + System.out.println("Document has no title."); + } +} + + +

The line

+ + SummaryInformation si = null; + +

declares a SummaryInformation variable and initializes it + with null. We need an instance of this class to access the + title. The instance is created in a try block:

+ + si = (SummaryInformation) + PropertySetFactory.create(event.getStream()); + +

The expression event.getStream() returns the input stream + containing the bytes of the property set stream named + \005SummaryInformation. This stream is passed into the + create method of the factory class + org.apache.poi.hpsf.PropertySetFactory which returns + a org.apache.poi.hpsf.PropertySet instance. It is more or + less safe to cast this result to SummaryInformation, a + convenience class with methods like getTitle(), + getAuthor() etc.

+ +

The PropertySetFactory.create() method may throw all sorts + of exceptions. We'll deal with them in the next sections. For now we just + catch all exceptions and throw a RuntimeException + containing the message text of the origin exception.

+ +

If all goes well, the sample application retrieves the title and prints + it to the standard output. As you can see you must be prepared for the + case that the POI filesystem does not have a title.

+ + final String title = si.getTitle(); +if (title != null) + System.out.println("Title: \"" + title + "\""); +else + System.out.println("Document has no title."); + +

Please note that a POI filesystem does not necessarily contain the + \005SummaryInformation stream. The documents created by the + Microsoft Office suite have one, as far as I know. However, an Excel + spreadsheet exported from StarOffice 5.2 won't have a + \005SummaryInformation stream. In this case the applications + won't throw an exception but simply does not call the + processPOIFSReaderEvent method. You have been warned!

+
+
+ + +
Additional Standard Properties, Exceptions And Embedded + Objects + + This section focusses on reading additional standard properties which + are kept in the document summary information stream. It + also talks about exceptions that may be thrown when dealing with HPSF and + shows how you can read properties of embedded objects. + +

A couple of additional standard properties are not + contained in the \005SummaryInformation stream explained + above. Examples for such properties are a document's category or the + number of multimedia clips in a PowerPoint presentation. Microsoft has + invented an additional stream named + \005DocumentSummaryInformation to hold these properties. With two + minor exceptions you can proceed exactly as described above to read the + properties stored in \005DocumentSummaryInformation:

+ +
    +
  • Instead of \005SummaryInformation use + \005DocumentSummaryInformation as the stream's name.
    • +
  • Replace all occurrences of the class + SummaryInformation by + DocumentSummaryInformation.
    • +
+ +

And of course you cannot call getTitle() because + DocumentSummaryInformation has different query methods, + e.g. getCategory. See the Javadoc API documentation for the + details.

+ +

In the previous section the application simply caught all + exceptions and was in no way interested in any + details. However, a real application will likely want to know what went + wrong and act appropriately. Besides any I/O exceptions there are three + HPSF resp. POI specific exceptions you should know about:

+ +
+
NoPropertySetStreamException:
+
+ This exception is thrown if the application tries to create a + PropertySet instance from a stream that is not a + property set stream. (SummaryInformation and + DocumentSummaryInformation are subclasses of + PropertySet.) A faulty property set stream counts as not + being a property set stream at all. An application should be prepared to + deal with this case even if it opens streams named + \005SummaryInformation or + \005DocumentSummaryInformation. These are just names. A + stream's name by itself does not ensure that the stream contains the + expected contents and that this contents is correct. +
+ +
UnexpectedPropertySetTypeException
+
This exception is thrown if a certain type of property set is + expected somewhere (e.g. a SummaryInformation or + DocumentSummaryInformation) but the provided property + set is not of that type.
+ +
MarkUnsupportedException
+
This exception is thrown if an input stream that is to be parsed + into a property set does not support the + InputStream.mark(int) operation. The POI filesystem uses + the DocumentInputStream class which does support this + operation, so you are safe here. However, if you read a property set + stream from another kind of input stream things may be + different.
+
+ +

Many Microsoft Office documents contain embedded + objects, for example an Excel sheet within a Word + document. Embedded objects may have property sets of their own. An + application can open these property set streams as described above. The + only difference is that they are not located in the POI filesystem's root + but in a nested directory instead. Just register a + POIFSReaderListener for the property set streams you are + interested in. For example, the POIBrowser application + tries to open each and every document in a POI filesystem + as a property set stream. If this operation was successful it displays the + properties.

+
+ + + + +
Writing Standard Properties + + This section explains how to write standard + properties. HPSF provides some high-level classes and methods + which make writing of standard properties easy. They are based on the + low-level writing functions explained in another + section. + +

As explained above, standard properties are located in the summary + information and document summary information streams of typical POI + filesystems. You have already learned about the classes + SummaryInformation and + DocumentSummaryInformation and their get...() + methods for reading standard properties. These classes also provide + set...() methods for writing properties.

+ +

After setting properties in SummaryInformation or + DocumentSummaryInformation you have to write them to a disk + file. The following sample program shows how you can

+ +
    +
  1. read a disk file into a POI filesystem,
    2. +
  2. read the document summary information from the POI filesystem,
    3. +
  3. set a property to a new value,
    4. +
  4. write the modified document summary information back to the POI + filesystem, and
    5. +
  5. write the POI filesystem to a disk file.
    6. +
+ +

The complete source code of this program is available as + ModifyDocumentSummaryInformation.java in the examples + section of the POI source tree.

+ + Dealing with the summary information stream is analogous to handling + the document summary information and therefore does not need to be + explained here in detailed. See the HPSF API documentation to learn about + the set...() methods of the class + SummaryInformation. + +

The first step is to read the POI filesystem into memory:

+ + InputStream is = new FileInputStream(poiFilesystem); +POIFSFileSystem poifs = new POIFSFileSystem(is); +is.close(); + +

The code snippet above assumes that the variable + poiFilesystem holds the name of a disk file. It reads the + file from an input stream and creates a POIFSFileSystem + object in memory. After having read the file, the input stream should be + closed as shown.

+ +

In order to read the document summary information stream the application + must open the element \005DocumentSummaryInformation in the POI + filesystem's root directory. However, the POI filesystem does not + necessarily contain a document summary information stream, and the + application should be able to deal with that situation. The following + code does so by creating a new DocumentSummaryInformation if + there is none in the POI filesystem:

+ + DirectoryEntry dir = poifs.getRoot(); +DocumentSummaryInformation dsi; +try +{ + DocumentEntry dsiEntry = (DocumentEntry) + dir.getEntry(DocumentSummaryInformation.DEFAULT_STREAM_NAME); + DocumentInputStream dis = new DocumentInputStream(dsiEntry); + PropertySet ps = new PropertySet(dis); + dis.close(); + dsi = new DocumentSummaryInformation(ps); +} +catch (FileNotFoundException ex) +{ + /* There is no document summary information. We have to create a + * new one. */ + dsi = PropertySetFactory.newDocumentSummaryInformation(); +} + + +

In the source code above the statement

+ + DirectoryEntry dir = poifs.getRoot(); + +

gets hold of the POI filesystem's root directory as a + DirectoryEntry. The getEntry() method of this + class is used to access a file or directory entry in a directory. However, + if the file to be opened does not exist, a + FileNotFoundException will be thrown. Therefore opening the + document summary information entry should be done in a try + block:

+ + DocumentEntry dsiEntry = (DocumentEntry) + dir.getEntry(DocumentSummaryInformation.DEFAULT_STREAM_NAME); + +

DocumentSummaryInformation.DEFAULT_STREAM_NAME represents + the string "\005DocumentSummaryInformation", i.e. the standard name of a + document summary information stream. If this stream exists, the + getEntry() method returns a DocumentEntry. To + read the DocumentEntry's contents, create a + DocumentInputStream:

+ + DocumentInputStream dis = new DocumentInputStream(dsiEntry); + +

Up to this point we have used POI's POIFS component. Now HPSF enters the + stage. A property set is created from the input stream's data:

+ + PropertySet ps = new PropertySet(dis); + dis.close(); + dsi = new DocumentSummaryInformation(ps); + +

If the data really constitutes a property set, a + PropertySet object is created. Otherwise a + NoPropertySetStreamException is thrown. After having read the + data from the input stream the latter should be closed.

+ +

Since we know - or at least hope - that the stream named + "\005DocumentSummaryInformation" is not just any property set but really + contains the document summary information, we try to create a new + DocumentSummaryInformation from the property set. If the + stream is not document summary information stream the sample application + fails with a UnexpectedPropertySetTypeException.

+ +

If the POI document does not contain a document summary information + stream, we can create a new one in the catch clause. The + PropertySetFactory's method + newDocumentSummaryInformation() establishes a new and empty + DocumentSummaryInformation instance:

+ + dsi = PropertySetFactory.newDocumentSummaryInformation(); + +

Whether we read the document summary information from the POI filesystem + or created it from scratch, in either case we now have a + DocumentSummaryInformation instance we can write to. Writing + is quite simple, as the following line of code shows:

+ + dsi.setCategory("POI example"); + +

This statement sets the "category" property to "POI example". Any + former "category" value will be lost. If there hasn't been a "category" + property yet, a new one will be created.

+ +

DocumentSummaryInformation of course has methods to set the + other standard properties, too - look into the API documentation to see + all of them.

+ +

Once all properties are set as needed, they should be stored into the + file on disk. The first step is to write the + DocumentSummaryInformation into the POI filesystem:

+ + dsi.write(dir, DocumentSummaryInformation.DEFAULT_STREAM_NAME); + +

The DocumentSummaryInformation's write() + method takes two parameters: The first is the DirectoryEntry + in the POI filesystem, the second is the name of the stream to create in + the directory. If this stream already exists, it will be overwritten.

+ + If you not only modified the document summary information but also + the summary information you have to write both of them to the POI + filesystem. + +

Still the POI filesystem is a data structure in memory only and must be + written to a disk file to make it permanent. The following lines write + back the POI filesystem to the file it was read from before. Please note + that in production-quality code you should never write directly to the + origin file, because in case of an error everything would be lost. Here it + is done this way to keep the example short.

+ + OutputStream out = new FileOutputStream(poiFilesystem); +poifs.writeFilesystem(out); +out.close(); + +
User-Defined Properties + +

If you compare the source code excerpts above with the file containing + the full source code, you will notice that I left out some following + lines of code. The are dealing with the special topic of custom + properties.

+ + DocumentSummaryInformation dsi = ... +... +CustomProperties customProperties = dsi.getCustomProperties(); +if (customProperties == null) + customProperties = new CustomProperties(); + +/* Insert some custom properties into the container. */ +customProperties.put("Key 1", "Value 1"); +customProperties.put("Schlüssel 2", "Wert 2"); +customProperties.put("Sample Number", new Integer(12345)); +customProperties.put("Sample Boolean", new Boolean(true)); +customProperties.put("Sample Date", new Date()); + +/* Read a custom property. */ +Object value = customProperties.get("Sample Number"); + +/* Write the custom properties back to the document summary + * information. */ +dsi.setCustomProperties(customProperties); + +

Custom properties are properties the user can define himself. Using for + example Microsoft Word he can define these extra properties and give + each of them a name, a type and a + value. The custom properties are stored in the document + information summary along with the standard properties.

+ +

The source code example shows how to retrieve the custom properties + as a whole from a DocumentSummaryInformation instance using + the getCustomProperties() method. The result is a + CustomProperties instance or null if no + user-defined properties exist.

+ +

Since CustomProperties implements the Map + interface you can read and write properties with the usual + Map methods. However, CustomProperties poses + some restrictions on the types of keys and values.

+ +
    +
  • The key is a string.
    • +
  • The value is one of String, + Boolean, Long, Integer, + Short, or java.util.Date.
    • +
+ +

The CustomProperties class has been designed for easy + access using just keys and values. The underlying Microsoft-specific + custom properties data structure is more complicated. However, it does + not provide noteworthy additional benefits. It is possible to have + multiple properties with the same name or properties without a + name at all. When reading custom properties from a document summary + information stream, the CustomProperties class ignores + properties without a name and keeps only the "last" (whatever that means) + of those properties having the same name. You can find out whether a + CustomProperties instance dropped any properties with the + isPure() method.

+ +

You can read and write the full spectrum of custom properties with + HPSF's low-level methods. They are explained in the next section.

+
+
+ + + + +
Reading Non-Standard Properties + + This section tells how to read non-standard properties. Non-standard + properties are application-specific ID/type/value triples. + +
Overview +

Now comes the real hardcode stuff. As mentioned above, + SummaryInformation and + DocumentSummaryInformation are just special cases of the + general concept of a property set. This concept says that a + property set consists of properties and that each + property is an entity with an ID, a + type, and a value.

+ +

Okay, that was still rather easy. However, to make things more + complicated, Microsoft in its infinite wisdom decided that a property set + shalt be broken into one or more sections. Each section + holds a bunch of properties. But since that's still not complicated + enough, a section may have an optional dictionary that + maps property IDs to property names - we'll explain + later what that means.

+ +

The procedure to get to the properties is the following:

+ +
    +
  1. Use the PropertySetFactory class to + create a PropertySet object from a property set stream. If + you don't know whether an input stream is a property set stream, just + try to call PropertySetFactory.create(java.io.InputStream): + You'll either get a PropertySet instance returned or an + exception is thrown.
    2. + +
  2. Call the PropertySet's method getSections() + to get the sections contained in the property set. Each section is + an instance of the Section class.
    3. + +
  3. Each section has a format ID. The format ID of the first section in a + property set determines the property set's type. For example, the first + (and only) section of the summary information property set has a format + ID of F29F85E0-4FF9-1068-AB-91-08-00-2B-27-B3-D9. You can + get the format ID with Section.getFormatID().
    4. + +
  4. The properties contained in a Section can be retrieved + with Section.getProperties(). The result is an array of + Property instances.
    5. + +
  5. A property has a name, a type, and a value. The Property + class has methods to retrieve them.
    6. +
+
+ +
A Sample Application +

Let's have a look at a sample Java application that dumps all property + set streams contained in a POI file system. The full source code of this + program can be found as ReadCustomPropertySets.java in the + examples area of the POI source code tree. Here are the key + sections:

+ + import java.io.*; +import java.util.*; +import org.apache.poi.hpsf.*; +import org.apache.poi.poifs.eventfilesystem.*; +import org.apache.poi.util.HexDump; + +

The most important package the application needs is + org.apache.poi.hpsf.*. This package contains the HPSF + classes. Most classes named below are from the HPSF package. Of course we + also need the POIFS event file system's classes and java.io.* + since we are dealing with POI I/O. From the java.util package + we use the List and Iterator class. The class + org.apache.poi.util.HexDump provides a methods to dump byte + arrays as nicely formatted strings.

+ + public static void main(String[] args) + throws IOException +{ + final String filename = args[0]; + POIFSReader r = new POIFSReader(); + + /* Register a listener for *all* documents. */ + r.registerListener(new MyPOIFSReaderListener()); + r.read(new FileInputStream(filename)); +} + +

The POIFSReader is set up in a way that the listener + MyPOIFSReaderListener is called on every file in the POI file + system.

+
+ +
The Property Set +

The listener class tries to create a PropertySet from each + stream using the PropertySetFactory.create() method:

+ + static class MyPOIFSReaderListener implements POIFSReaderListener +{ + public void processPOIFSReaderEvent(POIFSReaderEvent event) + { + PropertySet ps = null; + try + { + ps = PropertySetFactory.create(event.getStream()); + } + catch (NoPropertySetStreamException ex) + { + out("No property set stream: \"" + event.getPath() + + event.getName() + "\""); + return; + } + catch (Exception ex) + { + throw new RuntimeException + ("Property set stream \"" + + event.getPath() + event.getName() + "\": " + ex); + } + + /* Print the name of the property set stream: */ + out("Property set stream \"" + event.getPath() + + event.getName() + "\":"); + +

Creating the PropertySet is done in a try + block, because not each stream in the POI file system contains a property + set. If it is some other file, the + PropertySetFactory.create() throws a + NoPropertySetStreamException, which is caught and + logged. Then the program continues with the next stream. However, all + other types of exceptions cause the program to terminate by throwing a + runtime exception. If all went well, we can print the name of the property + set stream.

+
+ +
The Sections +

The next step is to print the number of sections followed by the + sections themselves:

+ + /* Print the number of sections: */ +final long sectionCount = ps.getSectionCount(); +out(" No. of sections: " + sectionCount); + +/* Print the list of sections: */ +List sections = ps.getSections(); +int nr = 0; +for (Iterator i = sections.iterator(); i.hasNext();) +{ + /* Print a single section: */ + Section sec = (Section) i.next(); + + // See below for the complete loop body. +} + +

The PropertySet's method getSectionCount() + returns the number of sections.

+ +

To retrieve the sections, use the getSections() + method. This method returns a java.util.List containing + instances of the Section class in their proper order.

+ +

The sample code shows a loop that retrieves the Section + objects one by one and prints some information about each one. Here is + the complete body of the loop:

+ + /* Print a single section: */ +Section sec = (Section) i.next(); +out(" Section " + nr++ + ":"); +String s = hex(sec.getFormatID().getBytes()); +s = s.substring(0, s.length() - 1); +out(" Format ID: " + s); + +/* Print the number of properties in this section. */ +int propertyCount = sec.getPropertyCount(); +out(" No. of properties: " + propertyCount); + +/* Print the properties: */ +Property[] properties = sec.getProperties(); +for (int i2 = 0; i2 < properties.length; i2++) +{ + /* Print a single property: */ + Property p = properties[i2]; + int id = p.getID(); + long type = p.getType(); + Object value = p.getValue(); + out(" Property ID: " + id + ", type: " + type + + ", value: " + value); +} +
+ +
The Section's Format ID +

The first method called on the Section instance is + getFormatID(). As explained above, the format ID of the + first section in a property set determines the type of the property + set. Its type is ClassID which is essentially a sequence of + 16 bytes. A real application using its own type of a custom property set + should have defined a unique format ID and, when reading a property set + stream, should check the format ID is equal to that unique format ID. The + sample program just prints the format ID it finds in a section:

+ + String s = hex(sec.getFormatID().getBytes()); +s = s.substring(0, s.length() - 1); +out(" Format ID: " + s); + +

As you can see, the getFormatID() method returns a + ClassID object. An array containing the bytes can be + retrieved with ClassID.getBytes(). In order to get a nicely + formatted printout, the sample program uses the hex() helper + method which in turn uses the POI utility class HexDump in + the org.apache.poi.util package. Another helper method is + out() which just saves typing + System.out.println().

+
+ +
The Properties +

Before getting the properties, it is possible to find out how many + properties are available in the section via the + Section.getPropertyCount(). The sample application uses this + method to print the number of properties to the standard output:

+ + int propertyCount = sec.getPropertyCount(); +out(" No. of properties: " + propertyCount); + +

Now its time to get to the properties themselves. You can retrieve a + section's properties with the method + Section.getProperties():

+ + Property[] properties = sec.getProperties(); + +

As you can see the result is an array of Property + objects. This class has three methods to retrieve a property's ID, its + type, and its value. The following code snippet shows how to call + them:

+ + for (int i2 = 0; i2 < properties.length; i2++) +{ + /* Print a single property: */ + Property p = properties[i2]; + int id = p.getID(); + long type = p.getType(); + Object value = p.getValue(); + out(" Property ID: " + id + ", type: " + type + + ", value: " + value); +} +
+ +
Sample Output +

The output of the sample program might look like the following. It + shows the summary information and the document summary information + property sets of a Microsoft Word document. However, unlike the first and + second section of this HOW-TO the application does not have any code + which is specific to the SummaryInformation and + DocumentSummaryInformation classes.

+ + Property set stream "/SummaryInformation": + No. of sections: 1 + Section 0: + Format ID: 00000000 F2 9F 85 E0 4F F9 10 68 AB 91 08 00 2B 27 B3 D9 ....O..h....+'.. + No. of properties: 17 + Property ID: 1, type: 2, value: 1252 + Property ID: 2, type: 30, value: Titel + Property ID: 3, type: 30, value: Thema + Property ID: 4, type: 30, value: Rainer Klute (Autor) + Property ID: 5, type: 30, value: Test (Stichwörter) + Property ID: 6, type: 30, value: This is a document for testing HPSF + Property ID: 7, type: 30, value: Normal.dot + Property ID: 8, type: 30, value: Unknown User + Property ID: 9, type: 30, value: 3 + Property ID: 18, type: 30, value: Microsoft Word 9.0 + Property ID: 12, type: 64, value: Mon Jan 01 00:59:25 CET 1601 + Property ID: 13, type: 64, value: Thu Jul 18 16:22:00 CEST 2002 + Property ID: 14, type: 3, value: 1 + Property ID: 15, type: 3, value: 20 + Property ID: 16, type: 3, value: 93 + Property ID: 19, type: 3, value: 0 + Property ID: 17, type: 71, value: [B@13582d +Property set stream "/DocumentSummaryInformation": + No. of sections: 2 + Section 0: + Format ID: 00000000 D5 CD D5 02 2E 9C 10 1B 93 97 08 00 2B 2C F9 AE ............+,.. + No. of properties: 14 + Property ID: 1, type: 2, value: 1252 + Property ID: 2, type: 30, value: Test + Property ID: 14, type: 30, value: Rainer Klute (Manager) + Property ID: 15, type: 30, value: Rainer Klute IT-Consulting GmbH + Property ID: 5, type: 3, value: 3 + Property ID: 6, type: 3, value: 2 + Property ID: 17, type: 3, value: 111 + Property ID: 23, type: 3, value: 592636 + Property ID: 11, type: 11, value: false + Property ID: 16, type: 11, value: false + Property ID: 19, type: 11, value: false + Property ID: 22, type: 11, value: false + Property ID: 13, type: 4126, value: [B@56a499 + Property ID: 12, type: 4108, value: [B@506411 + Section 1: + Format ID: 00000000 D5 CD D5 05 2E 9C 10 1B 93 97 08 00 2B 2C F9 AE ............+,.. + No. of properties: 7 + Property ID: 0, type: 0, value: {6=Test-JaNein, 5=Test-Zahl, 4=Test-Datum, 3=Test-Text, 2=_PID_LINKBASE} + Property ID: 1, type: 2, value: 1252 + Property ID: 2, type: 65, value: [B@c9ba38 + Property ID: 3, type: 30, value: This is some text. + Property ID: 4, type: 64, value: Wed Jul 17 00:00:00 CEST 2002 + Property ID: 5, type: 3, value: 27 + Property ID: 6, type: 11, value: true +No property set stream: "/WordDocument" +No property set stream: "/CompObj" +No property set stream: "/1Table" + +

There are some interesting items to note:

+ +
    +
  • The first property set (summary information) consists of a single + section, the second property set (document summary information) consists + of two sections.
    • + +
  • Each section type (identified by its format ID) has its own domain of + property ID. For example, in the second property set the properties with + ID 2 have different meanings in the two section. By the way, the format + IDs of these sections are not equal, but you have to + look hard to find the difference.
    • + +
  • The properties are not in any particular order in the section, + although they slightly tend to be sorted by their IDs.
    • +
+
+ +
Property IDs +

Properties in the same section are distinguished by their IDs. This is + similar to variables in a programming language like Java, which are + distinguished by their names. But unlike variable names, property IDs are + simple integral numbers. There is another similarity, however. Just like + a Java variable has a certain scope (e.g. a member variables in a class), + a property ID also has its scope of validity: the section.

+ +

Two property IDs in sections with different section format IDs + don't have the same meaning even though their IDs might be equal. For + example, ID 4 in the first (and only) section of a summary + information property set denotes the document's author, while ID 4 in the + first section of the document summary information property set means the + document's byte count. The sample output above does not show a property + with an ID of 4 in the first section of the document summary information + property set. That means that the document does not have a byte + count. However, there is a property with an ID of 4 in the + second section: This is a user-defined property ID - we'll get + to that topic in a minute.

+ +

So, how can you find out what the meaning of a certain property ID in + the summary information and the document summary information property set + is? The standard property sets as such don't have any hints about the + meanings of their property IDs. For example, the summary + information property set does not tell you that the property ID 4 stands + for the document's author. This is external knowledge. Microsoft defined + standard meanings for some of the property IDs in the summary information + and the document summary information property sets. As a help to the Java + and POI programmer, the class PropertyIDMap in the + org.apache.poi.hpsf.wellknown package defines constants + for the "well-known" property IDs. For example, there is the + definition

+ + public final static int PID_AUTHOR = 4; + +

These definitions allow you to use symbolic names instead of + numbers.

+ +

In order to provide support for the other way, too, - i.e. to map + property IDs to property names - the class PropertyIDMap + defines two static methods: + getSummaryInformationProperties() and + getDocumentSummaryInformationProperties(). Both return + java.util.Map objects which map property IDs to + strings. Such a string gives a hint about the property's meaning. For + example, + PropertyIDMap.getSummaryInformationProperties().get(4) + returns the string "PID_AUTHOR". An application could use this string as + a key to a localized string which is displayed to the user, e.g. "Author" + in English or "Verfasser" in German. HPSF might provide such + language-dependend ("localized") mappings in a later release.

+ +

Usually you won't have to deal with those two maps. Instead you should + call the Section.getPIDString(int) method. It returns the + string associated with the specified property ID in the context of the + Section object.

+ +

Above you learned that property IDs have a meaning in the scope of a + section only. However, there are two exceptions to the rule: The property + IDs 0 and 1 have a fixed meaning in all sections:

+ + + + + + + + + + + + + + + + +
Property IDMeaning
0The property's value is a dictionary, i.e. a + mapping from property IDs to strings.
1The property's value is the number of a codepage, + i.e. a mapping from character codes to characters. All strings in the + section containing this property must be interpreted using this + codepage. Typical property values are 1252 (8-bit "western" characters, + ISO-8859-1), 1200 (16-bit Unicode characters, UFT-16), or 65001 (8-bit + Unicode characters, UFT-8).
+
+ +
Property types +

A property is nothing without its value. It is stored in a property set + stream as a sequence of bytes. You must know the property's + type in order to properly interpret those bytes and + reasonably handle the value. A property's type is one of the so-called + Microsoft-defined "variant types". When you call + Property.getType() you'll get a long value + which denoting the property's variant type. The class + Variant in the org.apache.poi.hpsf package + holds most of those long values as named constants. For + example, the constant VT_I4 = 3 means a signed integer value + of four bytes. Examples of other types are VT_LPSTR = 30 + meaning a null-terminated string of 8-bit characters, VT_LPWSTR = + 31 which means a null-terminated Unicode string, or VT_BOOL + = 11 denoting a boolean value.

+ +

In most cases you won't need a property's type because HPSF does all + the work for you.

+
+ +
Property values +

When an application wants to retrieve a property's value and calls + Property.getValue(), HPSF has to interpret the bytes making + out the value according to the property's type. The type determines how + many bytes the value consists of and what + to do with them. For example, if the type is VT_I4, HPSF + knows that the value is four bytes long and that these bytes + comprise a signed integer value in the little-endian format. This is + quite different from e.g. a type of VT_LPWSTR. In this case + HPSF has to scan the value bytes for a Unicode null character and collect + everything from the beginning to that null character as a Unicode + string.

+ +

The good new is that HPSF does another job for you, too: It maps the + variant type to an adequate Java type.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Variant type:Java type:
VT_I2java.lang.Integer
VT_I4java.lang.Long
VT_FILETIMEjava.util.Date
VT_LPSTRjava.lang.String
VT_LPWSTRjava.lang.String
VT_CFbyte[]
VT_BOOLjava.lang.Boolean
+ +

The bad news is that there are still a couple of variant types HPSF + does not yet support. If it encounters one of these types it + returns the property's value as a byte array and leaves it to be + interpreted by the application.

+ +

An application retrieves a property's value by calling the + Property.getValue() method. This method's return type is the + abstract Object class. The getValue() method + looks up the property's variant type, reads the property's value bytes, + creates an instance of an adequate Java type, assigns it the property's + value and returns it. Primitive types like int or + long will be returned as the corresponding class, + e.g. Integer or Long.

+
+ + +
Dictionaries +

The property with ID 0 has a very special meaning: It is a + dictionary mapping property IDs to property names. We + have seen already that the meanings of standard properties in the + summary information and the document summary information property sets + have been defined by Microsoft. The advantage is that the labels of + properties like "Author" or "Title" don't have to be stored in the + property set. However, a user can define custom fields in, say, Microsoft + Word. For each field the user has to specify a name, a type, and a + value.

+ +

The names of the custom-defined fields (i.e. the property names) are + stored in the document summary information second section's + dictionary. The dictionary is a map which associates + property IDs with property names.

+ +

The method Section.getPIDString(int) not only returns with + the well-known property names of the summary information and document + summary information property sets, but with self-defined properties, + too. It should also work with self-defined properties in self-defined + sections.

+
+ +
Codepage support + +

The property with ID 1 holds the number of the codepage which was used + to encode the strings in this section. If this property is not available + in a section, the platform's default character encoding will be + used. This works fine as long as the document being read has been written + on a platform with the same default character encoding. However, if you + receive a document from another region of the world and the codepage is + undefined, you are in trouble.

+ +

HPSF's codepage support is only as good as the character encoding + support of the Java Virtual Machine (JVM) the application runs on. If + HPSF encounters a codepage number it assumes that the JVM has a character + encoding with a corresponding name. For example, if the codepage is 1252, + HPSF uses the character encoding "cp1252" to read or write strings. If + the JVM does not have that character encoding installed or if the + codepage number is illegal, an UnsupportedEncodingException will be + thrown. This works quite well with Java 2 Standard Edition (J2SE) + versions since 1.4. However, under J2SE 1.3 or lower you are out of + luck. You should install a newer J2SE version to process codepages with + HPSF.

+ +

There are some exceptions to the rule saying that a character + encoding's name is derived from the codepage number by prepending the + string "cp" to it. In these cases the codepage number is mapped to a + well-known character encoding name. Here are a few examples:

+ +
+
Codepage 932
+
is mapped to the character encoding "SJIS".
+
Codepage 1200
+
is mapped to the character encoding "UTF-16".
+
Codepage 65001
+
is mapped to the character encoding "UTF-8".
+
+ +

More of these mappings between codepage and character encoding name are + hard-coded in the classes org.apache.poi.hpsf.Constants and + org.apache.poi.hpsf.VariantSupport. Probably there will be a + need to add more mappings. The HPSF author will appreciate any hints.

+
+
+ + +
Writing Properties + + This section describes how to write properties. + +
Overview of Writing Properties +

Writing properties is possible at a high level and at a low level:

+ +
    + +
  • Most users will want to create or change entries in the summary + information or document summary information streams.
    • + +
  • On the low level, there are no convenience classes or methods. You + have to deal with things like property IDs and variant types to write + properties. Therefore you should have read section + 3 to understand the description of the low-level writing + functions.
    • +
+ +

HPSF's writing capabilities come with the classes + MutablePropertySet, MutableSection, + MutableProperty, and some helper classes. The "mutable" + classes extend their respective superclasses PropertySet, + Section, and Property and provide "set" and + "write" methods, following the Decorator + pattern.

+
+ + +
Low-Level Writing: An Overview +

When you are going to write a property set stream your application has + to perform the following steps:

+ +
    +
  1. Create a MutablePropertySet instance.
    2. + +
  2. Get hold of a MutableSection. You can either retrieve + the one that is always present in a new MutablePropertySet, + or you have to create a new MutableSection and add it to + the MutablePropertySet. +
    3. + +
  3. Set any Section fields as you like.
    4. + +
  4. Create as many MutableProperty objects as you need. Set + each property's ID, type, and value. Add the + MutableProperty objects to the + MutableSection. +
    5. + +
  5. Create further MutableSections if you need them.
    6. + +
  6. Eventually retrieve the property set as a byte stream using + MutablePropertySet.toInputStream() and write it to a POIFS + document.
    7. +
+
+ +
Low-level Writing Functions In Details +

Writing properties is introduced by an artificial but simple example: a + program creating a new document (aka POI file system) which contains only + a single document: a summary information property set stream. The latter + will hold the document's title only. This is artificial in that it does + not contain any Word, Excel or other kind of useful application document + data. A document containing just a property set is without any practical + use. However, it is perfectly fine for an example because it make it very + simple and easy to understand, and you will get used to writing + properties in real applications quickly.

+ +

The application expects the name of the POI file system to be written + on the command line. The title property it writes is "Sample title".

+ +

Here's the application's source code. You can also find it in the + "examples" section of the POI source code distribution. Explanations are + following below.

+ + package org.apache.poi.hpsf.examples; + +import java.io.FileOutputStream; +import java.io.IOException; +import java.io.InputStream; + +import org.apache.poi.hpsf.MutableProperty; +import org.apache.poi.hpsf.MutablePropertySet; +import org.apache.poi.hpsf.MutableSection; +import org.apache.poi.hpsf.SummaryInformation; +import org.apache.poi.hpsf.Variant; +import org.apache.poi.hpsf.WritingNotSupportedException; +import org.apache.poi.hpsf.wellknown.PropertyIDMap; +import org.apache.poi.hpsf.wellknown.SectionIDMap; +import org.apache.poi.poifs.filesystem.POIFSFileSystem; + +/** + * <p>This class is a simple sample application showing how to create a property + * set and write it to disk.</p> + * + * @author Rainer Klute + * @since 2003-09-12 + */ +public class WriteTitle +{ + /** + * <p>Runs the example program.</p> + * + * @param args Command-line arguments. The first and only command-line + * argument is the name of the POI file system to create. + * @throws IOException if any I/O exception occurs. + * @throws WritingNotSupportedException if HPSF does not (yet) support + * writing a certain property type. + */ + public static void main(final String[] args) + throws WritingNotSupportedException, IOException + { + /* Check whether we have exactly one command-line argument. */ + if (args.length != 1) + { + System.err.println("Usage: " + WriteTitle.class.getName() + + "destinationPOIFS"); + System.exit(1); + } + + final String fileName = args[0]; + + /* Create a mutable property set. Initially it contains a single section + * with no properties. */ + final MutablePropertySet mps = new MutablePropertySet(); + + /* Retrieve the section the property set already contains. */ + final MutableSection ms = (MutableSection) mps.getSections().get(0); + + /* Turn the property set into a summary information property. This is + * done by setting the format ID of its first section to + * SectionIDMap.SUMMARY_INFORMATION_ID. */ + ms.setFormatID(SectionIDMap.SUMMARY_INFORMATION_ID); + + /* Create an empty property. */ + final MutableProperty p = new MutableProperty(); + + /* Fill the property with appropriate settings so that it specifies the + * document's title. */ + p.setID(PropertyIDMap.PID_TITLE); + p.setType(Variant.VT_LPWSTR); + p.setValue("Sample title"); + + /* Place the property into the section. */ + ms.setProperty(p); + + /* Create the POI file system the property set is to be written to. */ + final POIFSFileSystem poiFs = new POIFSFileSystem(); + + /* For writing the property set into a POI file system it has to be + * handed over to the POIFS.createDocument() method as an input stream + * which produces the bytes making out the property set stream. */ + final InputStream is = mps.toInputStream(); + + /* Create the summary information property set in the POI file + * system. It is given the default name most (if not all) summary + * information property sets have. */ + poiFs.createDocument(is, SummaryInformation.DEFAULT_STREAM_NAME); + + /* Write the whole POI file system to a disk file. */ + poiFs.writeFilesystem(new FileOutputStream(fileName)); + } + +} + +

The application first checks that there is exactly one single argument + on the command line: the name of the file to write. If this single + argument is present, the application stores it in the + fileName variable. It will be used in the end when the POI + file system is written to a disk file.

+ + if (args.length != 1) +{ + System.err.println("Usage: " + WriteTitle.class.getName() + + "destinationPOIFS"); + System.exit(1); +} +final String fileName = args[0]; + +

Let's create a property set now. We cannot use the + PropertySet class, because it is read-only. It does not have + a constructor creating an empty property set, and it does not have any + methods to modify its contents, i.e. to write sections containing + properties into it.

+ +

The class to use is MutablePropertySet. It is a subclass + of PropertySet. The sample application calls its no-args + constructor in order to establish an empty property set:

+ + final MutablePropertySet mps = new MutablePropertySet(); + +

As said, we have an empty property set now. Later we will put some + contents into it.

+ +

By the way, the MutablePropertySet class has another + constructor taking a PropertySet as parameter. It creates a + mutable deep copy of the property set given to it.

+ +

The MutablePropertySet created by the no-args constructor + is not really empty: It contains a single section without properties. We + can either retrieve that section and fill it with properties or we can + replace it by another section. We can also add further sections to the + property set. The sample application decides to retrieve the section + being already there:

+ + final MutableSection ms = (MutableSection) mps.getSections().get(0); + +

The getSections() method returns the property set's + sections as a list, i.e. an instance of + java.util.List. Calling get(0) returns the + list's first (or zeroth, if you prefer) element. The Section + returned is a MutableSection: a subclass of + Section you can modify.

+ +

The alternative to retrieving the MutableSection being + already there would have been to create an new + MutableSection like this:

+ + MutableSection s = new MutableSection(); + +

There is also a constructor which takes a Section as + parameter and creates a mutable deep copy of it.

+ +

The MutableSection the sample application retrieved from + the MutablePropertySet is still empty. It contains no + properties and does not have a format ID. As you have read above the format ID of the first section in a + property set determines the property set's type. Since our property set + should become a SummaryInformation property set we have to set the format + ID of its first (and only) section to + F29F85E0-4FF9-1068-AB-91-08-00-2B-27-B3-D9. However, you + won't have to remember that ID: HPSF has it defined as the well-known + constant SectionIDMap.SUMMARY_INFORMATION_ID. The sample + application writes it to the section using the + setFormatID(byte[]) method:

+ + ms.setFormatID(SectionIDMap.SUMMARY_INFORMATION_ID); + +

Now it is time to create a property. As you might expect there is a + subclass of Property called + MutableProperty with a no-args constructor:

+ + final MutableProperty p = new MutableProperty(); + +

A MutableProperty object must have an ID, a type, and a + value (see above for details). The class + provides methods to set these attributes:

+ + p.setID(PropertyIDMap.PID_TITLE); +p.setType(Variant.VT_LPWSTR); +p.setValue("Sample title"); + +

The MutableProperty class has a constructor which you can + use to pass in all three attributes in a single call. See the Javadoc API + documentation for details!

+ +

The sample property set is complete now. We have a + MutablePropertySet containing a MutableSection + containing a MutableProperty. Of course we could have added + more sections to the property set and more properties to the sections but + we wanted to keep things simple.

+ +

The property set has to be written to a POI file system. The following + statement creates it.

+ + final POIFSFileSystem poiFs = new POIFSFileSystem(); + +

Writing the property set includes the step of converting it into a + sequence of bytes. The MutablePropertySet class has the + method toInputStream() for this purpose. It returns the + bytes making out the property set stream as an + InputStream:

+ + final InputStream is = mps.toInputStream(); + +

If you'd read from this input stream you'd receive all the property + set's bytes. However, it is very likely that you'll never do + that. Instead you'll pass the input stream to the + POIFSFileSystem.createDocument() method, like this:

+ + poiFs.createDocument(is, SummaryInformation.DEFAULT_STREAM_NAME); + +

Besides the InputStream createDocument() + takes a second parameter: the name of the document to be created. For a + SummaryInformation property set stream the default name is available as + the constant SummaryInformation.DEFAULT_STREAM_NAME.

+ +

The last step is to write the POI file system to a disk file:

+ + poiFs.writeFilesystem(new FileOutputStream(fileName)); +
+
+ + + +
Further Reading +

There are still some aspects of HSPF left which are not covered by this + HOW-TO. You should dig into the Javadoc API documentation to learn + further details. Since you've struggled through this document up to this + point, you are well prepared.

+
+ +
+ + + + diff --git a/src/documentation/content/xdocs/hpsf/index.xml b/src/documentation/content/xdocs/hpsf/index.xml new file mode 100644 index 0000000000..97754d25bb --- /dev/null +++ b/src/documentation/content/xdocs/hpsf/index.xml @@ -0,0 +1,74 @@ + + + + + +
+ Apache POI - HPSF - Java API to Handle Microsoft Format Document + Properties + Overview + + + +
+ +
Overview + +

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 property set + streams. A property set stream is a separate document within a + POI filesystem. We'll call property + set streams mostly just "property sets". HPSF is POI's pure-Java + implementation to read and write property sets.

+ +

The HPSF HOWTO 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.

+ +

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 HPSF description + describes the internal structure of property set streams. A separate + document explains the internal of thumbnail + images.

+
+ + + + diff --git a/src/documentation/content/xdocs/hpsf/internals.xml b/src/documentation/content/xdocs/hpsf/internals.xml new file mode 100644 index 0000000000..c97003c8f6 --- /dev/null +++ b/src/documentation/content/xdocs/hpsf/internals.xml @@ -0,0 +1,1081 @@ + + + + + +
+ Apache POI - HPSF Internals + + + +
+ +
HPSF Internals + +
Introduction + +

A Microsoft Office document is internally organized like a filesystem + with directory and files. Microsoft calls these files + streams. A document can have properties attached to it, + like author, title, number of words etc. These metadata are not stored in + the main stream of, say, a Word document, but instead in a dedicated + stream with a special format. Usually this stream's name is + \005SummaryInformation, where \005 represents + the character with a decimal value of 5.

+ +

A single piece of information in the stream is called a + property, for example the document title. Each property + has an integral ID (e.g. 2 for title), a + type (telling that the title is a string of bytes) and a + value (what this is should be obvious). A stream + containing properties is called a + property set stream.

+ +

This document describes the internal structure of a property set stream, + i.e. the HPSF. It does + not describe how a Microsoft Office document is organized internally and + how to retrieve a stream from it. See the POIFS documentation for that kind of + stuff.

+ +

The HPSF is not only used in the Summary + Information stream in the top-level document of a Microsoft Office + document. Often there is also a property set stream named + \005DocumentSummaryInformation with additional properties. + Embedded documents may have their own property set streams. You cannot + tell by a stream's name whether it is a property set stream or not. + Instead you have to open the stream and look at its bytes.

+
+ + + +
Data Types + +

Before delving into the details of the property set stream format we + have to have a short look at data types. Integral values are stored in the + so-called little endian format. In this format the bytes + that make out an integral value are stored in the "wrong" order. For + example, the decimal value 4660 is 0x1234 in the hexadecimal notation. If + you think this should be represented by a byte 0x12 followed by another + byte 0x34, you are right. This is called the big endian + format. In the little endian format, however, this order is reversed and + the low-value byte comes first: 0x3412. +

+ +

The following table gives an overview about some important data + types:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameLengthExample (Big Endian)Example (Little Endian)
Bytes1 byte0x120x12
Word2 bytes0x12340x3412
DWord4 bytes0x123456780x78563412
ClassID
+ A sequence of one DWord, two Words and eight Bytes		16 bytes0xE0859FF2F94F6810AB9108002B27B3D9 resp. + E0859FF2-F94F-6810-AB-91-08-00-2B-27-B3-D90xF29F85E04FF91068AB9108002B27B3D9 resp. + F29F85E0-4FF9-1068-AB-91-08-00-2B-27-B3-D9
The ClassID examples are given here in two different notations. The + second notation without the "0x" at the beginning and with dashes + inside shows the internal grouping into one DWord, two Words and eight + Bytes.Watch out: Microsoft documentation and tools show class IDs + a little bit differently like + F29F85E0-4FF9-1068-AB91-08002B27B3D9. + However, that representation is (intentionally?) misleading with + respect to endianess.
+
+ + + +
HPSF Overview + +

A property set stream consists of three main parts:

+ +
    +
  1. The header and
    2. +
  2. the section(s) containing the properties.
    3. +
+
+ + + +
The Header + +

The first bytes in a property set stream is the header. + It has a fixed length and looks like this:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
OffsetTypeContentsRemarks
0Word0xFFFEIf the first four bytes of a stream do not contain these values, the + stream is not a property set stream.
2Word0x0000
4DWordDenotes the operating system and the OS version under which this + stream was created. The operating system ID is in the DWord's higher + word (after little endian decoding): 0x0000 for Win16, + 0x0001 for Macintosh and 0x0002 for Win32 - + that's all. The reader is most likely aware of the fact that there are + some more operating systems. However, Microsoft does not seem to + know.
8ClassID0x00000000000000000000000000000000Most property set streams have this value but this is not + required.
24DWord0x01000000 or greaterSection count. This field's value should be equal to 1 or greater. + Microsoft claims that this is a "reserved" field, but it seems to tell + how many sections (see below) are following in the stream. This would + really make sense because otherwise you could not know where and how + far you should read section data.
+
+ + + +
Section List + +

Following the header is the section list. This is an array of pairs each + consisting of a section format ID and an offset. This array has as many + pairs of ClassID and and DWord fields as the section count field in the + header says. The Summary Information stream contains a single section, the + Document Summary Information stream contains two.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TypeContentsRemarks
ClassIDSection format ID0xF29F85E04FF91068AB9108002B27B3D9 for the single section + in the Summary Information stream.

+ + 0xD5CDD5022E9C101B939708002B2CF9AE for the first + section in the Document Summary Information stream.
DWordOffsetThe number of bytes between the beginning of the stream and the + beginning of the section within the stream.
ClassIDSection format ID...
DWordOffset...
.........
+
+ + + +
Section + +

A section is divided into three parts: the section header (with the + section length and the number of properties in the section), the + properties list (with type and offset of each property), and the + properties themselves. Here are the details:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
 TypeContentsRemarks
Section headerDWordLengthThe length of the section in bytes.
DWordProperty countThe number of properties in the section.
Properties listDWordProperty IDThe property ID tells what the property means. For example, an ID of + 0x0002 in the Summary Information stands for the document's + title. See the Property IDs + chapter below for more details.
DWordOffsetThe number of bytes between the beginning of the section and the + property.
.........
PropertiesDWordProperty type ("variant")This is the property's data type, e.g. an integer value, a byte + string or a Unicode string. See the + Property Types chapter + for details!
Field length depends on the property type + ("variant")Property valueThis field's length depends on the property's type. These are the + bytes that make out the DWord, the byte string or some other data of + fixed or variable length.

+ + The property value's length is always stored in an area which is a + multiple of 4 in length. If the property is shorter, e.g. a byte + string of 13 bytes, the remaining bytes are padded with 0x00 + bytes.
.........
+
+ + + +
Property IDs + + +

As seen above, a section holds a property list: an array with property + IDs and offsets. The property ID gives each property a meaning. For + example, in the Summary Information stream the property ID 2 says that + this property is the document's title.

+ +

If you want to know a property ID's meaning, it is not sufficient to + know the ID itself. You must also know the + section format ID. For example, in the Document Summary + Information stream the property ID 2 means not the document's title but + its category. Due to Microsoft's infinite wisdom the section format ID is + not part of the section. Thus if you have only a section without the + stream it is in, you cannot make any sense of the properties because you + do not know what they mean.

+ +

So each section format ID has its own name space of property IDs. + Microsoft defined some "well-known" property IDs for the Summary + Information and the Document Summary Information streams. You can extend + them by your own additional IDs. This will be described below.

+ +
Property IDs in The Summary Information Stream + +

The Summary Information stream has a single section with a section + format ID of 0xF29F85E04FF91068AB9108002B27B3D9. The following + table defines the meaning of its property IDs. Each row associates a + property ID with a name and an ID string. (The property + type is just for informational purposes given here. As we have + seen above, the type is always given along with the value.)

+ +

The property name is a readable string which could be + displayed to the user. However, this string is useful only for users who + understand English. The property name does not help with other + languages.

+ +

The property ID string is about the same but looks more + technically and is nothing a user should bother with. You could the ID + string and map it to an appropriate display string in a particular + language. Of course you could do that with the property ID as well and + with less overhead, but people (including software developers) tend to be + better in remembering symbolic constants than remembering numbers.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Property IDProperty NameProperty ID StringProperty Type
2TitlePID_TITLEVT_LPSTR
3SubjectPID_SUBJECTVT_LPSTR
4AuthorPID_AUTHORVT_LPSTR
5KeywordsPID_KEYWORDSVT_LPSTR
6CommentsPID_COMMENTSVT_LPSTR
7TemplatePID_TEMPLATEVT_LPSTR
8Last Saved ByPID_LASTAUTHORVT_LPSTR
9Revision NumberPID_REVNUMBERVT_LPSTR
10Total Editing TimePID_EDITTIMEVT_FILETIME
11Last PrintedPID_LASTPRINTEDVT_FILETIME
12Create Time/DatePID_CREATE_DTMVT_FILETIME
13Last Saved Time/DatePID_LASTSAVE_DTMVT_FILETIME
14Number of PagesPID_PAGECOUNTVT_I4
15Number of WordsPID_WORDCOUNTVT_I4
16Number of CharactersPID_CHARCOUNTVT_I4
17ThumbnailPID_THUMBNAILVT_CF
18Name of Creating ApplicationPID_APPNAMEVT_LPSTR
19SecurityPID_SECURITYVT_I4
+
+ + + +
Property IDs in The Document Summary Information Stream + +

The Document Summary Information stream has two sections with a section + format ID of 0xD5CDD5022E9C101B939708002B2CF9AE for the first + one. The following table defines the meaning of the property IDs in the + first section. See the preceeding section for interpreting the table.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Property IDProperty nameProperty ID stringVT type
0DictionaryPID_DICTIONARY[Special format]
1Code pagePID_CODEPAGEVT_I2
2CategoryPID_CATEGORYVT_LPSTR
3PresentationTargetPID_PRESFORMATVT_LPSTR
4BytesPID_BYTECOUNTVT_I4
5LinesPID_LINECOUNTVT_I4
6ParagraphsPID_PARCOUNTVT_I4
7SlidesPID_SLIDECOUNTVT_I4
8NotesPID_NOTECOUNTVT_I4
9HiddenSlidesPID_HIDDENCOUNTVT_I4
10MMClipsPID_MMCLIPCOUNTVT_I4
11ScaleCropPID_SCALEVT_BOOL
12HeadingPairsPID_HEADINGPAIRVT_VARIANT | VT_VECTOR
13TitlesofPartsPID_DOCPARTSVT_LPSTR | VT_VECTOR
14ManagerPID_MANAGERVT_LPSTR
15CompanyPID_COMPANYVT_LPSTR
16LinksUpTo DatePID_LINKSDIRTYVT_BOOL
+
+
+ + + +
Property Types + + +

A property consists of a DWord type field followed by the + property value. The property type is an integer value and tells how the + data byte following it are to be interpreted. In the Microsoft world it is + also known as the variant.

+ +

The Usage column says where a variant type may occur. Not all + of them are allowed in a property set but just those marked with a [P]. + [V] - may appear in a VARIANT, [T] - may + appear in a TYPEDESC, [P] - may appear in an OLE property + set, [S] - may appear in a Safe Array.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Variant IDVariant TypeUsageDescription
0VT_EMPTY[V] [P]nothing
1VT_NULL[V] [P]SQL style Null
2VT_I2[V] [T] [P] [S]2 byte signed int
3VT_I4[V] [T] [P] [S]4 byte signed int
4VT_R4[V] [T] [P] [S]4 byte real
5VT_R8[V] [T] [P] [S]8 byte real
6VT_CY[V] [T] [P] [S]currency
7VT_DATE[V] [T] [P] [S]date
8VT_BSTR[V] [T] [P] [S]OLE Automation string
9VT_DISPATCH[V] [T] [P] [S]IDispatch *
10VT_ERROR[V] [T] [S]SCODE
11VT_BOOL[V] [T] [P] [S]True=-1, False=0
12VT_VARIANT[V] [T] [P] [S]VARIANT *
13VT_UNKNOWN[V] [T] [S]IUnknown *
14VT_DECIMAL[V] [T] [S]16 byte fixed point
16VT_I1[T]signed char
17VT_UI1[V] [T] [P] [S]unsigned char
18VT_UI2[T] [P]unsigned short
19VT_UI4[T] [P]unsigned short
20VT_I8[T] [P]signed 64-bit int
21VT_UI8[T] [P]unsigned 64-bit int
22VT_INT[T]signed machine int
23VT_UINT[T]unsigned machine int
24VT_VOID[T]C style void
25VT_HRESULT[T]Standard return type
26VT_PTR[T]pointer type
27VT_SAFEARRAY[T](use VT_ARRAY in VARIANT)
28VT_CARRAY[T]C style array
29VT_USERDEFINED[T]user defined type
30VT_LPSTR[T] [P]null terminated string
31VT_LPWSTR[T] [P]wide null terminated string
64VT_FILETIME[P]FILETIME
65VT_BLOB[P]Length prefixed bytes
66VT_STREAM[P]Name of the stream follows
67VT_STORAGE[P]Name of the storage follows
68VT_STREAMED_OBJECT[P]Stream contains an object
69VT_STORED_OBJECT[P]Storage contains an object
70VT_BLOB_OBJECT[P]Blob contains an object
71VT_CF[P]Clipboard format
72VT_CLSID[P]A Class ID
0x1000VT_VECTOR[P]simple counted array
0x2000VT_ARRAY[V]SAFEARRAY*
0x4000VT_BYREF[V]void* for local use
0x8000VT_RESERVED

0xFFFFVT_ILLEGAL

0xFFFVT_ILLEGALMASKED

0xFFFVT_TYPEMASK

+
+ + + +
+ The Dictionary + +

What a dictionary is good for is explained in the HPSF HOW-TO. This chapter explains how it is + organized internally.

+ +

The dictionary has a simple header consisting of a single UInt value. It + tells how many entries the dictionary comprises:

+ + + + + + + + + + + + +
NameData typeDescription
nrEntriesUIntNumber of dictionary entries
+ +

The dictionary entries follow the header. Each one looks like this:

+ + + + + + + + + + + + + + + + + + + + + + +
NameData typeDescription
keyUIntThe unique number of this property, i.e. the PID
lengthUIntThe length of the property name associated with the key
valueStringThe property's name, terminated with a 0x00 character
+ +

The entries are not aligned, i.e. each one follows its predecessor + without any gap or fill characters.

+
+ + + +
References + +

In order to assemble the HPSF description I used information publically + available on the Internet only. The references given below have been very + helpful. If you have any amendments or corrections, please let us know! + Thank you!

+ +
    + +
  1. In + Understanding OLE + documents, Ken Kyler gives an introduction to OLE2 + documents and especially to property sets. He names the property names, + types, and IDs of the Summary Information and Document Summary + Information stream.
    2. + +
  2. The ActiveX + Programmer's Reference at http://www.dwam.net/docs/oleref/ + seems a little outdated, but that's what I have found.
    3. + +
  3. An overview of the VT_ types is in + Variant + Type Definitions.
    4. + +
  4. What is a FILETIME? The answer can be found + under , http://www.vbapi.com/ref/f/filetime.html or + http://www.cs.rpi.edu/courses/fall01/os/FILETIME.html. + In short: The FILETIME structure holds a date and time associated + with a file. The structure identifies a 64-bit integer specifying the + number of 100-nanosecond intervals which have passed since January 1, + 1601. This 64-bit value is split into the two dwords stored in the + structure.
    5. + +
  5. Microsoft provides some public information in the MSDN + Library. Use the search function to try to find what you are + looking for, e.g. "codepage" or "document summary information" etc.
    6. + +
  6. This documentation origins from the HPSF description available at http://www.rainer-klute.de/~klute/Software/poibrowser/doc/HPSF-Description.html.
    7. +
+
+
+ + + + diff --git a/src/documentation/content/xdocs/hpsf/thumbnails.xml b/src/documentation/content/xdocs/hpsf/thumbnails.xml new file mode 100644 index 0000000000..8b676c04f8 --- /dev/null +++ b/src/documentation/content/xdocs/hpsf/thumbnails.xml @@ -0,0 +1,199 @@ + + + + + +
+ HPSF THUMBNAIL HOW-TO + + + +
+ +
The VT_CF Format + +

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.

+ +

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.

+ +

The VT_CF structure looks like this:

+ + + + + + + + + + + + + + +
Element:Clipboard SizeClipboard Format TagClipboard Data
Size:32 bit unsigned integer (DWord)32 bit signed integer (DWord)variable length (byte array)
+ +

The Clipboard Size refers to the size (in bytes) of Clipboard Data + (variable size) plus the Clipboard Format (four bytes).

+ +

Clipboard Format Tag has four possible values:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + +
ValueIdentifierDescription
-1LCFTAG_WINDOWSa built-in Windows© clipboard format value
-2LCFTAG_MACINTOSHa Macintosh clipboard format value
-3LCFTAG_FMTIDa format identifier (FMTID) This is rarely used.
0LCFTAG_NODATANo data This is rarely used.
+
+ + + +
Windows Clipboard Data + +

Windows clipboard data has four image formats for thumbnails:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + +
ValueIdentifierDescription
3CF_METAFILEPICTWindows metafile format - recommended
8CF_DIBDevice Independent Bitmap
14CF_ENHMETAFILEEnhanced Windows metafile format
2CF_BITMAPBitmap - Obsolete - Use CF_DIB instead
+
+ +
Windows Metafile Format + +

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.

+ +

The Clipboard Data byte array looks like this when an image is stored in + Windows' Clipboard WMF format.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
IdentifierCF_METAFILEPICTmmwidthheighthandleWMF data
Size32 bit unsigned int16 bit unsigned(?) int16 bit unsigned(?) int16 bit unsigned(?) int16 bit unsigned(?) intbyte array - variable length
DescriptionClipboard WMFMapping ModeImage WidthImage Heighthandle to the WMF data array in memory, or 0standard WMF byte stream
+
+ + +
Device Independent Bitmap +

FIXME: Describe the Device Independent Bitmap + format!

+
+ + + +
Macintosh Clipboard Data +

FIXME: Describe the Macintosh clipboard formats!

+
+ + + + + diff --git a/src/documentation/content/xdocs/hpsf/todo.xml b/src/documentation/content/xdocs/hpsf/todo.xml new file mode 100644 index 0000000000..90a15bfe30 --- /dev/null +++ b/src/documentation/content/xdocs/hpsf/todo.xml @@ -0,0 +1,77 @@ + + + + + +
+ To Do + + + +
+ +
To Do + +

The following functionalities should be added to HPFS:

+ +
    +
  1. + Improve writing support! We need convenience classes and methods for + easily writing summary information streams and document summary + information streams. +
    2. +
  2. + Add resource bundles to + org.apache.poi.hpsf.wellknown 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. +
    3. +
  3. + Implement reading functionality for those property types that are not + yet supported. HPSF should return proper Java types instead of just byte + arrays. +
    4. +
  4. + Add WMF to java.awt.Image example code in the Thumbnail HOW-TO. +
    5. +
+
+ + + + diff --git a/src/documentation/content/xdocs/hsmf/book.xml b/src/documentation/content/xdocs/hsmf/book.xml new file mode 100644 index 0000000000..a6cc4c761c --- /dev/null +++ b/src/documentation/content/xdocs/hsmf/book.xml @@ -0,0 +1,34 @@ + + + + + + + + + + + + + + + diff --git a/src/documentation/content/xdocs/hsmf/index.xml b/src/documentation/content/xdocs/hsmf/index.xml new file mode 100644 index 0000000000..de2c06e497 --- /dev/null +++ b/src/documentation/content/xdocs/hsmf/index.xml @@ -0,0 +1,55 @@ + + + + + +
+ POI-HSMF - Java API To Access Microsoft Outlook MSG Files + Overview + + + + +
+ + +
+ Overview + +

HSMF is the POI Project's pure Java implementation of the Outlook MSG format.

+

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

+

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 + HSMF examples area + of SVN. You may also wish to look at the unit tests for more use guides.

+ + + This code currently lives the + scratchpad area + 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. + +
+ + diff --git a/src/documentation/content/xdocs/hwpf/book.xml b/src/documentation/content/xdocs/hwpf/book.xml new file mode 100644 index 0000000000..05eac510f0 --- /dev/null +++ b/src/documentation/content/xdocs/hwpf/book.xml @@ -0,0 +1,31 @@ + + + + + + + + + + + + + + diff --git a/src/documentation/content/xdocs/hwpf/docoverview.xml b/src/documentation/content/xdocs/hwpf/docoverview.xml new file mode 100644 index 0000000000..ac3afc50aa --- /dev/null +++ b/src/documentation/content/xdocs/hwpf/docoverview.xml @@ -0,0 +1,113 @@ + + + + + +
+ Apache POI - HWPF - Java API to Handle Microsoft Word Files + Word File Format + + + +
+ + +
The Word 97 File Format in semi-plain English + +

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

+

The OLE file format is not discussed in this document. It is assumed that + the reader has a working knowledge of the POIFS API.

+ +
Word file structure +

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.

+
+
Reading Word files +

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.

+
Text +

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.

+

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.

+
+
Text Formatting +
Stylesheet +

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.

+

Eventually, you have to chain back to the nil style which is an + imaginary style with certain implied values.

+
+
Paragraph and Character styles +

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.

+

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.

+

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.

+
+
Uncompressing styles and other data structures +

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.

+
+
+
+
+ + + diff --git a/src/documentation/content/xdocs/hwpf/index.xml b/src/documentation/content/xdocs/hwpf/index.xml new file mode 100644 index 0000000000..38bdb5896f --- /dev/null +++ b/src/documentation/content/xdocs/hwpf/index.xml @@ -0,0 +1,200 @@ + + + + + +
+ Apache POI - HWPF - Java API to Handle Microsoft Word Files + Overview + + + + + + +
+ + +
Overview + +

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.

+ +

The partner to HWPF for the new Word 2007 .docx format is XWPF. + Whilst HWPF and XWPF provide similar features, there is not a common + interface across the two of them at this time.

+ +

HWPF is still in early development. It is in the + scratchpad section of the SVN. You will need to ensure you + either have a recent SVN checkout, or a recent SVN nightly build + (including the scratchpad jar!)

+ +

+ Source code in the + org.apache.poi.hdf + tree is the old legacy code. Source in the + org.apache.poi.hwpf.model + 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 + org.apache.poi.hwpf.usermodel + package is actual public and user-friendly (as much as possible) API to access document + parts. Source code in the + org.apache.poi.hwpf.extractor + tree is a wrapper of this to facilitate easy extraction of interesting things (eg the Text), + and + org.apache.poi.hwpf.converter + package contains Word-to-HTML and Word-to-FO converters (latest can be used to generate PDF + from Word files when using with + Apache FOP + ). Also there is a small file-structure-dumping utility in + org.apache.poi.hwpf.dev + package, primally for developing purposes. +

+ +

+ The main entry point to HWPF is HWPFDocument. Currently it has a lot of references both to + internal interfaces ( + org.apache.poi.hwpf.model + package) and public API ( + org.apache.poi.hwpf.usermodel + ) package. It is possible that it will be split into two different interfaces (like WordFile + and WordDocument) in later versions. +

+ +

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

+ +

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

+ +
+
+ XWPF Patches Required! + +

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.

+ +

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 "Contribution to POI" page.

+
+ +
+ HWPF Pointman Needed! + +

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.

+ +

If you 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 overview. Full details on the word format + is available from + Microsoft, + but the documentation can be a little hard to get into at first... Try reading the + overview first, and looking at the existing + code, then finally look up the documentation for specific missing features.

+ +

As a first step you should familiarize yourself with the source code, + examples, test cases, and the HWPF patches available at Bugzilla (if any). Then you + should compile an overview of

+ +
    +
  • the current HWPF status,
    • +
  • the patches in Bugzilla to be checked + in (and those that should better be ditched),
    • +
  • the available test cases and the test cases still to be written,
    • +
  • the available documentation and the docs to be written,
    • +
  • anything else that seems reasonable
    • +
+ +

When you start coding, you will not yet have write access to the + SVN repository. Please submit your patches to Bugzilla and nag the dev list 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!

+ +

Please do not forget to write JUnit 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 "Contribution to POI" page + for more details and help getting started.

+ +

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!

+
+ + + + diff --git a/src/documentation/content/xdocs/hwpf/projectplan.xml b/src/documentation/content/xdocs/hwpf/projectplan.xml new file mode 100644 index 0000000000..913d49a2c8 --- /dev/null +++ b/src/documentation/content/xdocs/hwpf/projectplan.xml @@ -0,0 +1,392 @@ + + + + + +
+ Apache POI - HWPF - Java API to Handle Microsoft Word Files + Project Plan + + + +
+ +

HWPF Milestones

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ Milestones + + Target Date + + Owner +
+ 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 + + 07/11/2003 + + Ryan +
+ Add support for Lists and +Tables + + 8/15/2003 + +   +
+ HWPF 1.0-alpha release with +documentation and examples + + 8/18/2003 + + Praveen/Ryan +
+ Add support for Headers, +Footers, endnotes, and +footnotes + + 8/31/2003 + + ? +
+ Add support for forms and +mail merge + + September/October 2003 + + ? +
+

HWPF Task Lists

+

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

+ + + + + + + + + + + + + + + + + + + + + +
+ Task + + Target Date + + Owner +
+ Create classes to read and +write low level data +structures with test cases + + 7/10/2003 + + Ryan +
+ Create classes to read and +write FontTable and Font +names with test case + + 7/10/2003 + + Praveen +
+ Final test + + 7/11/2003 + + Ryan +
+

Develop user friendly API so it is fun and easy to read and write word documents +with java.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ Task + + Target Date + + Owner +
+ Develop a way for SPRMS to +be compressed and +uncompressed + + + + +
+ Override CHPAbstractType +with a concrete class that +exposes attributes with +human readable names + + + + +
+ Override PAPAbstractType +with a concrete class that +exposes attributes with +human readable names + + + + +
+ Override SEPAbstractType +with a concrete class that +exposes attributes with +human readable names + + + + +
+ Override DOPAbstractType +with a concrete class that +exposes attributes with +human readable names + + + + +
+ Override TAPAbstractType +with a concrete class that +exposes attributes with +human readable names + + + + +
+ Override TCAbstractType +with a concrete class that +exposes attributes with +human readable names + + + + +
+ Develop a VerifyIntegrity +class for testing so it is easy +to determine if a Word +Document is well-formed. + + + + +
+ Develop general intuitive +API to tie everything together + + + + +
+

Add support for lists and tables

+ + + + + + + + + + + + + + + + +
+ Task + + Target Date + + Owner +
+ Add data structures for +reading and writing list data +with test cases. + + + + +
+ Add data structures for +reading and writing tables +with test cases. + + + + +
+

HWPF 1.0-alpha release with documentation and examples

+ + + + + + + + + + + + + + + + + + + + + +
+ Task + + Target Date + + Owner +
+ Document the user model +API + + + + +
+ Document the low level +classes + + + + +
+ Come up with detailed How-To’s + + + + +
+ + diff --git a/src/documentation/content/xdocs/hwpf/quick-guide.xml b/src/documentation/content/xdocs/hwpf/quick-guide.xml new file mode 100644 index 0000000000..d717b0ef09 --- /dev/null +++ b/src/documentation/content/xdocs/hwpf/quick-guide.xml @@ -0,0 +1,88 @@ + + + + + +
+ POI-HWPF - A Quick Guide + Overview + + + +
+ + +

HWPF is still in early development. It is in the + scratchpad section of the SVN. You will need to ensure you + either have a recent SVN checkout, or a recent SVN nightly build + (including the scratchpad jar!)

+ +
Basic Text Extraction +

For basic text extraction, make use of +org.apache.poi.hwpf.extractor.WordExtractor. It accepts an input +stream or a HWPFDocument. The getText() +method can be used to +get the text from all the paragraphs, or getParagraphText() +can be used to fetch the text from each paragraph in turn. The other +option is getTextFromPieces(), which is very fast, but +tends to return things that aren't text from the page. YMMV. +

+
+ +
Specific Text Extraction +

To get specific bits of text, first create a +org.apache.poi.hwpf.HWPFDocument. Fetch the range +with getRange(), then get paragraphs from that. You +can then get text and other properties. +

+
+ +
Headers and Footers +

To get at the headers and footers of a word document, first create a +org.apache.poi.hwpf.HWPFDocument. Next, you need to create a +org.apache.poi.hwpf.usermodel.HeaderStores, 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.

+
+ +
Changing Text +

It is possible to change the text via + insertBefore() and insertAfter() + on a Range object (either a Range, + Paragraph or CharacterRun). + It is also possible to delete a Range. + This code will work in many, but not all cases, and patches to + improve it are gratefully received! +

+
+ +
Further Examples +

For now, the best source of additional examples is in the unit + tests. + Browse the HWPF unit tests. +

+
+ + diff --git a/src/documentation/content/xdocs/index.xml b/src/documentation/content/xdocs/index.xml new file mode 100644 index 0000000000..9bcee8147d --- /dev/null +++ b/src/documentation/content/xdocs/index.xml @@ -0,0 +1,176 @@ + + + + + +
+ Apache POI - the Java API for Microsoft Documents + + + + + + + +
+ + +
Project News +
19 September 2013 - POI 3.10 Beta 2 available +

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

+

A full list of changes is available in the change log. + People interested should also follow the dev mailing list to track further progress.

+

See the downloads page for more details.

+
+
3 December 2012 - POI 3.9 available +

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 + release notes for more details. +

+

A full list of changes is available in the change log. + People interested should also follow the dev mailing list to track further progress.

+

See the downloads page for more details.

+
+
28 August 2011 - The Apache POI project is celebrating its 10th anniversary +

+ 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. + Read more...

+
+
+ +
Mission Statement +

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

+

+ 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 OLE2 Filesystem (POIFS) and + OLE2 Document Properties (HPSF). +

+

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

+

+ 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 Excel workbooks (SS=HSSF+XSSF). + Work is progressing for Word documents (HWPF+XWPF) and + PowerPoint presentations (HSLF+XSLF). +

+

+ The project has recently added support for Outlook (HSMF). Microsoft opened the specifications + to this format in October 2007. We would welcome contributions. +

+

+ There are also projects for + Visio (HDGF), + TNEF (HMEF), + and Publisher (HPBF). +

+

+ As a general policy we collaborate as much as possible with other projects to + provide this functionality. Examples include: Cocoon for + which there are serializers for HSSF; + Open Office.org with whom we collaborate in documenting the + XLS format; and Tika / + Lucene, + for which we provide format interpretors. When practical, we donate + components directly to those projects for POI-enabling them. +

+
Why should I use Apache POI? +

+ A major use of the Apache POI api is for Text Extraction applications + such as web spiders, index builders, and content management systems. +

+

+ So why should you use POIFS, HSSF or XSSF? +

+

+ 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! +

+

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

+
+
Components +

+ The Apache POI Project provides several component modules some of which may not be of interest to you. + Use the information on our Components page to determine which + jar files to include in your classpath. +

+
+
+ +
Contributing +

+ 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 + Subversion Repository, build the code, + join the mailing lists and we'll be happy to help you get started on the project! +

+

+ Please read our Contribution Guidelines. When your contribution is ready + submit a patch to our Bug Database. +

+ + +
+ +
+ + Copyright (c) @year@ The Apache Software Foundation. All rights reserved. +
+ Apache POI, POI, Apache, the Apache feather logo, and the Apache + POI project logo are trademarks of The Apache Software Foundation. + +
+ + + diff --git a/src/documentation/content/xdocs/legal.xml b/src/documentation/content/xdocs/legal.xml new file mode 100644 index 0000000000..0c106726f1 --- /dev/null +++ b/src/documentation/content/xdocs/legal.xml @@ -0,0 +1,100 @@ + + + + + +
+ Apache POI - Legal Stuff + + + + +
+ + +
License and Notice +

+ Apache POI releases are available under the Apache License, Version 2.0. + See the NOTICE file contained in each release artifact for applicable copyright attribution notices. Release artifacts are available + from the Download page. +

+
+
Copyrights and Trademarks +

+All material on this website is Copyright © 2002-2010, The Apache +Software Foundation. +

+

+Apache POI, POI, Apache, the Apache feather logo, and the Apache POI +project logo are trademarks of The Apache Software Foundation. +

+

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

+
Cryptography Notice +

+ 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 + http://www.wassenaar.org/ + for more information. +

+ +

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

+ +

+ The cryptographic software used is from java.security and + javax.crypto and is used when processing encrypted and + protected documents. +

+
+
+ +
+ + Copyright (c) @year@ The Apache Software Foundation All rights reserved. +
+ Apache POI, POI, Apache, the Apache feather logo, and the Apache + POI project logo are trademarks of The Apache Software Foundation. + +
+ diff --git a/src/documentation/content/xdocs/mailinglists.xml b/src/documentation/content/xdocs/mailinglists.xml new file mode 100644 index 0000000000..78e09b4b41 --- /dev/null +++ b/src/documentation/content/xdocs/mailinglists.xml @@ -0,0 +1,99 @@ + + + + + +
+ Mailing Lists + + + +
+ + +
Mailing Lists - Guidelines +

+ Before subscribing to any of the mailing lists, please make + sure that you have read and understand the following + guidelines: +

+
    +
  • ASF guide to Mailing Lists
    • +
  • ASF Tips for email contributors
    • +
  • The Jakarta guide to Mailing Lists
    • +
+
+
Lists +
The POI User List +

+ Medium Traffic + Subscribe + Unsubscribe + Archive + gmane.org +

+

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

+
+
The POI Developer List +

+ Low Traffic + Subscribe + Unsubscribe + Archive + gmane.org +

+

+ 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. + Do not send mail to this list with usage questions or + configuration problems. +

+
+
The POI General List +

+ Low Traffic + Subscribe + Unsubscribe + Archive +

+

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

+
+
+ +
+ + Copyright (c) @year@ The Apache Software Foundation. All rights reserved. +
+ Apache POI, POI, Apache, the Apache feather logo, and the Apache + POI project logo are trademarks of The Apache Software Foundation. + +
+ diff --git a/src/documentation/content/xdocs/mirrors.xml b/src/documentation/content/xdocs/mirrors.xml new file mode 100644 index 0000000000..13fe902c51 --- /dev/null +++ b/src/documentation/content/xdocs/mirrors.xml @@ -0,0 +1,57 @@ + + + + + +
+ Apache POI Mirror Site + + + +
+ + +
Mirrors +

+ These are mirrors of the + POI website. + If you know of others...report them! :-) +

+
+
Austria +
    +
  • Austrian Mirror of Jakarta POI
    • +
+
+
Korea +
    +
  • Jakarta site partially translated into Korean and Mirrored
    • +
+
+ +
+ + Copyright (c) @year@ The Apache Software Foundation All rights reserved. +
+ Apache POI, POI, Apache, the Apache feather logo, and the Apache + POI project logo are trademarks of The Apache Software Foundation. + +
+ diff --git a/src/documentation/content/xdocs/news.xml b/src/documentation/content/xdocs/news.xml new file mode 100644 index 0000000000..ffd7b5723f --- /dev/null +++ b/src/documentation/content/xdocs/news.xml @@ -0,0 +1,233 @@ + + + + + +
+ Apache POI - In the News over the world + + + + +
+ + +
POI in the news +

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

+
+
English +
    +
  • + Discussion about using POI on AS/400s +
    • +
  • + Discussion from back when we almost had POI as the filter for KOffice if politics and licenses hadn't killed iit +
    • +
  • + Java discussion on O'Reilly Network including discussion about POI - O'Reilly.net +
    • +
  • + Poor Obfuscation Implementation. - Blog of David M. Johnson +
    • +
  • + + POI 1.5-dev-rc2 released - JSurfer +
    • + +
  • + Google says we're the most important in our category +
    • +
  • + It's POI-fect - Tony Sintes, Javaworld +
    • +
  • + + Nicola announces POI serialization code + - Matthew Langham's Radio Weblog +
    • +
  • + + Jakarta POI 1.4583 Released - JavaLobby +
    • +
  • + + POI project moves to Jakarta (OLE 2 CDF/Excel/Word in + pure java) - JavaLobby +
    • +
  • + + List of Java libraries to read and write image and document files + 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! +
    • +
  • + + The Experiences of an Operator (Måns af Klercker) + - radio.weblogs.com +
    • +
  • + + DATACONV - Data Conversion Tools: Office + DATACONV +
    • +
  • + + Chicago Developer Page + +
    • +
  • + + POI/POI Serialization Project + - Man you know you've hit the bigtime when + O'Reilly Likes you.. ;-) +
    • +
  • + + News Around the Net + - Java World +
    • + +
+
+
Nederlandstalige (Dutch) +
    +
  • + + Een Excel-werkboek maken vanuit Java - Lieven Smits + +
    • +
+
+
Deutsch (German) +
    +
  • Apache POI verffentlicht - entwicker.com +
    • +
  • + + Apache Jakarta-Projekt bringt Word und Excel in die Java-Welt - jsp-develop.de (for the misguided who use JSP ;-) ) +
    • +
  • + + Neues Apache-Projekt bringt Word- und Excel nach Java + - entwickler.com +
    • +
+
+
Español (Spanish) +
    +
  • + + OLE2 desde Java nativo + - javaHispano +
    • +
  • + Spanish discussion about Excel and Java including POI from Wrox forums +
    • +
+
+
Français (French) +
    +
  • + + Excel/OLE accessibles + - Da Linux French Page +
    • +
  • + Discussion on POI in French +
    • +
+
+
Nihongo (Japanese) +
    +
  • + 100% PureJava... - Dr. Panda Portal +
    • +
  • + + What's new with java? + - gimlay.org +
    • +
  • Java de Excel - How to use Japanese with POI
    • +
  • Various discussion in Japanese including on POI
    • +
  • Japanese resources on Jakarta projects including POI
    • +
  • Kishida's site -- Weekly Forte Lectures -- includes a snip about POI and Japanese.
    • + +
+
+
Russkii Yazyk (Russian) +
    +
  • + + Probably a translation of the Javalobby announcement of 1.5-final + -- Computer News (What's New) +
    • +
+
+
Hangul (Korean) +
    +
  • + Various discussion in Korean about Excel output/APIs including POI +
    • +
+
+
No freaking idea +

+ If you can read one of these languages, send mail to the list + telling us what language it is and we'll categorize it! +

+
    +
  • + + If I had to guess, I'd say this is Thai, but + maybe you actually know - javacentrix.com +
    • +
+
+ +
+ + Copyright (c) @year@ The Apache Software Foundation All rights reserved. +
+ Apache POI, POI, Apache, the Apache feather logo, and the Apache + POI project logo are trademarks of The Apache Software Foundation. + +
+ diff --git a/src/documentation/content/xdocs/news/book.xml b/src/documentation/content/xdocs/news/book.xml new file mode 100644 index 0000000000..dc26164fe7 --- /dev/null +++ b/src/documentation/content/xdocs/news/book.xml @@ -0,0 +1,37 @@ + + + + + + + + + + + + + + + + + + diff --git a/src/documentation/content/xdocs/news/logocontest.xml b/src/documentation/content/xdocs/news/logocontest.xml new file mode 100644 index 0000000000..15503daaba --- /dev/null +++ b/src/documentation/content/xdocs/news/logocontest.xml @@ -0,0 +1,194 @@ + + + + + +
+ + + + + +
+ + +
POI logos +

+ Here are the current logo submissions. Thanks to the artists! +

+
Michael Mosmann +

+ logo +

+
+
Loïc Lefèvre +

+ logo    + logo +

+
+
Glen Stampoultzis +

+ logo +

+
+
Marcus Gustafsson +

+ logo    + logo +

+
+
Adrianus Handoyo +

+ logo    + logo    + logo +

+
+
RussellBeattie +

+ logo    + logo    + logo +

+

+ logo    + logo +

+
+
Daniel Fernandez +

+ logo +

+
+
Andrew Clements +

+ logo    + logo +

+
+
Wendy Wise +

+ logo    + logo +

+
+
Nikhil Karmokar +

+ logo    + logo +

+

+ logo    + logo +

+

+ logo    + logo +

+

+ logo    + logo +

+

+ logo    + logo +

+

+ logo    + logo +

+
+
Lieven Janssen +

+ logo    + logo +

+
+
RaPi GmbH +

+ Contact Person: Fancy at: fancy at my-feiqi.com +

+

+ logo    + logo +

+

+ logo +

+

+ logo +

+

+ logo +

+

+ logo +

+

+ logo +

+

+ logo +

+

+ logo +

+

+ logo +

+
+
Randy Stanard +

+ logo +

+

+ logo +

+

+ logo +

+

+ logo +

+

+ logo +

+

+ logo +

+

+ logo +

+

+ logo +

+
+
+ +
+ + Copyright (c) @year@ The Apache Software Foundation All rights reserved. +
+ Apache POI, POI, Apache, the Apache feather logo, and the Apache + POI project logo are trademarks of The Apache Software Foundation. + +
+ diff --git a/src/documentation/content/xdocs/overview.xml b/src/documentation/content/xdocs/overview.xml new file mode 100644 index 0000000000..6caec2239f --- /dev/null +++ b/src/documentation/content/xdocs/overview.xml @@ -0,0 +1,351 @@ + + + + + +
+ Apache POI - Component Overview + + + + + +
+ +
Apache POI Project Components +
POIFS for OLE 2 Documents +

+ POIFS is the oldest and most stable part of the project. It is our port of the OLE 2 Compound Document Format to + pure Java. It supports both read and write functionality. All of our components ultimately rely on it by + definition. Please see the POIFS project page for more information. +

+
+
HSSF and XSSF for Excel Documents +

+ 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 + the HSSF+XSSF project page for more + information. +

+
+
HWPF and XWPF for Word Documents +

+ 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 the HWPF project page for more + information. This component remains in early stages of + development. It can already read and write simple files. +

+

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

+
+
HSLF and XSLF for PowerPoint Documents +

+ HSLF is our port of the Microsoft PowerPoint 97(-2003) file format to pure + Java. It supports read and write capabilities. Please see the HSLF project page for more + information. +

+

+ We are also working on the XSLF for the PresentationML (2007+) format from the + OOXML specification. +

+
+
HPSF for OLE 2 Document Properties +

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

+

+ HPSF supports both reading and writing of properties. +

+

+ Please see the HPSF project + page for more information. +

+
+
HDGF for Visio Documents +

+ 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 the HDGF project page for more + information. +

+
+
HPBF for Publisher Documents +

+ 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 the HPBF project page for more + information. +

+
+
HMEF for TNEF (winmail.dat) Outlook Attachments +

+ 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 the HMEF project page for more + information. +

+
+
HSMF for Outlook Messages +

+ 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 the HPBF project page for more + information. +

+

+ Microsoft has recently added the Outlook file format to its OSP. More information + is now available making implementation of this API an easier task. +

+
+
+
What is it? +

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

+

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! + ECMA-376 standard is here, + and is also under the Microsoft OSP. +

+
+
Component Map +

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

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ComponentApplication typeMaven artifactIdNotes
POIFSOLE2 FilesystempoiRequired to work with OLE2 / POIFS based files
HPSFOLE2 Property Setspoi 
HSSFExcel XLSpoiFor HSSF only, if common SS is needed see below
HSLFPowerPoint PPTpoi-scratchpad 
HWPFWord DOCpoi-scratchpad 
HDGFVisio VSDpoi-scratchpad 
HPBFPublisher PUBpoi-scratchpad 
HSMFOutlook MSGpoi-scratchpad 
OpenXML4JOOXMLpoi-ooxml plus one of
poi-ooxml-schemas, ooxml-schemas		Only one schemas jar is needed, see below for differences
XSSFExcel XLSXpoi-ooxml 
XSLFPowerPoint PPTXpoi-ooxml 
XWPFWord DOCXpoi-ooxml 
Common SSExcel XLS and XLSXpoi-ooxmlWorkbookFactory and friends all require poi-ooxml, not just core poi
+ +


+ +

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

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Maven artifactIdPrerequisitesJAR
poicommons-logging, commons-codec, log4jpoi-version-yyyymmdd.jar
poi-scratchpadpoipoi-scratchpad-version-yyyymmdd.jar
poi-ooxmlpoi, poi-ooxml-schemas, dom4jpoi-ooxml-version-yyyymmdd.jar
poi-ooxml-schemasxmlbeans, stax-api-1.0.1poi-ooxml-schemas-version-yyyymmdd.jar
poi-examplespoi, poi-scratchpad, poi-ooxmlpoi-examples-version-yyyymmdd.jar
ooxml-schemasxmlbeans, stax-api-1.0.1ooxml-schemas-1.1.jar
+ +

 

+

+ 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 normally + only required for development +

+

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

+
+
Examples +

+ Small sample programs using the POI API are available in the + src/examples directory of the source distribution. Before + studying the source code you might want to have a look at the + "Examples" section of the POI API + documentation. +

+
POI Browser +

+ 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 POI + source code. +

+
+

+ All of the examples are inclided in POI distributions as a poi-examples artifact. +

+
+
Contributed Software +

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

+

+ See POI Ruby Bindings and other code in the + poi-contrib module +

+
+ +
+ + Copyright (c) @year@ The Apache Software Foundation. All rights reserved. +
+ Apache POI, POI, Apache, the Apache feather logo, and the Apache + POI project logo are trademarks of The Apache Software Foundation. + +
+ diff --git a/src/documentation/content/xdocs/oxml4j/book.xml b/src/documentation/content/xdocs/oxml4j/book.xml new file mode 100644 index 0000000000..b28bbdd4cc --- /dev/null +++ b/src/documentation/content/xdocs/oxml4j/book.xml @@ -0,0 +1,34 @@ + + + + + + + + + + + + + + + diff --git a/src/documentation/content/xdocs/oxml4j/index.xml b/src/documentation/content/xdocs/oxml4j/index.xml new file mode 100644 index 0000000000..a64fa63ab4 --- /dev/null +++ b/src/documentation/content/xdocs/oxml4j/index.xml @@ -0,0 +1,42 @@ + + + + + +
+ POI-OpenXML4J - Java API To Access Office Open XML documents + Overview +
+ + +
+ Overview +

OpenXML4J is the POI Project's pure Java implementation of the Open Packaging Conventions (OPC) defined in + ECMA-376.

+

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.

+
+
+ History +

OpenXML4J was originally developed by http://openxml4j.org/ and contributed to POI in 2008. + Thanks to the support and guidance of Julien Chable

+
+ + diff --git a/src/documentation/content/xdocs/patches.xml b/src/documentation/content/xdocs/patches.xml new file mode 100644 index 0000000000..754a288e50 --- /dev/null +++ b/src/documentation/content/xdocs/patches.xml @@ -0,0 +1,92 @@ + + + + + + +
+ Patch Queue + + + + +
+ +
+ Introduction +

+ This is an + informal list - in chronological order - + of some of the noteworthy patches that have been posted + to the + developers 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! +

+

+ Reviewers wanted! - 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. +

+

+ Before submitting a patch, please read the page on + Third-Party + Contributions. The preferred submission method for patches is: +

+
    +
  • Post to POI developers list
    • +
  • Describe the patch, the reason for it and (if necessary) why this + is important.
    • +
  • Generate the patch in the unified diff format. This format is + created by the typical Subversion client when you execute the + svn diff command or the equivalent of it in a GUI environment.
    • +
  • Also generate a documentation patch or new file, if this is + something that should be documented.
    • +
  • Post as an attachment rather than inline (unless it is trivially small).
    • +
+

Following the above guidelines will facilitate your patch being reviewed + and applied efficiently.

+
+
+ Patch Queue +

+ [Under Construction] Archive links will be added later. + Please do not bother the patch submitters/authors without first reading the + relevant post(s) in the + mailing list archives. +

+

Vapourware will not be listed.

+ + + + + + + + +
idSummaryReviewerResolutionStatus
+

See also additional list of patches to be added in + To Do. +

+
+ + diff --git a/src/documentation/content/xdocs/plan/POI10Vision.xml b/src/documentation/content/xdocs/plan/POI10Vision.xml new file mode 100644 index 0000000000..757401254b --- /dev/null +++ b/src/documentation/content/xdocs/plan/POI10Vision.xml @@ -0,0 +1,521 @@ + + + + + +
+ POI 1.0 Vision Document + + + + +
+ + + +
Preface +

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

+

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

+

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

+

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

+
+ +
1. Introduction +
1.1 Purpose of this document +

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

+
+ + +
1.2 Project Overview +

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

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

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

+
    +
  1. + Our intended audience for the HSSF + Serializer portion of this project are developers writing reports or + data extracts in XML format. +
    2. +
  2. + 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. +
    3. +
  3. + Our intended audience for the + "POIFS" OLE 2 Compound Document format reader/writer is + ourselves as we are writing the HSSF library and secondly, anyone + wishing to provide other libraries for reading/writing OLE 2 + Compound Document Format in Java. +
    4. +
+
+
2.2. User environment +

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

+
+
2.3. Key User Needs +

+ The OLE 2 Compound Document format is + undocumented for all practical purposes and cryptic for all + impractical purposes. Developer needs in this area include + documentation and an easy to use library for reading and writing in + this format without requiring the developer to have intimate + knowledge of the format. +

+

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

+

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

+ + +
+
+
3. Project Overview +
3.1. Project Perspective +

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

+
+
3.2. Project Position Statement +

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

+
+
3.3. Summary of Capabilities +

+ HSSF Serializer for Apache Cocoon 2 +

+ + + + + + + + + + + + + + + + + + + + + +
+ Benefit + + Supporting Features +
+ Standard XML tag language for sheet data + + Serializer will transform documents utilizing a defined tag + language +
+ Utilize XML to output in Excel + + Serializer will output in Excel +
+ Java API to output in Excel on any platform + + The project will develop an API that outputs in Excel using + pure Java. +
+ Make it easy for developers to port other OLE 2 Compound + Document-based formats to Java. + + The POIFS library will contain both a high-level abstraction + along with low-level constructs. The project will fully document + the OLE 2 Compound Document Format. +
+
+
3.4. Assumptions and Dependencies +
    +
  • + The HSSF Serializer will run on + any Java 2 supporting platform with Apache Cocoon 2 installed along + with the HSSF and POIFS APIs. +
    • +
  • + The HSSF API requires a Java 2 + implementation and the POI API. +
    • +
  • + The POIFS API requires a Java 2 + implementation. +
    • +
+
+
+
4. Project Features +

+ The POIFS API will include: +

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

+ The HSSF API will include: +

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

+ The POI Filesystem API includes: +

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

+ The HSSF API includes: +

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

+ The HSSF Serializer subproject: +

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

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

+
+
5.2. System Requirements +

+ The minimum system requirements for POIFS are: +

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

+ The minimum system requirements for HSSF are: +

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

+ The minimum system requirements for the HSSF Serializer are: +

+
    +
  • 64 Mbytes memory
    • +
  • Java 2 environment
    • +
  • Pentium or better processor (or equivalent on other platforms)
    • +
  • Cocoon 2
    • +
  • HSSF API
    • +
  • POI API
    • +
+
+
5.3. Performance Requirements +

+ All components must perform well enough + to be practical for use in a webserver environment (especially + Cocoon2/Tomcat/Apache combo) +

+
+
5.4. Environmental Requirements +

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

+
+
+
6. Documentation Requirements +
6.1 POI Filesystem +

+ The filesystem as read and written by + POI shall be fully documented and explained so that the average Java + developer can understand it. +

+
+
6.2. POI API +

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

+
+
6.3. HSSF File Format +

+ The HSSF File Format as implemented by + the HSSF API will be fully documented. No documentation will be + provided for features that are not supported by HSSF API that are + supported by the Excel 97 File Format. Care will be taken not to + infringe on any "legal stuff". +

+
+
6.4. HSSF API +

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

+
+ +
6.5. HSSF Serializer +

+ The HSSF Serializer will be documented + by javadoc. +

+
+ +
6.6 HSSF Serializer Tag language +

+ The XML tag language along with + function and usage shall be fully documented. Examples will be + provided as well. +

+
+
+
7. Terminology +
7.1 Filesystem +

+ filesystem shall refer only to the POI formatted archive. +

+
+
7.2 File +

+ file shall refer to the embedded data stream within a + POI filesystem. This will be the actual embedded document. +

+
+
+ + diff --git a/src/documentation/content/xdocs/plan/POI20Vision.xml b/src/documentation/content/xdocs/plan/POI20Vision.xml new file mode 100644 index 0000000000..60a8013d23 --- /dev/null +++ b/src/documentation/content/xdocs/plan/POI20Vision.xml @@ -0,0 +1,594 @@ + + + + + +
+ POI 2.0 Vision Document + + + + + + +
+ + + +
Preface +

+ This is the POI 2.0 cycle vision document. Although the vision + has not changed and this document is certainly not out of date and + the vision has not changed, the structure of the project has + changed a bit. We're not going to change the vision document to + reflect this (however proper that may be) because it would only + involve deletion. There is no purpose in providing less + information provided we give clarification. +

+

+ This document was created before the POI components for + Apache Cocoon + were accepted into the Cocoon project itself. It was also + written before POI was accepted into Jakarta. So while the + vision hasn't changed some of the components are actually now + part of other projects. We'll still be working on them on the + same timeline roughly (minus the overhead of coordination with + other groups), but they are no longer technically part of the + POI project itself. +

+
+ +
1. Introduction +
1.1 Purpose of this document +

+ The purpose of this document is to + collect, analyze and define high-level requirements, user needs, + and features of the second release of the POI project software. + The POI project currently consists of the following components: + the HSSF Serializer, the HSSF library and the POIFS library. +

+
    +
  • + The HSSF Serializer is a set of Java classes whose main + class supports the Serializer interface from the Cocoon + 2 project and outputs the serialized data in a format + compatible with the spreadsheet program Microsoft Excel + '97. +
    • +
  • + The HSSF library is a set of classes for reading and + writing Microsoft Excel 97 file format using pure Java. +
    • +
  • + The POIFS library is a set of classes for reading and + writing Microsoft's OLE 2 Compound Document format using + pure Java. +
    • +
+

By the completion of this release cycle the POI project will also + include the HSSF Generator and the HWPF library. +

+
    +
  • The HSSF Generator will be responsible for using HSSF to read + in the XLS (Excel 97) file format and create SAX events. The HSSF + Generator will support the applicable interfaces specified by the + Apache Cocoon 2 project. +
    • +
  • The HWPF library will provide a set of high level interfaces + for reading and writing Microsoft Word 97 file format using pure + Java.
    • +
+ +
+ + +
1.2 Project Overview +

+ The first release of the POI project + was an astounding success. This release seeks to build on that + success by: +

+
    +
  • + Refactoring POIFS into imput and + output classes as well as an event-driven API for reading. +
    • +
  • + Refactor HSSF for greater + performance as well as an event-driven API for reading +
    • +
  • + Extend HSSF by adding the ability to read and write formulas. +
    • +
  • + Extend HSSF by adding the ability to read and write + user-defined styles. +
    • +
  • + Create a Cocoon 2 Generator for HSSF using the same tags + as the HSSF Serializer. +
    • +
  • + Create a new library (HWPF) for reading and writing + Microsoft Word DOC format. +
    • +
  • + Refactor the HSSFSerializer into a separate extensible + POIFSSerializer and HSSFSerializer +
    • +
  • + Providing the create excel charts. (write only) +
    • +
+
+
+
2. User Description +
2.1 User/Market Demographics +

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

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

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

+
+
2.3. Key User Needs +

+ The HSSF library currently requires a + full object representation to be created before reading values. This + results in very high memory utilization. We need to reduce this + substantially for reading. It would be preferable to do this for + writing, but it may not be possible due to the constraints imposed by + the file format itself. Memory utilization during read is our top + user complaint. +

+

+ The POIFS library currently requires a + full object representation to be created before reading values. This + results in very high memory utilization. We need to reduce this + substantially for reading. +

+

+ The HSSF library currently ignores + formula cells and identifies them as "UnknownRecord" at the + lower level of the API. We must provide a way to read and write + formulas. This is now the top requested feature. +

+

+ The HSSF library currently does not support + charts. This is a key requirement of some users who wish to use HSSF + in a reporting engine. +

+

+ The HSSF Serializer currently does not + provide serialization for cell styling. User's will want stylish + spreadsheets to result from their XML. +

+

+ There is currently no way to generate + the XML from an XLS that is consistent with the format used by the + HSSF Serializer. +

+

+ There should be a way to read and write + the DOC file format using pure Java. +

+ +
+
+
3. Project Overview +
3.1. Project Perspective +

+ The produced code shall be licensed by + the Apache License as used by the Cocoon 2 project (APL 1.1) and + maintained on at http://poi.sourceforge.net + and http://sourcefoge.net/projects/poi. + It is our hope to at some point integrate with the various Apache + projects (xml.apache.org and jakarta.apache.org), at which point we'd + turn the copyright over to them. +

+
+
3.2. Project Position Statement +

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

+
+
3.3. Summary of Capabilities +

+ HSSF Serializer for Apache Cocoon 2 +

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ Benefit + + Supporting Features +
+ Ability to serialize styles from XML spreadsheets. + + HSSFSerialzier will support styles. +
+ Ability to read and write formulas in XLS files. + + HSSF will support reading/writing formulas. +
+ Ability to output in MS Word on any platform using Java. + + The project will develop an API that outputs in Word format + using pure Java. +
+ Enhance performance for reading and writing XLS files. + + HSSF will undergo a number of performance enhancements. HSSF + will include a new event-based API for reading XLS files. POIFS + will support a new event-based API for reading OLE2 CDF files. +
+ Ability to generate XML from XLS files + + The project will develop an HSSF Generator. +
+ The ability to generate charts + + HSSF will provide low level support for chart records as well + as high level API support for generating charts. The ability + to read chart information will not initially be provided. +
+
+
3.4. Assumptions and Dependencies +
    +
  • + The HSSF Serializer and Generator + will support the Gnumeric 1.0 XML tag language. +
    • +
  • + The HSSF Generator and HSSF + Serializer will be mutually validating. It should be possible to + have an XLS file created by the Serializer run through the Generator + and the output back through the Serializer (via the Cocoon pipeline) + and get the same file or a reasonable facimille (no one cares if it + differs by the order of the binary records in some minor but + non-visually recognizable manner). +
    • +
  • + The HSSF Generator will run on any + Java 2 supporting platform with Apache Cocoon 2 installed along with + the HSSF and POIFS APIs. +
    • +
  • + The HSSF Serializer will run on + any Java 2 supporting platform with Apache Cocoon 2 installed along + with the HSSF and POIFS APIs. +
    • +
  • + The HWPF API requires a Java 2 + implementation and the POIFS API. +
    • +
  • + The HSSF API requires a Java 2 + implementation and the POIFS API. +
    • +
  • + The POIFS API requires a Java 2 + implementation. +
    • + +
+
+
+
4. Project Features +

+ Enhancements to the POIFS API will + include: +

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

+ Enhancements to the HSSF API will + include: +

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

+ The HSSF Generator will include: +

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

+ The HWPF API will include: +

+
    +
  • + An event driven API for reading + DOC files. +
    • +
  • + A set of high and low level APIs + for reading and writing DOC files. +
    • +
  • + Documentation of the DOC file + format or enhancements to existing documentation. +
    • +
+
+
5. Other Product Requirements +
5.1. Applicable Standards +

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

+
+
5.2. System Requirements +

+ The minimum system requirements for the POIFS API are: +

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

+ The minimum system requirements for the the HSSF API are: +

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

+ The minimum system requirements for the the HWPF API are: +

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

+ The minimum system requirements for the HSSF Serializer are: +

+
    +
  • 64 Mbytes memory
    • +
  • Java 2 environment
    • +
  • Pentium or better processor (or equivalent on other platforms)
    • +
  • Cocoon 2
    • +
  • HSSF API
    • +
  • POI API
    • +
+
+
5.3. Performance Requirements +

+ All components must perform well enough + to be practical for use in a webserver environment (especially + the "killer trio": Cocoon2/Tomcat/Apache combo) +

+
+
5.4. Environmental Requirements +

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

+
+
+
6. Documentation Requirements +
6.1 POI Filesystem +

+ The filesystem as read and written by + POI shall be fully documented and explained so that the average Java + developer can understand it. +

+
+
6.2. POI API +

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

+
+
6.3. HSSF File Format +

+ The HSSF File Format as implemented by + the HSSF API will be fully documented. No documentation will be + provided for features that are not supported by HSSF API that are + supported by the Excel 97 File Format. Care will be taken not to + infringe on any "legal stuff". Additionally, we are + collaborating with the fine folks at OpenOffice.org on + *free* documentation of the format. +

+
+
6.4. HSSF API +

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

+
+
6.5 HWPF API +

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

+
+
6.6 HSSF Serializer +

+ The HSSF Serializer will be documented + by javadoc. +

+
+
6.7 HSSF Generator +

+ The HSSF Generator will be documented + by javadoc. +

+
+
6.8 HSSF Serializer Tag language +

+ The XML tag language along with + function and usage shall be fully documented. Examples will be + provided as well. +

+
+
+
7. Terminology +
7.1 Filesystem +

+ filesystem shall refer only to the POI formatted archive. +

+
+
7.2 File +

+ file shall refer to the embedded data stream within a + POI filesystem. This will be the actual embedded document. +

+
+
+ + diff --git a/src/documentation/content/xdocs/plan/book.xml b/src/documentation/content/xdocs/plan/book.xml new file mode 100644 index 0000000000..b666aeab2a --- /dev/null +++ b/src/documentation/content/xdocs/plan/book.xml @@ -0,0 +1,39 @@ + + + + + + + + + + + + + + + + + + + + diff --git a/src/documentation/content/xdocs/plan/index.xml b/src/documentation/content/xdocs/plan/index.xml new file mode 100644 index 0000000000..5e8aa4e309 --- /dev/null +++ b/src/documentation/content/xdocs/plan/index.xml @@ -0,0 +1,76 @@ + + + + + +
+ Planning Documentation + Overview + + + + +
+ + +
Overview + +

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

+ +

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

+ +

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

+ +

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

+ +

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

+
+ +
Topics and Issues + +
    +
  • POI Version 2.0 Vision +
    • +
  • POI Version 1.0 Vision +
    • +
  • See the general To Do list + and the dev email archives for other issues
    • +
+
+ + + diff --git a/src/documentation/content/xdocs/plan/release.xml b/src/documentation/content/xdocs/plan/release.xml new file mode 100644 index 0000000000..ddbb2f7fc7 --- /dev/null +++ b/src/documentation/content/xdocs/plan/release.xml @@ -0,0 +1,81 @@ + + + + + +
+ Release Plan 2.0 + Planning Documentation + + + + +
+ + +
Preparation for release of Poi +

Todo

+ +
+ + + diff --git a/src/documentation/content/xdocs/poi-ruby.xml b/src/documentation/content/xdocs/poi-ruby.xml new file mode 100644 index 0000000000..8579380e7a --- /dev/null +++ b/src/documentation/content/xdocs/poi-ruby.xml @@ -0,0 +1,148 @@ + + + + + +
+ POI Ruby Bindings + + + +
+ + +
Intro +

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 +

+

The bindings are generated by compiling POI with gcj, + and generating the Ruby wrapper using SWIG. 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.

+
+ + +
Getting Started +
Pre-Requisites +

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 + libgcj , presumably from the same version of GCC with which you compiled. +

+
+
Subversion +

+ The POI-Ruby module sits under the POI Subversion. Running make + inside that directory will create a loadable ruby extention poi4r.so in the release subdirectory. Tests + are in the tests/ subdirectory, and should be run from the poi-ruby directory. Please read the tests to figure out the usage. +

+

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!

+
+
Binary +

A version of poi4r.so is available here. 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.

+
+
+ + + + +
+ Usage +

The following ruby code shows some of the things you can do with POI in Ruby

+ + 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")) + +

The tc_base_tests.rb file in the tests sub directory of the source distribution + contains examples of simple uses of the API. The quick quide 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 POI API documentation for more details. +

+
+ +
+ Future Directions +
TODO's +
    +
  • Implement support for reading Excel files (easy)
    • +
  • Expose POIFS API to read raw OLE2 files from Ruby
    • +
  • Expose HPSF API to read property streams
    • +
  • Tests... Tests... Tests...
    • +
+
+
Limitations +
    +
  • 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.
    • +
  • 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.
    • +
  • Packaging - The current make file makes no effort to install the extension into the standard ruby directories. This should probably be + packaged as a gem.
    • +
+
+ +
+ + +
+ + Copyright 2005 The Apache Software Foundation or its licensors, as applicable. + +
+ diff --git a/src/documentation/content/xdocs/poifs/book.xml b/src/documentation/content/xdocs/poifs/book.xml new file mode 100644 index 0000000000..d2fc4a3c78 --- /dev/null +++ b/src/documentation/content/xdocs/poifs/book.xml @@ -0,0 +1,40 @@ + + + + + + + + + + + + + + + + + + + + + diff --git a/src/documentation/content/xdocs/poifs/embeded.xml b/src/documentation/content/xdocs/poifs/embeded.xml new file mode 100644 index 0000000000..2ffd9f6295 --- /dev/null +++ b/src/documentation/content/xdocs/poifs/embeded.xml @@ -0,0 +1,95 @@ + + + + +
+ Apache POI - POIFS - Documents embeded in other documents + Overview + + + + +
+ +
Overview +

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.

+

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.

+

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.

+ +
Files embeded in Excel +

Excel normally stores embeded files in subdirectories + of the filesystem root. Typically these subdirectories + are named starting with MBD, with 8 hex characters following.

+
+ +
Files embeded in Word +

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.

+
+ +
Files embeded in PowerPoint +

PowerPoint does not normally store embeded files + in the OLE2 layer. Instead, they are held within records + of the main PowerPoint file. +
See the HSLF Tutorial + for how to retrieve embedded OLE objects from a presentation

+
+
+ +
Listing POIFS contents +

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.

+

The tool to use is org.apache.poi.poifs.dev.POIFSLister. + 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.

+
+ +
Opening embeded files +

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.

+

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.

+
+ + diff --git a/src/documentation/content/xdocs/poifs/fileformat.xml b/src/documentation/content/xdocs/poifs/fileformat.xml new file mode 100644 index 0000000000..5aefd2859d --- /dev/null +++ b/src/documentation/content/xdocs/poifs/fileformat.xml @@ -0,0 +1,703 @@ + + + + +
+ POIFS File System Internals + + + +
+ +
POIFS File System Internals +
Introduction +

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 ".xls" would likely + contain spreadsheet data, and a file ending in + ".doc" would probably contain a word processing + document. POIFS file systems are called "file + system", 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 "files" it contains.

+

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.

+

The POIFS file system does not encode the documents + themselves. For example, if you had a word processor file + with the extension ".doc", you would actually + have a POIFS file system with a document file archived + inside of that file system.

+

Note - this document is a good overview and explanation of + the file format, but for the very nitty-gritty details, + you should refer to + [MS-CFB].pdf + in the (now public) Microsoft Documentation.

+
+
Document Conventions +

This document utilizes the numeric types as described by + the Java Language Specification, which can be found at + http://java.sun.com. In + short:

+
    +
  • A byte is an 8 bit signed integer ranging from + -128 to 127.
    • +
  • A short is a 16 bit signed integer ranging from + -32768 to 32767
    • +
  • An int is a 32 bit signed integer ranging from + -2147483648 to 2147483647
    • +
  • A long is a 64 bit signed integer ranging from + -9.22E18 to 9.22E18.
    • +
+

The Java Language Specification spells out a number of + other types that are not referred to by this document.

+

Where this document makes references to "endian + conversion" it is referring to the byte order of + stored numbers. Numbers in "little-endian order" + are stored with the least 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 or operation to it + against the first byte. The following code illustrates this + method:

+ +public int getShort (byte[] rec) +{ + return ((rec[1] << 8) | (rec[0] & 0x00ff)); +} +
+
File System Walkthrough +

This is a walkthrough of a POIFS file system and how it is + put together. It is not intended to give a concise + description but to give a "big picture" of the + general structure and how it's interpreted.

+

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.

+

The first 64 bits of the header compose a magic number + identifier. 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 "sanity check" to + make sure this is a POIFS file system and not some other + format. The header also contains an array of block + numbers. These block numbers refer to blocks in the + file. When these blocks are read together they form the + Block Allocation Table. The header also contains a + pointer to the first element in the property table, + also known as the root element, and a pointer to the + small Block Allocation Table (SBAT).

+

The block allocation table or BAT, along with + the property table, 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 "end of file".

+

The property table is essentially the directory + storage for the file system. It consists of the name of the + file or directory, its start block in both the file + system and BAT, and its actual size. The first + property in the property table is the root + element. 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 small block data.

+

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.

+
+
Header Block +

The POIFS file system begins with a header + block. The first 64 bits of the header form a long + file type id or magic number identifier of + 0xE11AB1A1E011CFD0L. 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.

+

It's important to know the most important parts of the + header. These are discussed in the rest of this + section.

+
BATs +

At offset 0x2C is an int specifying the number + of elements in the BAT array. The array at + 0x4C an array of ints. This array contains the + indices of every block in the Block Allocation + Table.

+
+
XBATs +

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 0x44 of the header is the index of the + first extended BAT (XBAT) block. At offset + 0x48 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.

+

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.

+

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

+

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.

+
+
SBATs +

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 small + block allocation table is used to navigate the + array of small blocks. The SBAT's start block index is + found at offset 0x3C 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).

+
+
Property Table Start Index +

An integer at address 0x30 specifies the start + index of the property table. This integer is specified + as a "block index". The Property Table + is stored, as is almost everything in a POIFS file + system, in big blocks and walked via the BAT. The + Property Table is described below.

+
+
+
Property Table +

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:

+
    +
  • At offset 0x00 in the property is the + "name". This is stored as an + uncompressed 16 bit unicode string. In short every + other byte corresponds to an "ASCII" + character. The size of this string is stored at offset + 0x40 (string size) as a short.
    • +
  • At offset 0x42 is the property type + (byte). The type is 1 for directory, 2 for file or 5 + for the Root Entry.
    • +
  • At offset 0x43 is the node color + (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: +
      +
    1. The root of the tree is always black
      2. +
    2. Two consecutive nodes cannot both be red
      3. +
    3. A property is less than another property if its + name length is less than the other property's name + length
      4. +
    4. If two properties have the same name length, the + sort order is determined by the sort order of the + properties' names.
      5. +
    • +
  • At offset 0x44 is the index (int) of the + previous property.
    • +
  • At offset 0x48 is the index (int) of the + next property.
    • +
  • At offset 0x4C is the index (int) of the + first directory entry. This is used by + directory entries.
    • +
  • At offset 0x74 is an integer giving the + start block 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.
    • +
  • At offset 0x78 is an integer giving the total + actual size 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 Root + Entry, which, regardless of its size, is + always stored in big blocks and the main BAT is + used to walk the big blocks making up this special + file.
    • +
+
+
Root Entry +

The Root Entry in the Property Table + 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 Small Block Array, 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 Block + Allocation Table. 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).

+
+
Walking the Nodes of the Property Table +

The individual properties form a directory tree, with the + Root Entry as the directory tree's root, as shown + in the accompanying drawing. Note the numbers in + parentheses in each node; they represent the node's index + in the array of properties. The NEXT_PROP, + PREVIOUS_PROP, and CHILD_PROP fields hold + these indices, and are used to navigate the tree.

+

property set

+

Each directory entry (i.e., a property whose type is + directory or root entry) uses its + CHILD_PROP 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.

+

The children of a given directory property point to each + other in a similar fashion by using their + NEXT_PROP and PREVIOUS_PROP fields.

+

Unused NEXT_PROP, PREVIOUS_PROP, and + CHILD_PROP fields contain the marker value of + -1. All file properties have a value of -1 for their + CHILD_PROP fields for example.

+
+
Block Allocation Table +

The BAT blocks are pointed at by the bat array + contained in the header and supplemented, if necessary, + by the XBAT blocks. These blocks form a large + table of integers. These integers are block numbers. The + Block Allocation Table 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 property for a given file. The + elements in this BAT are both the block number (within + the file minus the header) and 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.

+

Here's an example: Let's assume that the BAT begins as + follows:

+

BAT[ 0 ] = 2

+

BAT[ 1 ] = 5

+

BAT[ 2 ] = 3

+

BAT[ 3 ] = 4

+

BAT[ 4 ] = 6

+

BAT[ 5 ] = -2

+

BAT[ 6 ] = 7

+

BAT[ 7 ] = -2

+

...

+

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.

+

Similarly, a file beginning at index 1 consists of + blocks 1 and 5.

+

Other special numbers in a BAT array are:

+
    +
  • -1, which indicates an unused block
    • +
  • -3, which indicates a "special" block, such + as a block used to make up the Small Block Array, the + Property Table, the main BAT, or the SBAT
    • +
+
+
File System Structures +

The following outlines the basic file system structures.

+
Header (block 1) -- 512 (0x200) bytes + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldDescriptionOffsetLengthDefault value or const
FILETYPEMagic number identifying this as a POIFS file + system.0x0000Long0xE11AB1A1E011CFD0
UK1Unknown constant0x0008Integer0
UK2Unknown Constant0x000CInteger0
UK3Unknown Constant0x0014Integer0
UK4Unknown Constant (revision?)0x0018Short0x003B
UK5Unknown Constant (version?)0x001AShort0x0003
UK6Unknown Constant0x001CShort-2
LOG_2_BIG_BLOCK_SIZELog, base 2, of the big block size0x001EShort9 (2 ^ 9 = 512 bytes)
LOG_2_SMALL_BLOCK_SIZELog, base 2, of the small block size0x0020Integer6 (2 ^ 6 = 64 bytes)
UK7Unknown Constant0x0024Integer0
UK8Unknown Constant0x0028Integer0
BAT_COUNTNumber of elements in the BAT array0x002CIntegerrequired
PROPERTIES_STARTBlock index of the first block of the property + table0x0030Integerrequired
UK9Unknown Constant0x0034Integer0
UK10Unknown Constant0x0038Integer0x00001000
SBAT_STARTBlock index of first big block containing the small + block allocation table (SBAT)0x003CInteger-2
SBAT_Block_CountNumber of big blocks holding the SBAT0x0040Integer1
XBAT_STARTBlock index of the first block in the Extended Block + Allocation Table (XBAT)0x0044Integer-2
XBAT_COUNTNumber of elements in the Extended Block Allocation + Table (to be added to the BAT)0x0048Integer0
BAT_ARRAYArray of block indices constituting the Block + Allocation Table (BAT)0x004C, 0x0050, 0x0054 ... 0x01FCInteger[]-1 for unused elements, at least first element must + be filled.
N/AHeader block data not otherwise described in this + tableN/AN/A-1
+
+
+ Block Allocation Table Block -- 512 (0x200) bytes + + + + + + + + + + + + + + + +
+ Field + + Description + + Offset + + Length + + Default value or const +
BAT_ELEMENTAny given element in the BAT block0x0000, 0x0004, 0x0008, ... 0x01FCInteger + -1 = unused
+ -2 = end of chain
+ -3 = special (e.g., BAT block)
+ All other values point to the next element in the + chain and the next index of a block composing the + file. +
+
+
Property Block -- 512 (0x200) byte block + + + + + + + + + + + + + + + +
FieldDescriptionOffsetLengthDefault value or const
Properties[]This block contains the properties.0x0000, 0x0080, 0x0100, 0x0180128 bytesAll unused space is set to -1.
+
+
Property -- 128 (0x80) byte block + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldDescriptionOffsetLengthDefault value or const
NAMEA unicode null-terminated uncompressed 16bit string + (lose the high bytes) containing the name of the + property.0x00, 0x02, 0x04, ... 0x3EShort[]0x0000 for unused elements, field required, 32 + (0x40) element max
NAME_SIZENumber of characters in the NAME field0x40ShortRequired
PROPERTY_TYPEProperty type (directory, file, or root)0x42Byte1 (directory), 2 (file), or 5 (root entry)
NODE_COLORNode color0x43Byte0 (red) or 1 (black)
PREVIOUS_PROPPrevious property index0x44Integer-1
NEXT_PROPNext property index0x48Integer-1
CHILD_PROPFirst child property index0x4cInteger-1
SECONDS_1Seconds component of the created timestamp?0x64Integer0
DAYS_1Days component of the created timestamp?0x68Integer0
SECONDS_2Seconds component of the modified timestamp?0x6CInteger0
DAYS_2Days component of the modified timestamp?0x70Integer0
START_BLOCKStarting block of the file, used as the first block + in the file and the pointer to the next block from + the BAT0x74IntegerRequired
SIZEActual size of the file this property points + to. (used to truncate the blocks to the real + size).0x78Integer0
+
+
+
+ + diff --git a/src/documentation/content/xdocs/poifs/how-to.xml b/src/documentation/content/xdocs/poifs/how-to.xml new file mode 100644 index 0000000000..5e107070d1 --- /dev/null +++ b/src/documentation/content/xdocs/poifs/how-to.xml @@ -0,0 +1,431 @@ + + + + +
+ How To Use the POIFS APIs + + + +
+ +
How To Use the POIFS APIs +

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.

+
Target Audience +

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.

+
+
Glossary +

This document attempts to be consistent in its terminology, which is defined here:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TermDefinition
DirectoryA special file that may contain other directories and documents.
DirectoryEntryRepresentation of a directory within another directory.
DocumentA file containing data, such as word processing data or a spreadsheet workbook.
DocumentEntryRepresentation of a document within a directory.
EntryRepresentation of a file in a directory.
FileA named entity, managed and contained by the file system.
File SystemThe POIFS data structures, plus the contained directories and documents, which are maintained in a hierarchical directory structure.
Root DirectoryThe 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.
+
+
+
Reading a File System +

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.

+ + + + + + + + + + + + + + + + + + + + + +
TechniqueAdvantagesDisadvantages
Conventional Reading (POIFSFileSystem) + Simpler API similar to reading a conventional file system.
+ Can read documents in any order. + 		+ All files are resident in memory, whether your application needs them or not. +
New NIO driven Reading (NPOIFSFileSystem) + Simpler API similar to reading a conventional file system.
+ Can read documents in any order.
+ Lower memory than POIFSFileSystem + 		+ If created from an InputStream, all files are resident in memory. + (If created from a File, only certain key structures are)
+ Currently doesn't support writing +
Event-Driven Reading + Reduced footprint -- only the documents you care about are processed.
+ Improved performance -- no time is wasted reading the documents you're not interested in. + 		+ More complicated API.
+ Need to know in advance which documents you want to read.
+ No control over the order in which the documents are read.
+ 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. +
+
Conventional Reading +

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.

+
Preparation +

Before an application can read a file from the file system, the file system needs to be loaded into memory. This is done by using the org.apache.poi.poifs.filesystem.POIFSFileSystem class. Once the file system has been loaded into memory, the application may need the root directory. The following code fragment will accomplish this preparation stage:

+ +// need an open InputStream; for a file-based system, this would be appropriate: +// 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(); +

Assuming no exception was thrown, the file system can then be read.

+

Note: loading the file system can take noticeable time, particularly for large file systems.

+
+
Reading the Directory Tree +

Once the file system has been loaded into memory and the root directory has been obtained, the root directory can be read. The following code fragment shows how to read the entries in an org.apache.poi.poifs.filesystem.DirectoryEntry instance:

+ +// dir is an instance of DirectoryEntry ... +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. + } +} +
+
Reading a Specific Document +

There are a couple of ways to read a document, depending on whether the document resides in the root directory or in another directory. Either way, you will obtain an org.apache.poi.poifs.filesystem.DocumentInputStream instance.

+
DocumentInputStream +

The DocumentInputStream class is a simple implementation of InputStream that makes a few guarantees worth noting:

+
    +
  • available() always returns the number of bytes in the document from your current position in the document.
    • +
  • markSupported() returns true.
    • +
  • mark(int limit) ignores the limit parameter; basically the method marks the current position in the document.
    • +
  • reset() takes you back to the position when mark() was last called, or to the beginning of the document if mark() has not been called.
    • +
  • skip(long n) will take you to your current position + n (but not past the end of the document).
    • +
+

The behavior of available means you can read in a document in a single read call like this:

+ +byte[] content = new byte[ stream.available() ]; +stream.read(content); +stream.close(); +

The combination of mark, reset, and skip provide the basic mechanisms needed for random access of the document contents.

+
+
Reading a Document From the Root Directory +

If the document resides in the root directory, you can obtain a DocumentInputStream like this:

+ +// 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 +} +
+
Reading a Document From an Arbitrary Directory +

A more generic technique for reading a document is to obtain an org.apache.poi.poifs.filesystem.DirectoryEntry instance for the directory containing the desired document (recall that you can use getRoot() to obtain the root directory from its file system). From that DirectoryEntry, you can then obtain a DocumentInputStream like this:

+ +DocumentEntry document = (DocumentEntry)directory.getEntry(documentName); +DocumentInputStream stream = new DocumentInputStream(document); + +
+
+
+
NIO Reading using NPOIFSFileSystem +

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.

+

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.

+
Preparation +

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 org.apache.poi.poifs.filesystem.NPOIFSFileSystem + 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:

+ +// 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(); + +

Assuming no exception was thrown, the file system can then be read.

+

One the NPOFSFileSytem is open, you can manipulate it just like + a POIFSFileSytem one.

+
+
+
Event-Driven Reading +

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.

+
Preparation +

The preparation phase involves creating an instance of org.apache.poi.poifs.eventfilesystem.POIFSReader and to then register one or more org.apache.poi.poifs.eventfilesystem.POIFSReaderListener instances with the POIFSReader.

+ +POIFSReader reader = new POIFSReader(); +// 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"); +
+
POIFSReaderListener +

org.apache.poi.poifs.eventfilesystem.POIFSReaderListener is an interface used to register for documents. When a matching document is read by the org.apache.poi.poifs.eventfilesystem.POIFSReader, the POIFSReaderListener instance receives an org.apache.poi.poifs.eventfilesystem.POIFSReaderEvent instance, which contains an open DocumentInputStream and information about the document.

+

A POIFSReaderListener instance can register for individual documents, or it can register for all documents; once it has registered for all documents, subsequent (and previous!) registration requests for individual documents are ignored. There is no way to unregister a POIFSReaderListener.

+

Thus, it is possible to register a single POIFSReaderListener for multiple documents - one, some, or all documents. It is guaranteed that a single POIFSReaderListener will receive exactly one notification per registered document. There is no guarantee as to the order in which it will receive notification of its documents, as future implementations of POIFSReader are free to change the algorithm for walking the file system's directory structure.

+

It is also permitted to register more than one POIFSReaderListener for the same document. There is no guarantee of ordering for notification of POIFSReaderListener instances that have registered for the same document when POIFSReader processes that document.

+

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

+

The following table describes the three ways to register a POIFSReaderListener for a document or set of documents:

+ + + + + + + + + + + + + + + + + +
Method SignatureWhat it does
registerListener(POIFSReaderListener listener)registers listener for all documents.
registerListener(POIFSReaderListener listener, String name)registers listener for a document with the specified name in the root directory.
registerListener(POIFSReaderListener listener, POIFSDocumentPath path, String name)registers listener for a document with the specified name in the directory described by path
+
+
POIFSDocumentPath +

The org.apache.poi.poifs.filesystem.POIFSDocumentPath class is used to describe a directory in a POIFS file system. Since there are no reserved characters in the name of a file in a POIFS file system, a more traditional string-based solution for describing a directory, with special characters delimiting the components of the directory name, is not feasible. The constructors for the class are used as follows:

+ + + + + + + + + + + + + + + + + + + + + + + + + +
Constructor exampleDirectory described
new POIFSDocumentPath()The root directory.
new POIFSDocumentPath(null)The root directory.
new POIFSDocumentPath(new String[ 0 ])The root directory.
new POIFSDocumentPath(new String[ ] { "foo", "bar"} )in Unix terminology, "/foo/bar".
new POIFSDocumentPath(new POIFSDocumentPath(new String[] { "foo" }), new String[ ] { "fu", "bar"} )in Unix terminology, "/foo/fu/bar".
+
+
Processing POIFSReaderEvent Events +

Processing org.apache.poi.poifs.eventfilesystem.POIFSReaderEvent events is relatively easy. After all of the POIFSReaderListener instances have been registered with POIFSReader, the POIFSReader.read(InputStream stream) method is called.

+

Assuming that there are no problems with the data, as the POIFSReader processes the documents in the specified InputStream's data, it calls registered POIFSReaderListener instances' processPOIFSReaderEvent method with a POIFSReaderEvent instance.

+

The POIFSReaderEvent instance contains information to identify the document (a POIFSDocumentPath object to identify the directory that the document is in, and the document name), and an open DocumentInputStream instance from which to read the document.

+
+
+
+
Writing a File System +

Writing a file system is very much like reading a file system in that there are multiple ways to do so. You can load an existing file system into memory and modify it (removing files, renaming files) and/or add new files to it, and write it, or you can start with a new, empty file system:

+ +POIFSFileSystem fs = new POIFSFileSystem(); +
The Naming of Names +

There are two restrictions on the names of files in a file system that must be considered when creating files:

+
    +
  1. The name of the file must not exceed 31 characters. If it does, the POIFS API will silently truncate the name to fit.
    2. +
  2. The name of the file must be unique within its containing directory. This seems pretty obvious, but if it isn't spelled out, there'll be hell to pay, to be sure. Uniqueness, of course, is determined after the name has been truncated, if the original name was too long to begin with.
    3. +
+
+
Creating a Document +

A document can be created by acquiring a DirectoryEntry and calling one of the two createDocument methods:

+ + + + + + + + + + + + + + + + +
Method SignatureAdvantagesDisadvantages
CreateDocument(String name, InputStream stream) + Simple API. + + Increased memory footprint (document is in memory until file system is written). +
CreateDocument(String name, int size, POIFSWriterListener writer) + Decreased memory footprint (only very small documents are held in memory, and then only for a short time). + + More complex API.
+ Determining document size in advance may be difficult.
+ Lose control over when document is to be written. +
+

Unlike reading, you don't have to choose between the in-memory and event-driven writing models; both can co-exist in the same file system.

+

Writing is initiated when the POIFSFileSystem instance's writeFilesystem() method is called with an OutputStream to write to.

+

The event-driven model is quite similar to the event-driven model for reading, in that the file system calls your org.apache.poi.poifs.filesystem.POIFSWriterListener when it's time to write your document, just as the POIFSReader calls your POIFSReaderListener when it's time to read your document. Internally, when writeFilesystem() is called, the final POIFS data structures are created and are written to the specified OutputStream. When the file system needs to write a document out that was created with the event-driven model, it calls the POIFSWriterListener back, calling its processPOIFSWriterEvent() method, passing an org.apache.poi.poifs.filesystem.POIFSWriterEvent instance. This object contains the POIFSDocumentPath and name of the document, its size, and an open org.apache.poi.poifs.filesystem.DocumentOutputStream to which to write. A DocumentOutputStream is a wrapper over the OutputStream that was provided to the POIFSFileSystem to write to, and has the responsibility of making sure that the document your application writes fits within the size you specified for it.

+
+
Creating a Directory +

Creating a directory is similar to creating a document, except that there's only one way to do so:

+ +DirectoryEntry createdDir = existingDir.createDirectory(name); +
+
Using POIFSFileSystem Directly To Create a Document Or Directory +

As with reading documents, it is possible to create a new document or directory in the root directory by using convenience methods of POIFSFileSystem.

+ + + + + + + + + + + + + + + + + +
DirectoryEntry Method SignaturePOIFSFileSystem Method Signature
createDocument(String name, InputStream stream)createDocument(InputStream stream, String name)
createDocument(String name, int size, POIFSWriterListener writer)createDocument(String name, int size, POIFSWriterListener writer)
createDirectory(String name)createDirectory(String name)
+
+
+
Modifying a File System +

It is possible to modify an existing POIFS file system, whether it's one your application has loaded into memory, or one which you are creating on the fly.

+
Removing a Document +

Removing a document is simple: you get the Entry corresponding to the document and call its delete() method. This is a boolean method, but should always return true, indicating that the operation succeeded.

+
+
Removing a Directory +

Removing a directory is also simple: you get the Entry corresponding to the directory and call its delete() method. This is a boolean method, but, unlike deleting a document, may not always return true, indicating that the operation succeeded. Here are the reasons why the operation may fail:

+
    +
  • The directory still has files in it (to check, call isEmpty() on its DirectoryEntry; is the return value false?)
    • +
  • The directory is the root directory. You cannot remove the root directory.
    • +
+
+
Renaming a File +

Regardless of whether the file is a directory or a document, it can be renamed, with one exception - the root directory has a special name that is expected by the components of a major software vendor's office suite, and the POIFS API will not let that name be changed. Renaming is done by acquiring the file's corresponding Entry instance and calling its renameTo method, passing in the new name.

+

Like delete, renameTo returns true if the operation succeeded, otherwise false. Reasons for failure include these:

+
    +
  • The new name is the same as another file in the same directory. And don't forget - if the new name is longer than 31 characters, it will be silently truncated. In its original length, the new name may have been unique, but truncated to 31 characters, it may not be unique any longer.
    • +
  • You tried to rename the root directory.
    • +
+
+
+ + diff --git a/src/documentation/content/xdocs/poifs/html/POIFSDesignDocument.html b/src/documentation/content/xdocs/poifs/html/POIFSDesignDocument.html new file mode 100644 index 0000000000..e4dcdb5046 --- /dev/null +++ b/src/documentation/content/xdocs/poifs/html/POIFSDesignDocument.html @@ -0,0 +1,1297 @@ + + + + POIFS Design Document + + + POIFS Design Document +

+ This document describes the design of the POIFS system. It is + organized as follows: +

+
    +
  • + Scope A description of the limitations of + this document. +
    • +
  • + Assumptions The assumptions on + which this design is based. +
    • +
  • + Design Considerations The + constraints and goals applied to the design. +
    • +
  • + Design The design of the POIFS system. +
    • +
+

+
    +
  1. + Scope +

    + This document is written as part of an iterative process. + As that process is not yet complete, neither is this + document. +

    +
    2. +
  2. + Assumptions +

    + The design of POIFS is not dependent on the code written + for the proof-of-concept prototype POIFS package. +

    +
    3. +
  3. + Design + Considerations +

    + As usual, the primary considerations in the design of the + POIFS assumption involve the classic space-time tradeoff. + In this case, the main consideration has to involve + minimizing the memory footprint of POIFS. POIFS may be + called upon to create relatively large documents, and in + web application server, it may be called upon to create + several documents simultaneously, and it will likely + co-exist with other Serializer systems, competing with + those other systems for space on the server. +

    +

    + We've addressed the risk of being too slow through a + proof-of-concept prototype. This prototype for POIFS + involved reading an existing file, decomposing it into its + constituent documents, composing a new POIFS from the + constituent documents, and writing the POIFS file back to + disk and verifying that the output file, while not + necessarily a byte-for-byte image of the input file, could + be read by the application that generated the input file. + This prototype proved to be quite fast, reading, + decomposing, and re-generating a large (300K) file in 2 to + 2.5 seconds. +

    +

    + While the POIFS format allows great flexibility in laying + out the documents and the other internal data structures, + the layout of the filesystem will be kept as simple as + possible. +

    +
    4. +
  4. + Design +

    + The design of the POIFS is broken down into two parts: + discussion of the classes and + interfaces, and discussion of how + these classes and interfaces will be used to convert an + appropriate Java InputStream (such as an XML stream) to a + POIFS output stream containing an HSSF document. +

    + Classes and Interfaces +

    + The classes and interfaces used in the POIFS are broken + down as follows: +

    + + + + + + + + + + + + + + + + + + + + + +
    PackageContents
    net.sourceforge.poi.poifs.storageBlock classes and interfaces
    net.sourceforge.poi.poifs.propertyProperty classes and interfaces
    net.sourceforge.poi.poifs.filesystemFilesystem classes and interfaces
    net.sourceforge.poi.utilUtility classes and interfaces
    +
      +
    1. + Block Classes and + Interfaces +

      + The block classes and interfaces are shown + in the following class diagram. +

      +

      + +

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      Class/InterfaceDescription
      BATBlockThe BATBlock class + represents a single big block + containing 128 BAT + entries.
      Its + _fields array is + used to read and write the BAT entries + into the _data + array.
      Its + createBATBlocks + method is used to create an array of + BATBlock instances from an array of + int BAT entries.
      Its + calculateStorageRequirements + method calculates the number of BAT + blocks necessary to hold the specified + number of BAT entries.
      BigBlockThe BigBlock class is an + abstract class representing the common + big block of 512 bytes. It implements + BlockWritable, + trivially delegating the + writeBlocks method + of BlockWritable to its own abstract + writeData + method.
      BlockWritableThe BlockWritable interface + defines a single method, + writeBlocks, that + is used to write an implementation's + block data to an + OutputStream.
      DocumentBlockThe DocumentBlock class is + used by a Document to holds + its raw data. It also retains the + number of bytes read, as this is used + by the Document class to determine the + total size of the data, and is also + used internally to determine whether + the block was filled by the + InputStream or + not.
      The + DocumentBlock + constructor is passed an + InputStream from which to + fill its _data + array.
      The size + method returns the number of bytes + read (_bytes_read + when the instance was + constructed.
      The + partiallyRead + method returns true if the + _data array was + not completely filled, which may be + interpreted by the Document as having + reached the end of file + point.
      Typical use of the + DocumentBlock class is like + this:
      while + (true)
      {
          DocumentBlock + block = new + DocumentBlock(stream);
          blocks.add(block);
          size + += + block.size();
          if + (block.partiallyRead())
          {
              break;
          }
      }
      HeaderBlockThe HeaderBlock class is + used to contain the data found in a + POIFS header.
      Its IntegerField + members are used to read and write the + appropriate entries into the + _data + array.
      Its + setBATBlocks, + setPropertyStart, + and setXBATStart + methods are used to set the + appropriate fields in the + _data + array.
      The + calculateXBATStorageRequirements + method is used to determine how many + XBAT blocks are necessary to + accommodate the specified number of + BAT blocks. +
      PropertyBlockThe PropertyBlock class is + used to contain Property + instances for the PropertyTable + class.
      It contains an array, + _properties of 4 + Property instances, which together + comprise the 512 bytes of a BigBlock.
      The + createPropertyBlockArray + method is used to convert a + List of Property + instances into an array of + PropertyBlock instances. The number of + Property instances is rounded up to a + multiple of 4 by creating empty + anonymous inner class extensions of + Property.
      +
      2. +
    2. + Property Classes + and Interfaces +

      + The property classes and interfaces are + shown in the following class diagram. +

      +

      + +

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      Class/InterfaceDescription
      DirectoryThe Directory interface is + implemented by the RootProperty + class. It is not strictly necessary + for the initial POIFS implementation, + but when the POIFS supports directory + elements, this interface will be + more widely implemented, and so is + included in the design at this point + to ease the eventual support of + directory elements.
      Its methods are + a getter/setter pair, + getChildren, + returning an Iterator of + Property + instances; and + addChild, which + will allow the caller to add another + Property instance to the Directory's + children.
      DocumentPropertyThe DocumentProperty class + is a trivial extension of Property and is + used by Document to keep + track of its associated entry in the + PropertyTable.
      Its + constructor takes a name and the + document size, on the assumption that + the Document will not create a + DocumentProperty until after it has + created the storage for the document + data and therefore knows how much data + there is.
      FileThe File interface + specifies the behavior of reading and + writing the next and previous child + fields of a Property.
      PropertyThe Property class is an + abstract class that defines the basic + data structure of an element of the Property + Table.
      Its ByteField, ShortField, and + IntegerField + members are used to read and write + data into the appropriate locations in + the _raw_data + array.
      The + _index member is + used to hold a Propery instance's + index in the List of + Property instances maintained by PropertyTable, + which is used to populate the child + property of parent Directory + properties and the next property and + previous property of sibling File + properties.
      The + _name, + _next_file, and + _previous_file + members are used to help fill the + appropriate fields of the _raw_data + array.
      Setters are provided for + some of the fields (name, property + type, node color, child property, + size, index, start block), as well as + a few getters (index, child + property).
      The + preWrite method is + abstract and is used by the owning + PropertyTable to iterate through its + Property instances and prepare each + for writing.
      The + shouldUseSmallBlocks + method returns true if the Property's + size is sufficiently small - how small + is none of the caller's business. +
      PropertyBlockSee the description in PropertyBlock.
      PropertyTableThe PropertyTable class + holds all of the DocumentProperty + instances and the RootProperty + instance for a Filesystem + instance.
      It maintains a + List of its Property + instances + (_properties), and + when prepared to write its data by a + call to preWrite, + it gets and holds an array of PropertyBlock + instances + (_blocks.
      It + also maintains its start block in its + _start_block + member.
      It has a method, + getRoot, to get + the RootProperty, returning it as an + implementation of Directory, and a + method to add a Property, + addProperty, and a + method to get its start block, + getStartBlock.
      RootPropertyThe RootProperty class acts + as the Directory for + all of the DocumentProperty + instance. As such, it is more of a + pure directory + entry than a proper root + entry in the Property + Table, but the initial POIFS + implementation does not warrant the + additional complexity of a full-blown + root entry, and so it is not modeled + in this design.
      It maintains a + List of its children, + _children, in + order to perform its + directory-oriented duties.
      +
      3. +
    3. + Filesystem + Classes and Interfaces +

      + The property classes and interfaces are + shown in the following class diagram. +

      +

      + +

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      Class/InterfaceDescription
      FilesystemThe Filesystem class is the + top-level class that manages the + creation of a POIFS document.
      It + maintains a PropertyTable + instance in its + _property_table + member, a HeaderBlock + instance in its + _header_block + member, and a List of its + Document + instances in its + _documents + member.
      It provides methods for a + client to create a document + (createDocument), + and a method to write the Filesystem + to an OutputStream + (writeFilesystem).
      BATBlockSee the description in BATBlock
      BATManagedThe BATManaged interface + defines common behavior for objects + whose location in the written file is + managed by the Block + Allocation Table.
      It defines + methods to get a count of the + implementation's BigBlock + instances + (countBlocks), and + to set an implementation's start block + (setStartBlock).
      BlockAllocationTableThe BlockAllocationTable is + an implementation of the POIFS Block + Allocation Table. It is only + created when the Filesystem is + about to be written to an + OutputStream.
      It + contains an IntList of block + numbers for all of the BATManaged + implementations owned by the + Filesystem, + _entries, which is + filled by calls to + allocateSpace.
      It + fills its array, + _blocks, of BATBlock + instances when its + createBATBlocks + method is called. This method has to + take into account its own storage + requirements, as well as those of the + XBAT blocks, and so calls + BATBlock.calculateStorageRequirements + and + HeaderBlock.calculateXBATStorageRequirements + repeatedly until the counts returned + by those methods stabilize.
      The + countBlocks method + returns the number of BATBlock + instances created by the preceding + call to createBlocks.
      BlockWritableSee the description in BlockWritable
      DocumentThe Document class is used + to contain a document, such as an HSSF + workbook.
      It has its own DocumentProperty + (_property) and + stores its data in a collection of DocumentBlock + instances + (_blocks).
      It + has a method, + getDocumentProperty, + to get its DocumentProperty.
      DocumentBlockSee the description in DocumentBlock
      DocumentPropertySee the description in DocumentProperty
      HeaderBlockSee the description in HeaderBlock
      PropertyTableSee the description in PropertyTable
      +
      4. +
    4. + Utility Classes + and Interfaces +

      + The utility classes and interfaces are + shown in the following class diagram. +

      +

      + +

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      Class/InterfaceDescription
      BitFieldThe BitField class is used + primarily by HSSF code to manage + bit-mapped fields of HSSF records. It + is not likely to be used in the POIFS + code itself and is only included here + for the sake of complete documentation + of the POI utility classes.
      ByteFieldThe ByteField class is an + implementation of FixedField for + the purpose of managing reading and + writing to a byte-wide field in an + array of bytes.
      FixedFieldThe FixedField interface + defines a set of methods for reading a + field from an array of + bytes or from an + InputStream, and for + writing a field to an array of + bytes. Implementations + typically require an offset in their + constructors that, for the purposes of + reading and writing to an array of + bytes, makes sure that + the correct bytes in the + array are read or written.
      HexDumpThe HexDump class is a + debugging class that can be used to + dump an array of bytes to + an OutputStream. The + static method dump + takes an array of bytes, + a long offset that is + used to label the output, an open + OutputStream, and an + int index that specifies + the starting index within the array of + bytes.
      The data is + displayed 16 bytes per line, with each + byte displayed in hexadecimal format + and again in printable form, if + possible (a byte is considered + printable if its value is in the range + of 32 ... 126).
      Here is an example + of a small array of bytes + with an offset of + 0x110:
      00000110 C8 00 00 00 FF 7F 90 01 00 00 00 00 00 00 05 01 ................
      00000120 41 00 72 00 69 00 61 00 6C 00                   A.r.i.a.l.
      IntegerFieldThe IntegerField class is + an implementation of FixedField for + the purpose of managing reading and + writing to an integer-wide field in an + array of bytes.
      IntListThe IntList class is a + work-around for functionality missing + in Java (see http://developer.java.sun.com/developer/bugParade/bugs/4487555.html + for details); it is a simple growable + array of ints that gets + around the requirement of wrapping and + unwrapping ints in + Integer instances in + order to use the + java.util.List + interface.
      IntList mimics + the functionality of the + java.util.List interface + as much as possible.
      LittleEndianThe LittleEndian class + provides a set of static methods for + reading and writing + shorts, + ints, longs, + and doubles in and out of + byte arrays, and out of + InputStreams, preserving + the Intel byte ordering and encoding + of these values.
      LittleEndianConstsThe LittleEndianConsts + interface defines the width of a + short, int, + long, and + double as stored by Intel + processors.
      LongFieldThe LongField class is an + implementation of FixedField for + the purpose of managing reading and + writing to a long-wide field in an + array of bytes.
      ShortFieldThe ShortField class is an + implementation of FixedField for + the purpose of managing reading and + writing to a short-wide field in an + array of bytes.
      ShortListThe ShortList class is a + work-around for functionality missing + in Java (see http://developer.java.sun.com/developer/bugParade/bugs/4487555.html + for details); it is a simple growable + array of shorts that gets + around the requirement of wrapping and + unwrapping shorts in + Short instances in order + to use the java.util.List + interface.
      ShortList mimics + the functionality of the + java.util.List interface + as much as possible.
      StringUtilThe StringUtil class + manages the processing of Unicode + strings.
      +
      5. +
    + Scenarios +

    + This section describes the scenarios of how the + POIFS classes and interfaces will be used to + convert an appropriate XML stream to a POIFS + output stream containing an HSSF document. +

    +

    + It is broken down as suggested by the following + scenario diagram: +

    +

    + +

    + + + + + + + + + + + + + + + + + +
    StepDescription
    1The Filesystem is + created by the client application.
    2The client + application tells the Filesystem to create a + document, providing an + InputStream and the name of the + document. This may be repeated several + times.
    3The client + application asks the Filesystem to write its + data to an OutputStream.
    +
      +
    1. +

      + Initialization +

      +

      + Initialization of the POIFS system is + shown in the following scenario diagram: +

      +

      + +

      + + + + + + + + + + + + + + + + + +
      StepDescription
      1The Filesystem + object, which is created for each + request to convert an appropriate XML + stream to a POIFS output stream + containing an HSSF document, creates + its PropertyTable.
      2The PropertyTable + creates its RootProperty + instance, making the RootProperty the + first Property + in its List of Property + instances.
      3The Filesystem + creates its HeaderBlock + instance. It should be noted that the + decision to create the HeaderBlock at + Filesystem initialization is + arbitrary; creation of the HeaderBlock + could easily and harmlessly be + postponed to the appropriate moment in + writing the + filesystem.
      +
      2. +
    2. +

      + Creating a + Document +

      +

      + Creating and adding a document to a POIFS + system is shown in the following scenario + diagram: +

      +

      + +

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      StepDescription
      1The Filesystem + instance creates a new Document + instance. It will store the newly + created Document in a + List of BATManaged + instances.
      2The Document reads + data from the provided + InputStream, storing the + data in DocumentBlock + instances. It keeps track of the byte + count as it reads the data.
      3The Document creates + a DocumentProperty + to keep track of its property + data. The byte count is stored in the + newly created DocumentProperty + instance.
      4The Filesystem + requests the newly created DocumentProperty + from the newly created Document + instance.
      5The Filesystem + sends the newly created DocumentProperty + to the Filesystem's PropertyTable + so that the PropertyTable can add the + DocumentProperty to its + List of Property + instances.
      6The Filesystem gets + the RootProperty + from its PropertyTable.
      7The Filesystem adds + the newly created DocumentProperty + to the RootProperty.
      +

      + Although typical deployment of the POIFS + system will only entail adding a single Document (the + workbook) to the Filesystem, there + is nothing in the design to prevent + multiple Documents from being added to the + Filesystem. This flexibility can be + employed to write summary information + document(s) in addition to the workbook. +

      +
      3. +
    3. +

      + Writing the + Filesystem +

      +

      + Writing the filesystem is shown in the + following scenario diagram: +

      +

      + +

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      StepDescription
      1The Filesystem adds + the PropertyTable + to its List of BATManaged + instances and calls the + PropertyTable's + preWrite + method. The action taken by the + PropertyTable is shown in the PropertyTable + preWrite scenario diagram.
      2The Filesystem + creates the BlockAllocationTable.
      3The Filesystem gets + the block count from the BATManaged + instance. These three steps are + repeated for each BATManaged + instance in the Filesystem's + List of BATManaged + instances (i.e., the Documents, in + order of their addition to the + Filesystem, followed by the PropertyTable).
      4The Filesystem + sends the block count to the BlockAllocationTable, + which adds the appropriate entries to + is IntList of + entries, returning the starting block + for the newly added entries.
      5The Filesystem + gives the start block number to the BATManaged + instance. If the BATManaged instance + is a Document, + it sets the start block field in its + DocumentProperty.
      6The Filesystem + tells the BlockAllocationTable + to create its BatBlocks.
      7The Filesystem + gives the BAT information to the HeaderBlock so + that it can set its BAT fields and, if + necessary, create XBAT blocks.
      8If the filesystem is + unusually large (over 7MB), the + HeaderBlock + will create XBAT blocks to contain the + BAT data that it cannot hold + directly. In this case, the Filesystem + tells the HeaderBlock where those + additional blocks will be stored.
      9The Filesystem + gives the PropertyTable + start block to the HeaderBlock.
      10The Filesystem + tells the BlockWritable + instance to write its blocks to the + provided + OutputStream.
      This + step is repeated for each + BlockWritable instance, in this + order:
      +
        +
      1. + The HeaderBlock. +
        2. +
      2. + Each Document, + in the order in which it was + added to the Filesystem. +
        3. +
      3. + The PropertyTable. +
        4. +
      4. + The BlockAllocationTable +
        5. +
      5. + The XBAT blocks created by the + HeaderBlock, + if any. +
        6. +
      +

      + PropertyTable + preWrite scenario diagram +

      +

      + +

      + + + + + + + + + + + + + + + + + + + + + + + + +
      StepDescription
      1The PropertyTable + calls setIndex for + each of its Property + instances, so that each Property now + knows its index within the + PropertyTable's List of + Property instances.
      2 The PropertyTable + requests the PropertyBlock + class to create an array of PropertyBlock + instances.
      3The PropertyBlock + calculates the number of empty Property + instances it needs to create and + creates them. The algorithm for the + number to create is:
      + block_count = (properties.size() + + 3) / 4;
      emptyPropertiesNeeded = + (block_count * 4) - + properties.size();
      4 The PropertyBlock + creates the required number of PropertyBlock + instances from the List + of Property + instances, including the newly created + empty Property + instances.
      5The PropertyTable + calls preWrite on + each of its Property + instances. For DocumentProperty + instances, this call is a no-op. For + the RootProperty, + the action taken is shown in the RootProperty + preWrite scenario diagram.
      +

      + RootProperty + preWrite scenario diagram +

      +

      + +

      + + + + + + + + + + + + + + + + + + +
      StepDescription
      1The RootProperty + sets its child property with the index + of the child Property that is + first in its List of + children.
      2The RootProperty + sets its child's next property field + with the index of the child's next + sibling in the RootProperty's + List of children. If the + child is the last in the + List, its next property + field is set to -1.These two steps are + repeated for each File in the RootProperty's + List of + children.
      3The RootProperty + sets its child's previous property + field with a value of + -1.
      +
      4. +
    +
    5. +
+ + diff --git a/src/documentation/content/xdocs/poifs/index.xml b/src/documentation/content/xdocs/poifs/index.xml new file mode 100644 index 0000000000..4b693475b6 --- /dev/null +++ b/src/documentation/content/xdocs/poifs/index.xml @@ -0,0 +1,58 @@ + + + + +
+ Apache POI - POIFS - Java implementation of the OLE 2 Compound Document format + Overview + + + + +
+ +
Overview +

POIFS is a pure Java implementation of the OLE 2 Compound + Document format.

+

By definition, all APIs developed by the POI project are + based somehow on the POIFS API.

+

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

+

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!". ;-)

+ +
+ + diff --git a/src/documentation/content/xdocs/poifs/usecases.xml b/src/documentation/content/xdocs/poifs/usecases.xml new file mode 100644 index 0000000000..8d2dea3ade --- /dev/null +++ b/src/documentation/content/xdocs/poifs/usecases.xml @@ -0,0 +1,653 @@ + + + + +
+ POIFS Use Cases + + + +
+ +
POIFS Use Cases +
Use Case 1: Read existing file system + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Primary Actor:POIFS client
Scope:POIFS
Level:Summary
Stakeholders and Interests: + POIFS client- wants to read content of file + system
+ POIFS - understands POIFS file system +
Precondition:None
Minimal Guarantee:None
Main Success Guarantee: + 1. POIFS client requests POIFS to read a POIFS file + system, providing an + InputStream + containing POIFS file system in question.
+ 2. POIFS reads from the + InputStream in + 512 byte blocks.
+ 3. POIFS verifies that the first block begins with + the well known signature + ( + 0xE11AB1A1E011CFD0)
+ 4. POIFS reads the Block Allocation Table from the + first block and, if necessary, from the XBAT + blocks.
+ 5. POIFS obtains the start block of the Property + Table and reads the Property Table (use case 9, + read file)
+ 6. POIFS reads the individual entries in the Property + Table
+ 7. POIFS obtains the start block of the Small Block + Allocation Table and reads the Small Block + Allocation Table (use case 9, read file)
+ 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)
+
Extensions: + 2a. If the last block read is not a 512 byte + block, the + InputStream is not that of + a POIFS file system, and POIFS throws an + appropriate exception. +
+ 3a. If the signature is incorrect, the + InputStream is not that of a POIFS + file system, and POIFS throws an appropriate + exception.
+
+
+
Use Case 2: Write file system + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Primary Actor:POIFS client
Scope:POIFS
Level:Summary
Stakeholders and Interests: + POIFS client- wants to write file system out.
+ POIFS - knows how to write file system out. +
Precondition: + 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) +
or
+ File system has been created (use case 3, create + new file system) +
Minimal Guarantee:None
Main Success Guarantee: + 1. POIFS client provides an + OutputStream + to write the file system to. +
+ 2. POIFS gets the sizes of the Property Table and + each file in the file system.
+ 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.
+ 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.
+ 5. POIFS creates a set of big blocks sufficient to + store the Block Allocation Table
+ 6. POIFS creates and writes the header block
+ 7. POIFS writes out the XBAT blocks, if needed.
+ 8. POIFS writes out the Small Block Array, if + needed
+ 9. POIFS writes out the Small Block Allocation Table, + if needed
+ 10. POIFS writes out the Property Table
+ 11. POIFS writes out the large files, if needed
+ 12. POIFS closes the OutputStream. +
Extensions: + 6a. Exceptions writing to the + OutputStream will be propagated back + to the POIFS client. +
+ 7a. Exceptions writing to the + OutputStream will be propagated back + to the POIFS client. +
+ 8a. Exceptions writing to the + OutputStream will be propagated back + to the POIFS client. +
+ 9a. Exceptions writing to the + OutputStream will be propagated back + to the POIFS client. +
+ 10a. Exceptions writing to the + OutputStream will be propagated back + to the POIFS client. +
+ 11a. Exceptions writing to the + OutputStream will be propagated back + to the POIFS client. +
+ 12a. Exceptions closing the + OutputStream will be propagated back + to the POIFS client. +
+
+
+
Use Case 3: Create new file system + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Primary Actor:POIFS client
Scope:POIFS
Level:Summary
Stakeholders and Interests: + POIFS client- wants to create a new file + system
+ POIFS - knows how to create a new file system +
Precondition:None
Minimal Guarantee:None
Main Success Guarantee: + POIFS creates an empty Property Table. +
Extensions:None
+
+
Use Case 4: Replace file in file system + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Primary Actor:POIFS client
Scope:POIFS
Level:Summary
Stakeholders and Interests: + 1. POIFS client- wants to replace an existing file in + the file system
+ 2. POIFS - knows how to manage the file system +
Precondition: + Either +

+ 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) +

or

+ 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) +
Minimal Guarantee:None
Main Success Guarantee: + 1. POIFS discards storage of the existing file.
+ 2. POIFS updates the existing file's entry in the + Property Table
+ 3. POIFS stores the new file's data +
Extensions: + 1a. POIFS throws an exception if the file does not + exist. +
+
+
Use Case 5: Delete file from file system + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Primary Actor:POIFS client
Scope:POIFS
Level:Summary
Stakeholders and Interests: + * POIFS client- wants to remove a file from a file + system
+ * POIFS - knows how to manage the file system +
Precondition: + Either

+ 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)
+
+ or
+
+ 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) +
Minimal Guarantee:None
Main Success Guarantee: + 1. POIFS discards the specified file's storage.
+ 2. POIFS discards the file's Property Table + entry. +
Extensions: + 1a. POIFS throws an exception if the file does not + exist. +
+
+
Use Case 6: Write new file to file system + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Primary Actor:POIFS client
Scope:POIFS
Level:Summary
Stakeholders and Interests: + * POIFS client- wants to add a new file to the file + system
+ * POIFS - knows how to manage the file system +
Precondition:The specified file does not yet exist in the file + system
Minimal Guarantee:None
Main Success Guarantee: + 1. The POIFS client provides a file name
+ 2. POIFS creates a new Property Table entry for the + new file
+ 3. POIFS provides the POIFS client with an + OutputStream to write to.
+ 4. The POIFS client writes data to the provided + OutputStream.
+ 5. The POIFS client closes the provided + OutputStream
+ 6. POIFS updates the Property Table entry with the + new file's size +
Extensions: + 1a. POIFS throws an exception if a file with the + specified name already exists in the file + system.
+ 1b. POIFS throws an exception if the file name is + too long. The limit on file name length is 31 + characters. +
+
+
Use Case 7: Read existing file from file system + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Primary Actor:POIFS client
Scope:POIFS
Level:Summary
Stakeholders and Interests: + * POIFS client- wants to read a file from the file + system
+ * POIFS - knows how to manage the file system +
Precondition: + * 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).
+ * The specified file exists in the file system. +
Minimal Guarantee:None
Main Success Guarantee: + * The POIFS client provides the name of a file to be read
+ * POIFS provides an InputStream to read from.
+ * The POIFS client reads from the InputStream.
+ * The POIFS client closes the InputStream. +
Extensions:1a. POIFS throws an exception if no file with the + specified name exists.
+
+
Use Case 8: Read file system directory + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Primary Actor:POIFS client
Scope:POIFS
Level:Summary
Stakeholders and Interests: + * POIFS client- wants to know what files exist in + the file system
+ * POIFS - knows how to manage the file system +
Precondition:The file system has been read (use case 1, read + existing file system) or created (use case 3, create + new file system)
Minimal Guarantee:None
Main Success Guarantee: + 1. The POIFS client requests the file system + directory. + 2. POIFS returns an Iterator. The + Iterator will not include the root + entry in the Property Table, and may be an + Iterator over an empty + Collection. +
Extensions:None
+
+
Use Case 9: Read file + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Primary Actor:POIFS
Scope:POIFS
Level:Summary
Stakeholders and Interests: + 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) +
Precondition:None
Minimal Guarantee:None
Main Success Guarantee: + 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
+ 2. POIFS returns an InputStream.
+ 3. Reads from the InputStream are + performed by walking the specified Block + Allocation Table and reading the blocks + indicated.
+ 4. POIFS closes the InputStream when + finished reading the file, or its client wants to + close the InputStream. +
Extensions: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.
+
+
Use Case 10: Rename existing file in the file system + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Primary Actor:POIFS client
Scope:POIFS
Level:Summary
Stakeholders and Interests: + * POIFS client- wants to rename an existing file in + the file system.
+ * POIFS - knows how to manage the file system. +
Precondition: + * 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.
+ * The specified file exists in the file system.
+ * The new name for the file does not duplicate + another file in the file system. +
Minimal Guarantee:None
Main Success Guarantee: + 1. POIFS updates the Property Table entry for the + specified file with its new name. +
Extensions: + * 1a. If the old file name is not in the file + system, POIFS throws an exception.
+ * 1b. If the new file name already exists in the + file system, POIFS throws an exception.
+ * 1c. If the new file name is too long (the limit is + 31 characters), POIFS throws an exception. +
+
+
+ + diff --git a/src/documentation/content/xdocs/references/book.xml b/src/documentation/content/xdocs/references/book.xml new file mode 100644 index 0000000000..f7ebc038a3 --- /dev/null +++ b/src/documentation/content/xdocs/references/book.xml @@ -0,0 +1,38 @@ + + + + + + + + + + + + + + + + + + diff --git a/src/documentation/content/xdocs/references/index.xml b/src/documentation/content/xdocs/references/index.xml new file mode 100644 index 0000000000..fdfa382b76 --- /dev/null +++ b/src/documentation/content/xdocs/references/index.xml @@ -0,0 +1,66 @@ + + + + + +
+ Live Sites using Poi + + + + + + + + +
+ + +
References + +
Live Sites using POI +

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.

+ +
+ +
Products/Projects using POI +

Publically available products/projects using POI include:

+
    +
  • JTimeTracker
    • +
+
+ +
File Format Descriptions +

POI depends on publically available documents describing various + file formats. The list below contains links to some of them.

+
    +
  • Wotsit's Format
    • +
+
+ +
+ + diff --git a/src/documentation/content/xdocs/resolutions/book.xml b/src/documentation/content/xdocs/resolutions/book.xml new file mode 100644 index 0000000000..8cd5b8d0c0 --- /dev/null +++ b/src/documentation/content/xdocs/resolutions/book.xml @@ -0,0 +1,40 @@ + + + + + + + + + + + + + + + + + + + + + diff --git a/src/documentation/content/xdocs/resolutions/index.xml b/src/documentation/content/xdocs/resolutions/index.xml new file mode 100644 index 0000000000..fbec750616 --- /dev/null +++ b/src/documentation/content/xdocs/resolutions/index.xml @@ -0,0 +1,55 @@ + + + + + +
+ Resolutions + About this section + + + +
+ + +
About Resolutions +

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

+

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

+

+ This section is intended mainly to reduce big waste of time + discussions from taking away from whats important...developing + POI! :-D +

+
+ + diff --git a/src/documentation/content/xdocs/resolutions/res001.xml b/src/documentation/content/xdocs/resolutions/res001.xml new file mode 100644 index 0000000000..177156f18b --- /dev/null +++ b/src/documentation/content/xdocs/resolutions/res001.xml @@ -0,0 +1,113 @@ + + + + + +
+ POI Resoluton + Resolution 001 - Minimal Coding Standards + + + +
+ + +
Resolution 001 - Minimal Coding Standards +
Majority Position +

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

+

+ Marc Johnson Authored the following resolution: +

+

+ 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): +

+
    +
  1. + All classes and interfaces MUST have, right at the + beginning of the file, the Apache Software License + 2.0 License Header. (see /legal/LICENSE). +
    2. +
  2. + 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. + + +
    3. +
  3. + 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. +
    4. +
+
+
Amendments (informal by extension and not by vote) +
License +

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

+
+
2 cents +

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

+
+
+
Dissent +

+ The motion was passed unanimously with no negative or + neutral votes. +

+
+
Comments +

+ Andy didn't feel like going through his mail and sucking + out the comments.. If there is anything you feel should + be added here do it yourself ;-). +

+
+
+ + diff --git a/src/documentation/content/xdocs/site.xml b/src/documentation/content/xdocs/site.xml new file mode 100644 index 0000000000..947c83e374 --- /dev/null +++ b/src/documentation/content/xdocs/site.xml @@ -0,0 +1,51 @@ + + + + + + + + + + + + + + + + + + + + + + diff --git a/src/documentation/content/xdocs/slideshow/book.xml b/src/documentation/content/xdocs/slideshow/book.xml new file mode 100644 index 0000000000..741b7bc6b9 --- /dev/null +++ b/src/documentation/content/xdocs/slideshow/book.xml @@ -0,0 +1,38 @@ + + + + + + + + + + + + + + + + + + + diff --git a/src/documentation/content/xdocs/slideshow/how-to-shapes.xml b/src/documentation/content/xdocs/slideshow/how-to-shapes.xml new file mode 100644 index 0000000000..40ef32aa75 --- /dev/null +++ b/src/documentation/content/xdocs/slideshow/how-to-shapes.xml @@ -0,0 +1,668 @@ + + + + + +
+ Busy Developers' Guide to HSLF drawing layer + + + +
+ +
Busy Developers' Guide to HSLF drawing layer +
Index of Features +
    +
  • How to create a new presentation and add new slides to it
    • +
  • How to retrieve or change slide size
    • +
  • How to get shapes contained in a particular slide
    • +
  • Drawing a shape on a slide
    • +
  • How to work with pictures
    • +
  • How to set slide title
    • +
  • How to work with slide/shape background
    • +
  • How to create bulleted lists
    • +
  • Hyperlinks
    • +
  • Tables
    • +
  • How to remove shapes
    • +
  • How to retrieve embedded OLE objects
    • +
  • How to retrieve embedded sounds
    • +
  • How to create shapes of arbitrary geometry
    • +
  • Shapes and Graphics2D
    • +
  • How to convert slides into images
    • +
  • Headers / Footers
    • +
+
+
Features + +
New Presentation + + //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(); + +
+ +
How to retrieve or change slide size + + 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(); + +
+ +
How to get shapes contained in a particular slide +

+ The following code demonstrates how to iterate over shapes for each slide. +

+ + SlideShow ppt = new SlideShow(new HSLFSlideShow("slideshow.ppt")); + //get slides + Slide[] slide = ppt.getSlides(); + for (int i = 0; i < slide.length; i++){ + Shape[] sh = slide[i].getShapes(); + for (int j = 0; j < 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 + } + } + } + +
+ +
Drawing a shape on a slide + + 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: java.awt.headless=true + (either via -Djava.awt.headless=true startup parameter or via System.setProperty("java.awt.headless", "true")). + +

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

+ + 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(); + + +
+ +
How to work with pictures + +

+ Currently, HSLF API supports the following types of pictures: +

+
    +
  • Windows Metafiles (WMF)
    • +
  • Enhanced Metafiles (EMF)
    • +
  • JPEG Interchange Format
    • +
  • Portable Network Graphics (PNG)
    • +
  • Macintosh PICT
    • +
+ + + SlideShow ppt = new SlideShow(new HSLFSlideShow("slideshow.ppt")); + + //extract all pictures contained in the presentation + PictureData[] pdata = ppt.getPictureData(); + for (int i = 0; i < 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 < 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(); + + +
+ +
How to set slide title + + 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(); + +

+ Below is the equivalent code in PowerPoint VBA: +

+ + Set myDocument = ActivePresentation.Slides(1) + myDocument.Shapes.AddTitle.TextFrame.TextRange.Text = "Hello, World!" + +
+ +
How to modify background of a slide master + + 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); + +
+
How to modify background of a slide + + 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); + +
+
How to modify background of a shape + + 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); + +
+ +
How to create bulleted lists + + 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(); + +
+ +
How to read hyperlinks from a slide show + + FileInputStream is = new FileInputStream("slideshow.ppt"); + SlideShow ppt = new SlideShow(is); + is.close(); + + Slide[] slide = ppt.getSlides(); + for (int j = 0; j < slide.length; j++) { + + //read hyperlinks from the text runs + TextRun[] txt = slide[j].getTextRuns(); + for (int k = 0; k < txt.length; k++) { + String text = txt[k].getText(); + Hyperlink[] links = txt[k].getHyperlinks(); + if(links != null) for (int l = 0; l < 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 < sh.length; k++) { + Hyperlink link = sh[k].getHyperlink(); + if(link != null) { + String title = link.getTitle(); + String address = link.getAddress(); + } + } + } + +
+ +
How to create tables + + //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 < data.length; i++) { + for (int j = 0; j < 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(); + + +
+ + +
How to remove shapes from a slide + + + Shape[] shape = slide.getShapes(); + for (int i = 0; i < shape.length; i++) { + + //remove the shape + boolean ok = slide.removeShape(shape[i]); + if(ok){ + //the shape was removed. Do something. + } + } + +
+ +
How to retrieve embedded OLE objects + + + Shape[] shape = slide.getShapes(); + for (int i = 0; i < 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()); + } + } + } + +
+ + +
How to retrieve embedded sounds + + + FileInputStream is = new FileInputStream(args[0]); + SlideShow ppt = new SlideShow(is); + is.close(); + + SoundData[] sound = ppt.getSoundData(); + for (int i = 0; i < 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(); + } + } + +
+ + +
How to create shapes of arbitrary geometry + + + 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); + +
+ + +
How to draw into a slide using Graphics2D + + 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. + + + 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 < 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(); + + +
+ + +
Export PowerPoint slides into java.awt.Graphics2D +

+ 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: +

+
    +
  • Java2D renders fonts differently vs PowerPoint. There are always some differences in the way the font glyphs are painted
    • +
  • HSLF uses java.awt.font.LineBreakMeasurer to break text into lines. PowerPoint may do it in a different way.
    • +
  • If a font from the presentation is not avaiable, then the JDK default font will be used.
    • +
+

+ Current Limitations: +

+
    +
  • Some types of shapes are not yet supported (WordArt, complex auto-shapes)
    • +
  • Only Bitmap images (PNG, JPEG, DIB) can be rendered in Java
    • +
+ + 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 < 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(); + } + + +
+ +
+ +
How to extract Headers / Footers from an existing presentation + + + 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 < 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(); + } + + } + +
+
How to set Headers / Footers + + + SlideShow ppt = new SlideShow(); + + //presentation-scope headers / footers + HeadersFooters hdd = ppt.getSlideHeadersFooters(); + hdd.setSlideNumberVisible(true); + hdd.setFootersText("Created by POI-HSLF"); + +
+
+ + diff --git a/src/documentation/content/xdocs/slideshow/index.xml b/src/documentation/content/xdocs/slideshow/index.xml new file mode 100644 index 0000000000..939ccb9961 --- /dev/null +++ b/src/documentation/content/xdocs/slideshow/index.xml @@ -0,0 +1,70 @@ + + + + + +
+ POI-HSLF and and POI-XLSF - Java API To Access Microsoft Powerpoint Format Files + Overview + + + + + +
+ + +
+ POI-HSLF + +

HSLF is the POI Project's pure Java implementation of the Powerpoint '97(-2007) file format.

+

HSLF provides a way to read, create or modify PowerPoint presentations. In particular, it provides: +

+
    +
  • api for data extraction (text, pictures, embedded objects, sounds)
    • +
  • usermodel api for creating, reading and modifying ppt files
    • +
+ + This code currently lives the + scratchpad area + 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. + +

The quick guide documentation provides + information on using this API. Comments and fixes gratefully accepted on the POI + dev mailing lists.

+
+
+ POI-XSLF +

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

+

+ Please note that XSLF is still in early development and is a subject to incompatible changes in future. +

+

+ A quick guide is available in the XSLF Cookbook +

+
+ + diff --git a/src/documentation/content/xdocs/slideshow/ppt-file-format.xml b/src/documentation/content/xdocs/slideshow/ppt-file-format.xml new file mode 100644 index 0000000000..d76fd7f543 --- /dev/null +++ b/src/documentation/content/xdocs/slideshow/ppt-file-format.xml @@ -0,0 +1,367 @@ + + + + + +
+ POI-HSLF - A Guide to the PowerPoint File Format + Overview + + + + +
+ + +
Records, Containers and Atoms +

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

+

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

+

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

+

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

+
+ +
Record Headers +

+ All records, be they containers or atoms, have the same standard + 8 byte header. It is: +

+
  • 1/2 byte container flag
    • +
  • 1.5 byte option field
    • +
  • 2 byte record type
    • +
  • 4 byte record length
+

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

+

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

+

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

+
+ +
CurrentUserAtom, UserEditAtom and PersistPtrIncrementalBlock +

aka Records that care about the byte level position of other records

+

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

+

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

+

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

+

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

+ +/-------------------------------\ +| 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 |==================/ + \---------------------------------/ + +

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

+

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

+ +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 + +
+ +
Paragraph and Text Styling +

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

+

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

+

+ (We don't currently know enough about master sheet styling + to write about it) +

+

+ 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) +

+

+ 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. (More on Fonts to be discovered) +

+
+ +
StyleTextPropAtom +

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

+

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

+

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

+

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

+

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

+ +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 + +
+ +
Fonts in PowerPoint +

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

+
+ +
FontEntityAtom +

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

+

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

+ +

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

+
+ + diff --git a/src/documentation/content/xdocs/slideshow/quick-guide.xml b/src/documentation/content/xdocs/slideshow/quick-guide.xml new file mode 100644 index 0000000000..7e6f9ae2e3 --- /dev/null +++ b/src/documentation/content/xdocs/slideshow/quick-guide.xml @@ -0,0 +1,136 @@ + + + + + +
+ POI-HSLF - A Quick Guide + Overview + + + +
+ + +
Basic Text Extraction +

For basic text extraction, make use of +org.apache.poi.hslf.extractor.PowerPointExtractor. It accepts a file or an input +stream. The getText() method can be used to get the text from the slides, and the getNotes() method can be used to get the text +from the notes. Finally, getText(true,true) will get the text +from both. +

+
+ +
Specific Text Extraction +

To get specific bits of text, first create a org.apache.poi.hslf.usermodel.SlideShow +(from a org.apache.poi.hslf.HSLFSlideShow, which accepts a file or an input +stream). Use getSlides() and getNotes() to get the slides and notes. +These can be queried to get their page ID (though they should be returned +in the right order).

+

You can then call getTextRuns() 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 TextRun, you can extract the text, and check +what type of text it is (eg Body, Title). You can allso call +getRichTextRuns(), which will return the +RichTextRuns that make up the TextRun. A +RichTextRun is made up of a sequence of text, all having the +same character and paragraph formatting. +

+
+ +
Poor Quality Text Extraction +

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 + org.apache.poi.hslf.extractor.QuickButCruddyTextExtractor + might be of use.

+

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!

+

There are two ways of getting the text back. + getTextAsString() will return a single string with all + the text in it. getTextAsVector() will return a + vector of strings, one for each text record found in the file. +

+
+ +
Changing Text +

It is possible to change the text via + TextRun.setText(String) or + RichTextRun.setText(String). It is not yet possible + to add additional TextRuns or RichTextRuns.

+

When calling TextRun.setText(String), all + the text will end up with the same formatting. When calling + RichTextRun.setText(String), the text will retain + the old formatting of that RichTextRun. +

+
+ +
Adding Slides +

You may add new slides by calling + SlideShow.createSlide(), 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). +

+
+ +
Guide to key classes +
    +
  • org.apache.poi.hslf.HSLFSlideShow + Handles reading in and writing out files. Calls + org.apache.poi.hslf.record.record to build a tree + of all the records in the file, which it allows access to. +
    • +
  • org.apache.poi.hslf.record.record + Base class of all records. Also provides the main record generation + code, which will build up a tree of records for a file. +
    • +
  • org.apache.poi.hslf.usermodel.SlideShow + Builds up model entries from the records, and presents a user facing + view of the file +
    • +
  • org.apache.poi.hslf.model.Slide + 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. +
    • +
  • org.apache.poi.hslf.model.TextRun + Holds all the Text in a given area of the Slide, and will + contain one or more RichTextRuns. +
    • +
  • org.apache.poi.hslf.usermodel.RichTextRun + Holds a run of text, all having the same character and + paragraph stylings. It is possible to modify text, and/or text stylings. +
    • +
  • org.apache.poi.hslf.extractor.PowerPointExtractor + Uses the model code to allow extraction of text from files +
    • +
  • org.apache.poi.hslf.extractor.QuickButCruddyTextExtractor + Uses the record code to extract all the text from files very fast, + but including deleted text (and other bits of Crud). +
    • +
+
+ + diff --git a/src/documentation/content/xdocs/slideshow/xslf-cookbook.xml b/src/documentation/content/xdocs/slideshow/xslf-cookbook.xml new file mode 100644 index 0000000000..da0e683e11 --- /dev/null +++ b/src/documentation/content/xdocs/slideshow/xslf-cookbook.xml @@ -0,0 +1,305 @@ + + + + + +
+ XSLF Cookbook + + + +
+ +
XSLF Cookbook +

+ This page offers a short introduction into the XSLF API. More examples can be found in the + XSLF Examples + in the POI SVN repository. +

+ + Please note that XSLF is still in early development and is a subject to incompatible changes in a future release. + +
Index of Features +
    +
  • Create a new presentation
    • +
  • Read an existing presentation
    • +
  • Create a slide with a predefined layout
    • +
  • Delete slide
    • +
  • Re-order slides
    • +
  • Change slide size
    • +
  • Read shapes
    • +
  • Add image
    • +
  • Read images contained in a presentation
    • +
  • Format text
    • +
  • Hyperlinks
    • +
  • Convert .pptx slides into images
    • +
  • Merge multiple presentations together
    • +
+
+
Cookbok + +
New Presentation +

+ The following code creates a new .pptx slide show and adds a blank slide to it: +

+ + //create a new empty slide show + XMLSlideShow ppt = new XMLSlideShow(); + + //add first slide + XSLFSlide blankSlide = ppt.createSlide(); + +
+ +
Read an existing presentation and append a slide to it + + XMLSlideShow ppt = new XMLSlideShow(new FileInputStream("slideshow.pptx")); + + //append a new slide to the end + XSLFSlide blankSlide = ppt.createSlide(); + +
+ + +
Create a new slide from a predefined slide layout + + 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"); + +
+ + +
Delete slide + + XMLSlideShow ppt = new XMLSlideShow(new FileInputStream("slideshow.pptx")); + + ppt.removeSlide(0); // 0-based index of a slide to be removed + +
+ + +
Re-order slides + + 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 + +
+ + +
How to retrieve or change slide size + + 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)); + +
+ +
How to read shapes contained in a particular slide +

+ The following code demonstrates how to iterate over shapes for each slide. +

+ + XMLSlideShow ppt = new XMLSlideShow(new FileInputStream("slideshow.pptx")); + //get slides + XSLFSlide[] slide = ppt.getSlides(); + for (int i = 0; i < slide.length; i++){ + XSLFShape[] sh = slide[i].getShapes(); + for (int j = 0; j < 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 + } + } + } + +
+ +
Add Image to Slide + + 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); + +
+ + +
Read Images contained within a presentation + + XMLSlideShow ppt = new XMLSlideShow(new FileInputStream("slideshow.pptx")); + for(XSLFPictureData data : ppt.getAllPictures()){ + byte[] bytes = data.getData(); + String fileName = data.getFileName(); + + } + +
+ + +
Basic text formatting + + 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); + +
+ +
How to read hyperlinks from a slide show + + 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"); + +
+ +
PPTX2PNG is an application that converts each slide of a .pptx slideshow into a PNG image + +Usage: PPTX2PNG [options] <pptx file> +Options: + -scale <float> scale factor (default is 1.0) + -slide <integer> 1-based index of a slide to render. Default is to render all slides. + +

How it works:

+

+ The XSLFSlide object implements a draw(Graphics2D graphics) method that recursively paints all shapes + in the slide into the supplied graphics canvas: +

+ + slide.draw(graphics); + +

+ 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 + PPTX2SVG + example demonstrates how to use Apache Batik to convert .pptx slides into SVG format. +

+
+ +
+ Merge multiple presentations together + + 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(); + +
+ +
+
+ + diff --git a/src/documentation/content/xdocs/spreadsheet/book.xml b/src/documentation/content/xdocs/spreadsheet/book.xml new file mode 100644 index 0000000000..15ac2a26f4 --- /dev/null +++ b/src/documentation/content/xdocs/spreadsheet/book.xml @@ -0,0 +1,53 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/src/documentation/content/xdocs/spreadsheet/chart.xml b/src/documentation/content/xdocs/spreadsheet/chart.xml new file mode 100644 index 0000000000..3dd3371287 --- /dev/null +++ b/src/documentation/content/xdocs/spreadsheet/chart.xml @@ -0,0 +1,1532 @@ + + + + + +
+ Chart record information + + + +
+ +
Introduction +

+ This document is intended as a work in progress for describing + our current understanding of how the chart records are are + written to produce a valid chart. +

+
+
Bar chart +

+ The following records detail the records written for a + 'simple' bar chart. +

+ + + ============================================ + rectype = 0xec, recsize = 0xc8 + -BEGIN DUMP--------------------------------- + 00000000 0F 00 02 F0 C0 00 00 00 10 00 08 F0 08 00 00 00 ................ + 00000010 02 00 00 00 02 04 00 00 0F 00 03 F0 A8 00 00 00 ................ + 00000020 0F 00 04 F0 28 00 00 00 01 00 09 F0 10 00 00 00 ....(........... + 00000030 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................ + 00000040 02 00 0A F0 08 00 00 00 00 04 00 00 05 00 00 00 ................ + 00000050 0F 00 04 F0 70 00 00 00 92 0C 0A F0 08 00 00 00 ....p........... + 00000060 02 04 00 00 00 0A 00 00 93 00 0B F0 36 00 00 00 ............6... + 00000070 7F 00 04 01 04 01 BF 00 08 00 08 00 81 01 4E 00 ..............N. + 00000080 00 08 83 01 4D 00 00 08 BF 01 10 00 11 00 C0 01 ....M........... + 00000090 4D 00 00 08 FF 01 08 00 08 00 3F 02 00 00 02 00 M.........?..... + 000000A0 BF 03 00 00 08 00 00 00 10 F0 12 00 00 00 00 00 ................ + 000000B0 04 00 C0 02 0A 00 F4 00 0E 00 66 01 20 00 E9 00 ..........f. ... + 000000C0 00 00 11 F0 00 00 00 00 ........ + -END DUMP----------------------------------- + recordid = 0xec, size =200 + [UNKNOWN RECORD:ec] + .id = ec + [/UNKNOWN RECORD] + + ============================================ + rectype = 0x5d, recsize = 0x1a + -BEGIN DUMP--------------------------------- + 00000000 15 00 12 00 05 00 02 00 11 60 00 00 00 00 B8 03 .........`...... + 00000010 87 03 00 00 00 00 00 00 00 00 .......... + -END DUMP----------------------------------- + recordid = 0x5d, size =26 + [UNKNOWN RECORD:5d] + .id = 5d + [/UNKNOWN RECORD] + + ============================================ + rectype = 0x809, recsize = 0x10 + -BEGIN DUMP--------------------------------- + 00000000 00 06 20 00 FE 1C CD 07 C9 40 00 00 06 01 00 00 .. ......@...... + -END DUMP----------------------------------- + recordid = 0x809, size =16 + [BOF RECORD] + .version = 600 + .type = 20 + .build = 1cfe + .buildyear = 1997 + .history = 40c9 + .requiredversion = 106 + [/BOF RECORD] + + ============================================ + rectype = 0x14, recsize = 0x0 + -BEGIN DUMP--------------------------------- + **NO RECORD DATA** + -END DUMP----------------------------------- + recordid = 0x14, size =0 + [HEADER] + .length = 0 + .header = null + [/HEADER] + + ============================================ + rectype = 0x15, recsize = 0x0 + -BEGIN DUMP--------------------------------- + **NO RECORD DATA** + -END DUMP----------------------------------- + recordid = 0x15, size =0 + [FOOTER] + .footerlen = 0 + .footer = null + [/FOOTER] + + ============================================ + rectype = 0x83, recsize = 0x2 + -BEGIN DUMP--------------------------------- + 00000000 00 00 .. + -END DUMP----------------------------------- + recordid = 0x83, size =2 + [HCENTER] + .hcenter = false + [/HCENTER] + + ============================================ + rectype = 0x84, recsize = 0x2 + -BEGIN DUMP--------------------------------- + 00000000 00 00 .. + -END DUMP----------------------------------- + recordid = 0x84, size =2 + [VCENTER] + .vcenter = false + [/VCENTER] + + ============================================ + rectype = 0xa1, recsize = 0x22 + -BEGIN DUMP--------------------------------- + 00000000 00 00 12 00 01 00 01 00 01 00 04 00 00 00 B8 03 ................ + 00000010 00 00 00 00 00 00 E0 3F 00 00 00 00 00 00 E0 3F .......?.......? + 00000020 0F 00 .. + -END DUMP----------------------------------- + recordid = 0xa1, size =34 + [PRINTSETUP] + .papersize = 0 + .scale = 18 + .pagestart = 1 + .fitwidth = 1 + .fitheight = 1 + .options = 4 + .ltor = false + .landscape = false + .valid = true + .mono = false + .draft = false + .notes = false + .noOrientat = false + .usepage = false + .hresolution = 0 + .vresolution = 952 + .headermargin = 0.5 + .footermargin = 0.5 + .copies = 15 + [/PRINTSETUP] + + + ============================================ + rectype = 0x33, recsize = 0x2 + -BEGIN DUMP--------------------------------- + 00000000 03 00 .. + -END DUMP----------------------------------- + recordid = 0x33, size =2 + [UNKNOWN RECORD:33] + .id = 33 + [/UNKNOWN RECORD] + + ============================================ + rectype = 0x1060, recsize = 0xa + -BEGIN DUMP--------------------------------- + 00000000 A0 23 08 16 C8 00 00 00 05 00 .#........ + -END DUMP----------------------------------- + recordid = 0x1060, size =10 + [FBI] + .xBasis = 0x23A0 (9120 ) + .yBasis = 0x1608 (5640 ) + .heightBasis = 0x00C8 (200 ) + .scale = 0x0000 (0 ) + .indexToFontTable = 0x0005 (5 ) + [/FBI] + + ============================================ + rectype = 0x1060, recsize = 0xa + -BEGIN DUMP--------------------------------- + 00000000 A0 23 08 16 C8 00 01 00 06 00 .#........ + -END DUMP----------------------------------- + recordid = 0x1060, size =10 + [FBI] + .xBasis = 0x23A0 (9120 ) + .yBasis = 0x1608 (5640 ) + .heightBasis = 0x00C8 (200 ) + .scale = 0x0001 (1 ) + .indexToFontTable = 0x0006 (6 ) + [/FBI] + + ============================================ + rectype = 0x12, recsize = 0x2 + -BEGIN DUMP--------------------------------- + 00000000 00 00 .. + -END DUMP----------------------------------- + recordid = 0x12, size =2 + [PROTECT] + .rowheight = 0 + [/PROTECT] + + ============================================ + Offset 0xf22 (3874) + rectype = 0x1001, recsize = 0x2 + -BEGIN DUMP--------------------------------- + 00000000 00 00 .. + -END DUMP----------------------------------- + recordid = 0x1001, size =2 + [UNITS] + .units = 0x0000 (0 ) + [/UNITS] + + ============================================ + Offset 0xf28 (3880) + rectype = 0x1002, recsize = 0x10 + -BEGIN DUMP--------------------------------- + 00000000 00 00 00 00 00 00 00 00 58 66 D0 01 40 66 22 01 ........Xf..@f". + -END DUMP----------------------------------- + recordid = 0x1002, size =16 + [CHART] + .x = 0x00000000 (0 ) + .y = 0x00000000 (0 ) + .width = 0x01D06658 (30434904 ) + .height = 0x01226640 (19031616 ) + [/CHART] + + ============================================ + Offset 0xf3c (3900) + rectype = 0x1033, recsize = 0x0 + -BEGIN DUMP--------------------------------- + **NO RECORD DATA** + -END DUMP----------------------------------- + recordid = 0x1033, size =0 + [BEGIN] + [/BEGIN] + + ============================================ + Offset 0xf40 (3904) + rectype = 0xa0, recsize = 0x4 + -BEGIN DUMP--------------------------------- + 00000000 01 00 01 00 .... + -END DUMP----------------------------------- + recordid = 0xa0, size =4 + [SCL] + .numerator = 0x0001 (1 ) + .denominator = 0x0001 (1 ) + [/SCL] + + + ============================================ + Offset 0xf48 (3912) + rectype = 0x1064, recsize = 0x8 + -BEGIN DUMP--------------------------------- + 00000000 00 00 01 00 00 00 01 00 ........ + -END DUMP----------------------------------- + recordid = 0x1064, size =8 + [PLOTGROWTH] + .horizontalScale = 0x00010000 (65536 ) + .verticalScale = 0x00010000 (65536 ) + [/PLOTGROWTH] + + ============================================ + Offset 0xf54 (3924) + rectype = 0x1032, recsize = 0x4 + -BEGIN DUMP--------------------------------- + 00000000 00 00 02 00 .... + -END DUMP----------------------------------- + recordid = 0x1032, size =4 + [FRAME] + .borderType = 0x0000 (0 ) + .options = 0x0002 (2 ) + .autoSize = false + .autoPosition = true + [/FRAME] + + ============================================ + Offset 0xf5c (3932) + rectype = 0x1033, recsize = 0x0 + -BEGIN DUMP--------------------------------- + **NO RECORD DATA** + -END DUMP----------------------------------- + recordid = 0x1033, size =0 + [BEGIN] + [/BEGIN] + + ============================================ + Offset 0xf60 (3936) + rectype = 0x1007, recsize = 0xc + -BEGIN DUMP--------------------------------- + 00000000 00 00 00 00 00 00 FF FF 09 00 4D 00 ..........M. + -END DUMP----------------------------------- + recordid = 0x1007, size =12 + [LINEFORMAT] + .lineColor = 0x00000000 (0 ) + .linePattern = 0x0000 (0 ) + .weight = 0xFFFF (-1 ) + .format = 0x0009 (9 ) + .auto = true + .drawTicks = false + .unknown = false + .colourPaletteIndex = 0x004D (77 ) + [/LINEFORMAT] + + ============================================ + Offset 0xf70 (3952) + rectype = 0x100a, recsize = 0x10 + -BEGIN DUMP--------------------------------- + 00000000 FF FF FF 00 00 00 00 00 01 00 01 00 4E 00 4D 00 ............N.M. + -END DUMP----------------------------------- + recordid = 0x100a, size =16 + [AREAFORMAT] + .foregroundColor = 0x00FFFFFF (16777215 ) + .backgroundColor = 0x00000000 (0 ) + .pattern = 0x0001 (1 ) + .formatFlags = 0x0001 (1 ) + .automatic = true + .invert = false + .forecolorIndex = 0x004E (78 ) + .backcolorIndex = 0x004D (77 ) + [/AREAFORMAT] + + ============================================ + Offset 0xf84 (3972) + rectype = 0x1034, recsize = 0x0 + -BEGIN DUMP--------------------------------- + **NO RECORD DATA** + -END DUMP----------------------------------- + recordid = 0x1034, size =0 + [END] + [/END] + + ============================================ + Offset 0xf88 (3976) + rectype = 0x1003, recsize = 0xc + -BEGIN DUMP--------------------------------- + 00000000 01 00 01 00 20 00 1F 00 01 00 00 00 .... ....... + -END DUMP----------------------------------- + recordid = 0x1003, size =12 + [SERIES] + .categoryDataType = 0x0001 (1 ) + .valuesDataType = 0x0001 (1 ) + .numCategories = 0x0020 (32 ) + .numValues = 0x001F (31 ) + .bubbleSeriesType = 0x0001 (1 ) + .numBubbleValues = 0x0000 (0 ) + [/SERIES] + + ============================================ + Offset 0xf98 (3992) + rectype = 0x1033, recsize = 0x0 + -BEGIN DUMP--------------------------------- + **NO RECORD DATA** + -END DUMP----------------------------------- + recordid = 0x1033, size =0 + [BEGIN] + [/BEGIN] + + + ============================================ + Offset 0xf9c (3996) + rectype = 0x1051, recsize = 0x8 + -BEGIN DUMP--------------------------------- + 00000000 00 01 00 00 00 00 00 00 ........ + -END DUMP----------------------------------- + recordid = 0x1051, size =8 + [AI] + .linkType = 0x00 (0 ) + .referenceType = 0x01 (1 ) + .options = 0x0000 (0 ) + .customNumberFormat = false + .indexNumberFmtRecord = 0x0000 (0 ) + .formulaOfLink = (org.apache.poi.hssf.record.LinkedDataFormulaField@1ee3914 ) + [/AI] + + ============================================ + Offset 0xfa8 (4008) + rectype = 0x1051, recsize = 0x13 + -BEGIN DUMP--------------------------------- + 00000000 01 02 00 00 00 00 0B 00 3B 00 00 00 00 1E 00 01 ........;....... + 00000010 00 01 00 ... + -END DUMP----------------------------------- + recordid = 0x1051, size =19 + [AI] + .linkType = 0x01 (1 ) + .referenceType = 0x02 (2 ) + .options = 0x0000 (0 ) + .customNumberFormat = false + .indexNumberFmtRecord = 0x0000 (0 ) + .formulaOfLink = (org.apache.poi.hssf.record.LinkedDataFormulaField@e5855a ) + [/AI] + + ============================================ + Offset 0xfbf (4031) + rectype = 0x1051, recsize = 0x13 + -BEGIN DUMP--------------------------------- + 00000000 02 02 00 00 69 01 0B 00 3B 00 00 00 00 1F 00 00 ....i...;....... + 00000010 00 00 00 ... + -END DUMP----------------------------------- + recordid = 0x1051, size =19 + [AI] + .linkType = 0x02 (2 ) + .referenceType = 0x02 (2 ) + .options = 0x0000 (0 ) + .customNumberFormat = false + .indexNumberFmtRecord = 0x0169 (361 ) + .formulaOfLink = (org.apache.poi.hssf.record.LinkedDataFormulaField@95fd19 ) + [/AI] + + ============================================ + Offset 0xfd6 (4054) + rectype = 0x1051, recsize = 0x8 + -BEGIN DUMP--------------------------------- + 00000000 03 01 00 00 00 00 00 00 ........ + -END DUMP----------------------------------- + recordid = 0x1051, size =8 + [AI] + .linkType = 0x03 (3 ) + .referenceType = 0x01 (1 ) + .options = 0x0000 (0 ) + .customNumberFormat = false + .indexNumberFmtRecord = 0x0000 (0 ) + .formulaOfLink = (org.apache.poi.hssf.record.LinkedDataFormulaField@11b9fb1 ) + [/AI] + + ============================================ + Offset 0xfe2 (4066) + rectype = 0x1006, recsize = 0x8 + -BEGIN DUMP--------------------------------- + 00000000 FF FF 00 00 00 00 00 00 ........ + -END DUMP----------------------------------- + recordid = 0x1006, size =8 + [DATAFORMAT] + .pointNumber = 0xFFFF (-1 ) + .seriesIndex = 0x0000 (0 ) + .seriesNumber = 0x0000 (0 ) + .formatFlags = 0x0000 (0 ) + .useExcel4Colors = false + [/DATAFORMAT] + + ============================================ + Offset 0xfee (4078) + rectype = 0x1033, recsize = 0x0 + -BEGIN DUMP--------------------------------- + **NO RECORD DATA** + -END DUMP----------------------------------- + recordid = 0x1033, size =0 + [BEGIN] + [/BEGIN] + + ============================================ + Offset 0xff2 (4082) + rectype = 0x105f, recsize = 0x2 + -BEGIN DUMP--------------------------------- + 00000000 00 00 .. + -END DUMP----------------------------------- + recordid = 0x105f, size =2 + [UNKNOWN RECORD] + .id = 105f + [/UNKNOWN RECORD] + + ============================================ + Offset 0xff8 (4088) + rectype = 0x1034, recsize = 0x0 + -BEGIN DUMP--------------------------------- + **NO RECORD DATA** + -END DUMP----------------------------------- + recordid = 0x1034, size =0 + [END] + [/END] + + ============================================ + Offset 0xffc (4092) + rectype = 0x1045, recsize = 0x2 + -BEGIN DUMP--------------------------------- + 00000000 00 00 .. + -END DUMP----------------------------------- + recordid = 0x1045, size =2 + [SeriesToChartGroup] + .chartGroupIndex = 0x0000 (0 ) + [/SeriesToChartGroup] + + ============================================ + Offset 0x1002 (4098) + rectype = 0x1034, recsize = 0x0 + -BEGIN DUMP--------------------------------- + **NO RECORD DATA** + -END DUMP----------------------------------- + recordid = 0x1034, size =0 + [END] + [/END] + + ============================================ + Offset 0x1006 (4102) + rectype = 0x1044, recsize = 0x4 + -BEGIN DUMP--------------------------------- + 00000000 0A 00 00 00 .... + -END DUMP----------------------------------- + recordid = 0x1044, size =4 + [SHTPROPS] + .flags = 0x000A (10 ) + .chartTypeManuallyFormatted = false + .plotVisibleOnly = true + .doNotSizeWithWindow = false + .defaultPlotDimensions = true + .autoPlotArea = false + .empty = 0x00 (0 ) + [/SHTPROPS] + + ============================================ + Offset 0x100e (4110) + rectype = 0x1024, recsize = 0x2 + -BEGIN DUMP--------------------------------- + 00000000 02 00 .. + -END DUMP----------------------------------- + recordid = 0x1024, size =2 + [DEFAULTTEXT] + .categoryDataType = 0x0002 (2 ) + [/DEFAULTTEXT] + + ============================================ + Offset 0x1014 (4116) + rectype = 0x1025, recsize = 0x20 + -BEGIN DUMP--------------------------------- + 00000000 02 02 01 00 00 00 00 00 DB FF FF FF C4 FF FF FF ................ + 00000010 00 00 00 00 00 00 00 00 B1 00 4D 00 50 2B 00 00 ..........M.P+.. + -END DUMP----------------------------------- + recordid = 0x1025, size =32 + [TEXT] + .horizontalAlignment = 0x02 (2 ) + .verticalAlignment = 0x02 (2 ) + .displayMode = 0x0001 (1 ) + .rgbColor = 0x00000000 (0 ) + .x = 0xFFFFFFDB (-37 ) + .y = 0xFFFFFFC4 (-60 ) + .width = 0x00000000 (0 ) + .height = 0x00000000 (0 ) + .options1 = 0x00B1 (177 ) + .autoColor = true + .showKey = false + .showValue = false + .vertical = false + .autoGeneratedText = true + .generated = true + .autoLabelDeleted = false + .autoBackground = true + .rotation = 0 + .showCategoryLabelAsPercentage = false + .showValueAsPercentage = false + .showBubbleSizes = false + .showLabel = false + .indexOfColorValue = 0x004D (77 ) + .options2 = 0x2B50 (11088 ) + .dataLabelPlacement = 0 + .textRotation = 0x0000 (0 ) + [/TEXT] + + ============================================ + Offset 0x1038 (4152) + rectype = 0x1033, recsize = 0x0 + -BEGIN DUMP--------------------------------- + **NO RECORD DATA** + -END DUMP----------------------------------- + recordid = 0x1033, size =0 + [BEGIN] + [/BEGIN] + + + ============================================ + Offset 0x103c (4156) + rectype = 0x104f, recsize = 0x14 + -BEGIN DUMP--------------------------------- + 00000000 02 00 02 00 00 00 00 00 00 00 00 00 00 00 00 00 ................ + 00000010 00 00 00 00 .... + -END DUMP----------------------------------- + recordid = 0x104f, size =20 + [UNKNOWN RECORD] + .id = 104f + [/UNKNOWN RECORD] + + ============================================ + Offset 0x1054 (4180) + rectype = 0x1026, recsize = 0x2 + -BEGIN DUMP--------------------------------- + 00000000 05 00 .. + -END DUMP----------------------------------- + recordid = 0x1026, size =2 + [FONTX] + .fontIndex = 0x0005 (5 ) + [/FONTX] + + ============================================ + Offset 0x105a (4186) + rectype = 0x1051, recsize = 0x8 + -BEGIN DUMP--------------------------------- + 00000000 00 01 00 00 00 00 00 00 ........ + -END DUMP----------------------------------- + recordid = 0x1051, size =8 + [AI] + .linkType = 0x00 (0 ) + .referenceType = 0x01 (1 ) + .options = 0x0000 (0 ) + .customNumberFormat = false + .indexNumberFmtRecord = 0x0000 (0 ) + .formulaOfLink = (org.apache.poi.hssf.record.LinkedDataFormulaField@913fe2 ) + [/AI] + + ============================================ + Offset 0x1066 (4198) + rectype = 0x1034, recsize = 0x0 + -BEGIN DUMP--------------------------------- + **NO RECORD DATA** + -END DUMP----------------------------------- + recordid = 0x1034, size =0 + [END] + [/END] + + ============================================ + Offset 0x106a (4202) + rectype = 0x1024, recsize = 0x2 + -BEGIN DUMP--------------------------------- + 00000000 03 00 .. + -END DUMP----------------------------------- + recordid = 0x1024, size =2 + [DEFAULTTEXT] + .categoryDataType = 0x0003 (3 ) + [/DEFAULTTEXT] + + ============================================ + Offset 0x1070 (4208) + rectype = 0x1025, recsize = 0x20 + -BEGIN DUMP--------------------------------- + 00000000 02 02 01 00 00 00 00 00 DB FF FF FF C4 FF FF FF ................ + 00000010 00 00 00 00 00 00 00 00 B1 00 4D 00 50 2B 00 00 ..........M.P+.. + -END DUMP----------------------------------- + recordid = 0x1025, size =32 + [TEXT] + .horizontalAlignment = 0x02 (2 ) + .verticalAlignment = 0x02 (2 ) + .displayMode = 0x0001 (1 ) + .rgbColor = 0x00000000 (0 ) + .x = 0xFFFFFFDB (-37 ) + .y = 0xFFFFFFC4 (-60 ) + .width = 0x00000000 (0 ) + .height = 0x00000000 (0 ) + .options1 = 0x00B1 (177 ) + .autoColor = true + .showKey = false + .showValue = false + .vertical = false + .autoGeneratedText = true + .generated = true + .autoLabelDeleted = false + .autoBackground = true + .rotation = 0 + .showCategoryLabelAsPercentage = false + .showValueAsPercentage = false + .showBubbleSizes = false + .showLabel = false + .indexOfColorValue = 0x004D (77 ) + .options2 = 0x2B50 (11088 ) + .dataLabelPlacement = 0 + .textRotation = 0x0000 (0 ) + [/TEXT] + + ============================================ + Offset 0x1094 (4244) + rectype = 0x1033, recsize = 0x0 + -BEGIN DUMP--------------------------------- + **NO RECORD DATA** + -END DUMP----------------------------------- + recordid = 0x1033, size =0 + [BEGIN] + [/BEGIN] + + ============================================ + Offset 0x1098 (4248) + rectype = 0x104f, recsize = 0x14 + -BEGIN DUMP--------------------------------- + 00000000 02 00 02 00 00 00 00 00 00 00 00 00 00 00 00 00 ................ + 00000010 00 00 00 00 .... + -END DUMP----------------------------------- + recordid = 0x104f, size =20 + [UNKNOWN RECORD] + .id = 104f + [/UNKNOWN RECORD] + + ============================================ + Offset 0x10b0 (4272) + rectype = 0x1026, recsize = 0x2 + -BEGIN DUMP--------------------------------- + 00000000 06 00 .. + -END DUMP----------------------------------- + recordid = 0x1026, size =2 + [FONTX] + .fontIndex = 0x0006 (6 ) + [/FONTX] + + ============================================ + Offset 0x10b6 (4278) + rectype = 0x1051, recsize = 0x8 + -BEGIN DUMP--------------------------------- + 00000000 00 01 00 00 00 00 00 00 ........ + -END DUMP----------------------------------- + recordid = 0x1051, size =8 + [AI] + .linkType = 0x00 (0 ) + .referenceType = 0x01 (1 ) + .options = 0x0000 (0 ) + .customNumberFormat = false + .indexNumberFmtRecord = 0x0000 (0 ) + .formulaOfLink = (org.apache.poi.hssf.record.LinkedDataFormulaField@1f934ad ) + [/AI] + + ============================================ + Offset 0x10c2 (4290) + rectype = 0x1034, recsize = 0x0 + -BEGIN DUMP--------------------------------- + **NO RECORD DATA** + -END DUMP----------------------------------- + recordid = 0x1034, size =0 + [END] + [/END] + + ============================================ + Offset 0x10c6 (4294) + rectype = 0x1046, recsize = 0x2 + -BEGIN DUMP--------------------------------- + 00000000 01 00 .. + -END DUMP----------------------------------- + recordid = 0x1046, size =2 + [AXISUSED] + .numAxis = 0x0001 (1 ) + [/AXISUSED] + + ============================================ + Offset 0x10cc (4300) + rectype = 0x1041, recsize = 0x12 + -BEGIN DUMP--------------------------------- + 00000000 00 00 DF 01 00 00 DD 00 00 00 B3 0B 00 00 56 0B ..............V. + 00000010 00 00 .. + -END DUMP----------------------------------- + recordid = 0x1041, size =18 + [AXISPARENT] + .axisType = 0x0000 (0 ) + .x = 0x000001DF (479 ) + .y = 0x000000DD (221 ) + .width = 0x00000BB3 (2995 ) + .height = 0x00000B56 (2902 ) + [/AXISPARENT] + + ============================================ + Offset 0x10e2 (4322) + rectype = 0x1033, recsize = 0x0 + -BEGIN DUMP--------------------------------- + **NO RECORD DATA** + -END DUMP----------------------------------- + recordid = 0x1033, size =0 + [BEGIN] + [/BEGIN] + + ============================================ + Offset 0x10e6 (4326) + rectype = 0x104f, recsize = 0x14 + -BEGIN DUMP--------------------------------- + 00000000 02 00 02 00 3A 00 00 00 5E 00 00 00 58 0D 00 00 ....:...^...X... + 00000010 E5 0E 00 00 .... + -END DUMP----------------------------------- + recordid = 0x104f, size =20 + [UNKNOWN RECORD] + .id = 104f + [/UNKNOWN RECORD] + + ============================================ + Offset 0x10fe (4350) + rectype = 0x101d, recsize = 0x12 + -BEGIN DUMP--------------------------------- + 00000000 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................ + 00000010 00 00 .. + -END DUMP----------------------------------- + recordid = 0x101d, size =18 + [AXIS] + .axisType = 0x0000 (0 ) + .reserved1 = 0x00000000 (0 ) + .reserved2 = 0x00000000 (0 ) + .reserved3 = 0x00000000 (0 ) + .reserved4 = 0x00000000 (0 ) + [/AXIS] + + ============================================ + Offset 0x1114 (4372) + rectype = 0x1033, recsize = 0x0 + -BEGIN DUMP--------------------------------- + **NO RECORD DATA** + -END DUMP----------------------------------- + recordid = 0x1033, size =0 + [BEGIN] + [/BEGIN] + + ============================================ + Offset 0x1118 (4376) + rectype = 0x1020, recsize = 0x8 + -BEGIN DUMP--------------------------------- + 00000000 01 00 01 00 01 00 01 00 ........ + -END DUMP----------------------------------- + recordid = 0x1020, size =8 + [CATSERRANGE] + .crossingPoint = 0x0001 (1 ) + .labelFrequency = 0x0001 (1 ) + .tickMarkFrequency = 0x0001 (1 ) + .options = 0x0001 (1 ) + .valueAxisCrossing = true + .crossesFarRight = false + .reversed = false + [/CATSERRANGE] + + ============================================ + Offset 0x1124 (4388) + rectype = 0x1062, recsize = 0x12 + -BEGIN DUMP--------------------------------- + 00000000 1C 90 39 90 02 00 00 00 01 00 00 00 00 00 1C 90 ..9............. + 00000010 FF 00 .. + -END DUMP----------------------------------- + recordid = 0x1062, size =18 + [AXCEXT] + .minimumCategory = 0x901C (-28644 ) + .maximumCategory = 0x9039 (-28615 ) + .majorUnitValue = 0x0002 (2 ) + .majorUnit = 0x0000 (0 ) + .minorUnitValue = 0x0001 (1 ) + .minorUnit = 0x0000 (0 ) + .baseUnit = 0x0000 (0 ) + .crossingPoint = 0x901C (-28644 ) + .options = 0x00FF (255 ) + .defaultMinimum = true + .defaultMaximum = true + .defaultMajor = true + .defaultMinorUnit = true + .isDate = true + .defaultBase = true + .defaultCross = true + .defaultDateSettings = true + [/AXCEXT] + + ============================================ + Offset 0x113a (4410) + rectype = 0x101e, recsize = 0x1e + -BEGIN DUMP--------------------------------- + 00000000 02 00 03 01 00 00 00 00 00 00 00 00 00 00 00 00 ................ + 00000010 00 00 00 00 00 00 00 00 23 00 4D 00 2D 00 ........#.M.-. + -END DUMP----------------------------------- + recordid = 0x101e, size =30 + [TICK] + .majorTickType = 0x02 (2 ) + .minorTickType = 0x00 (0 ) + .labelPosition = 0x03 (3 ) + .background = 0x01 (1 ) + .labelColorRgb = 0x00000000 (0 ) + .zero1 = 0x0000 (0 ) + .zero2 = 0x0000 (0 ) + .options = 0x0023 (35 ) + .autoTextColor = true + .autoTextBackground = true + .rotation = 0 + .autorotate = true + .tickColor = 0x004D (77 ) + .zero3 = 0x002D (45 ) + [/TICK] + + ============================================ + Offset 0x115c (4444) + rectype = 0x1034, recsize = 0x0 + -BEGIN DUMP--------------------------------- + **NO RECORD DATA** + -END DUMP----------------------------------- + recordid = 0x1034, size =0 + [END] + [/END] + + ============================================ + Offset 0x1160 (4448) + rectype = 0x101d, recsize = 0x12 + -BEGIN DUMP--------------------------------- + 00000000 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................ + 00000010 00 00 .. + -END DUMP----------------------------------- + recordid = 0x101d, size =18 + [AXIS] + .axisType = 0x0001 (1 ) + .reserved1 = 0x00000000 (0 ) + .reserved2 = 0x00000000 (0 ) + .reserved3 = 0x00000000 (0 ) + .reserved4 = 0x00000000 (0 ) + [/AXIS] + + + ============================================ + Offset 0x1176 (4470) + rectype = 0x1033, recsize = 0x0 + -BEGIN DUMP--------------------------------- + **NO RECORD DATA** + -END DUMP----------------------------------- + recordid = 0x1033, size =0 + [BEGIN] + [/BEGIN] + + ============================================ + Offset 0x117a (4474) + rectype = 0x101f, recsize = 0x2a + -BEGIN DUMP--------------------------------- + 00000000 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................ + 00000010 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................ + 00000020 00 00 00 00 00 00 00 00 1F 01 .......... + -END DUMP----------------------------------- + recordid = 0x101f, size =42 + [VALUERANGE] + .minimumAxisValue = (0.0 ) + .maximumAxisValue = (0.0 ) + .majorIncrement = (0.0 ) + .minorIncrement = (0.0 ) + .categoryAxisCross = (0.0 ) + .options = 0x011F (287 ) + .automaticMinimum = true + .automaticMaximum = true + .automaticMajor = true + .automaticMinor = true + .automaticCategoryCrossing = true + .logarithmicScale = false + .valuesInReverse = false + .crossCategoryAxisAtMaximum = false + .reserved = true + [/VALUERANGE] + + ============================================ + Offset 0x11a8 (4520) + rectype = 0x101e, recsize = 0x1e + -BEGIN DUMP--------------------------------- + 00000000 02 00 03 01 00 00 00 00 00 00 00 00 00 00 00 00 ................ + 00000010 00 00 00 00 00 00 00 00 23 00 4D 00 00 00 ........#.M... + -END DUMP----------------------------------- + recordid = 0x101e, size =30 + [TICK] + .majorTickType = 0x02 (2 ) + .minorTickType = 0x00 (0 ) + .labelPosition = 0x03 (3 ) + .background = 0x01 (1 ) + .labelColorRgb = 0x00000000 (0 ) + .zero1 = 0x0000 (0 ) + .zero2 = 0x0000 (0 ) + .options = 0x0023 (35 ) + .autoTextColor = true + .autoTextBackground = true + .rotation = 0 + .autorotate = true + .tickColor = 0x004D (77 ) + .zero3 = 0x0000 (0 ) + [/TICK] + + ============================================ + Offset 0x11ca (4554) + rectype = 0x1021, recsize = 0x2 + -BEGIN DUMP--------------------------------- + 00000000 01 00 .. + -END DUMP----------------------------------- + recordid = 0x1021, size =2 + [AXISLINEFORMAT] + .axisType = 0x0001 (1 ) + [/AXISLINEFORMAT] + + ============================================ + Offset 0x11d0 (4560) + rectype = 0x1007, recsize = 0xc + -BEGIN DUMP--------------------------------- + 00000000 00 00 00 00 00 00 FF FF 09 00 4D 00 ..........M. + -END DUMP----------------------------------- + recordid = 0x1007, size =12 + [LINEFORMAT] + .lineColor = 0x00000000 (0 ) + .linePattern = 0x0000 (0 ) + .weight = 0xFFFF (-1 ) + .format = 0x0009 (9 ) + .auto = true + .drawTicks = false + .unknown = false + .colourPaletteIndex = 0x004D (77 ) + [/LINEFORMAT] + + ============================================ + Offset 0x11e0 (4576) + rectype = 0x1034, recsize = 0x0 + -BEGIN DUMP--------------------------------- + **NO RECORD DATA** + -END DUMP----------------------------------- + recordid = 0x1034, size =0 + [END] + [/END] + + ============================================ + Offset 0x11e4 (4580) + rectype = 0x1035, recsize = 0x0 + -BEGIN DUMP--------------------------------- + **NO RECORD DATA** + -END DUMP----------------------------------- + recordid = 0x1035, size =0 + [PLOTAREA] + [/PLOTAREA] + + ============================================ + Offset 0x11e8 (4584) + rectype = 0x1032, recsize = 0x4 + -BEGIN DUMP--------------------------------- + 00000000 00 00 03 00 .... + -END DUMP----------------------------------- + recordid = 0x1032, size =4 + [FRAME] + .borderType = 0x0000 (0 ) + .options = 0x0003 (3 ) + .autoSize = true + .autoPosition = true + [/FRAME] + + ============================================ + Offset 0x11f0 (4592) + rectype = 0x1033, recsize = 0x0 + -BEGIN DUMP--------------------------------- + **NO RECORD DATA** + -END DUMP----------------------------------- + recordid = 0x1033, size =0 + [BEGIN] + [/BEGIN] + + ============================================ + Offset 0x11f4 (4596) + rectype = 0x1007, recsize = 0xc + -BEGIN DUMP--------------------------------- + 00000000 80 80 80 00 00 00 00 00 00 00 17 00 ............ + -END DUMP----------------------------------- + recordid = 0x1007, size =12 + [LINEFORMAT] + .lineColor = 0x00808080 (8421504 ) + .linePattern = 0x0000 (0 ) + .weight = 0x0000 (0 ) + .format = 0x0000 (0 ) + .auto = false + .drawTicks = false + .unknown = false + .colourPaletteIndex = 0x0017 (23 ) + [/LINEFORMAT] + + ============================================ + Offset 0x1204 (4612) + rectype = 0x100a, recsize = 0x10 + -BEGIN DUMP--------------------------------- + 00000000 C0 C0 C0 00 00 00 00 00 01 00 00 00 16 00 4F 00 ..............O. + -END DUMP----------------------------------- + recordid = 0x100a, size =16 + [AREAFORMAT] + .foregroundColor = 0x00C0C0C0 (12632256 ) + .backgroundColor = 0x00000000 (0 ) + .pattern = 0x0001 (1 ) + .formatFlags = 0x0000 (0 ) + .automatic = false + .invert = false + .forecolorIndex = 0x0016 (22 ) + .backcolorIndex = 0x004F (79 ) + [/AREAFORMAT] + + ============================================ + Offset 0x1218 (4632) + rectype = 0x1034, recsize = 0x0 + -BEGIN DUMP--------------------------------- + **NO RECORD DATA** + -END DUMP----------------------------------- + recordid = 0x1034, size =0 + [END] + [/END] + + ============================================ + Offset 0x121c (4636) + rectype = 0x1014, recsize = 0x14 + -BEGIN DUMP--------------------------------- + 00000000 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................ + 00000010 00 00 00 00 .... + -END DUMP----------------------------------- + recordid = 0x1014, size =20 + [CHARTFORMAT] + .xPosition = 0 + .yPosition = 0 + .width = 0 + .height = 0 + .grBit = 0 + [/CHARTFORMAT] + + ============================================ + Offset 0x1234 (4660) + rectype = 0x1033, recsize = 0x0 + -BEGIN DUMP--------------------------------- + **NO RECORD DATA** + -END DUMP----------------------------------- + recordid = 0x1033, size =0 + [BEGIN] + [/BEGIN] + + ============================================ + Offset 0x1238 (4664) + rectype = 0x1017, recsize = 0x6 + -BEGIN DUMP--------------------------------- + 00000000 00 00 96 00 00 00 ...... + -END DUMP----------------------------------- + recordid = 0x1017, size =6 + [BAR] + .barSpace = 0x0000 (0 ) + .categorySpace = 0x0096 (150 ) + .formatFlags = 0x0000 (0 ) + .horizontal = false + .stacked = false + .displayAsPercentage = false + .shadow = false + [/BAR] + + ============================================ + Offset 0x1242 (4674) + rectype = 0x1022, recsize = 0xa + -BEGIN DUMP--------------------------------- + 00000000 00 00 00 00 00 00 00 00 0F 00 .......... + -END DUMP----------------------------------- + recordid = 0x1022, size =10 + [UNKNOWN RECORD] + .id = 1022 + [/UNKNOWN RECORD] + + ============================================ + Offset 0x1250 (4688) + rectype = 0x1015, recsize = 0x14 + -BEGIN DUMP--------------------------------- + 00000000 D6 0D 00 00 1E 06 00 00 B5 01 00 00 D5 00 00 00 ................ + 00000010 03 01 1F 00 .... + -END DUMP----------------------------------- + recordid = 0x1015, size =20 + [LEGEND] + .xAxisUpperLeft = 0x00000DD6 (3542 ) + .yAxisUpperLeft = 0x0000061E (1566 ) + .xSize = 0x000001B5 (437 ) + .ySize = 0x000000D5 (213 ) + .type = 0x03 (3 ) + .spacing = 0x01 (1 ) + .options = 0x001F (31 ) + .autoPosition = true + .autoSeries = true + .autoXPositioning = true + .autoYPositioning = true + .vertical = true + .dataTable = false + [/LEGEND] + + ============================================ + Offset 0x1268 (4712) + rectype = 0x1033, recsize = 0x0 + -BEGIN DUMP--------------------------------- + **NO RECORD DATA** + -END DUMP----------------------------------- + recordid = 0x1033, size =0 + [BEGIN] + [/BEGIN] + + ============================================ + Offset 0x126c (4716) + rectype = 0x104f, recsize = 0x14 + -BEGIN DUMP--------------------------------- + 00000000 05 00 02 00 D6 0D 00 00 1E 06 00 00 00 00 00 00 ................ + 00000010 00 00 00 00 .... + -END DUMP----------------------------------- + recordid = 0x104f, size =20 + [UNKNOWN RECORD] + .id = 104f + [/UNKNOWN RECORD] + + ============================================ + Offset 0x1284 (4740) + rectype = 0x1025, recsize = 0x20 + -BEGIN DUMP--------------------------------- + 00000000 02 02 01 00 00 00 00 00 DB FF FF FF C4 FF FF FF ................ + 00000010 00 00 00 00 00 00 00 00 B1 00 4D 00 70 37 00 00 ..........M.p7.. + -END DUMP----------------------------------- + recordid = 0x1025, size =32 + [TEXT] + .horizontalAlignment = 0x02 (2 ) + .verticalAlignment = 0x02 (2 ) + .displayMode = 0x0001 (1 ) + .rgbColor = 0x00000000 (0 ) + .x = 0xFFFFFFDB (-37 ) + .y = 0xFFFFFFC4 (-60 ) + .width = 0x00000000 (0 ) + .height = 0x00000000 (0 ) + .options1 = 0x00B1 (177 ) + .autoColor = true + .showKey = false + .showValue = false + .vertical = false + .autoGeneratedText = true + .generated = true + .autoLabelDeleted = false + .autoBackground = true + .rotation = 0 + .showCategoryLabelAsPercentage = false + .showValueAsPercentage = false + .showBubbleSizes = false + .showLabel = false + .indexOfColorValue = 0x004D (77 ) + .options2 = 0x3770 (14192 ) + .dataLabelPlacement = 0 + .textRotation = 0x0000 (0 ) + [/TEXT] + + ============================================ + Offset 0x12a8 (4776) + rectype = 0x1033, recsize = 0x0 + -BEGIN DUMP--------------------------------- + **NO RECORD DATA** + -END DUMP----------------------------------- + recordid = 0x1033, size =0 + [BEGIN] + [/BEGIN] + + ============================================ + Offset 0x12ac (4780) + rectype = 0x104f, recsize = 0x14 + -BEGIN DUMP--------------------------------- + 00000000 02 00 02 00 00 00 00 00 00 00 00 00 00 00 00 00 ................ + 00000010 00 00 00 00 .... + -END DUMP----------------------------------- + recordid = 0x104f, size =20 + [UNKNOWN RECORD] + .id = 104f + [/UNKNOWN RECORD] + + ============================================ + Offset 0x12c4 (4804) + rectype = 0x1051, recsize = 0x8 + -BEGIN DUMP--------------------------------- + 00000000 00 01 00 00 00 00 00 00 ........ + -END DUMP----------------------------------- + recordid = 0x1051, size =8 + [AI] + .linkType = 0x00 (0 ) + .referenceType = 0x01 (1 ) + .options = 0x0000 (0 ) + .customNumberFormat = false + .indexNumberFmtRecord = 0x0000 (0 ) + .formulaOfLink = (org.apache.poi.hssf.record.LinkedDataFormulaField@1d05c81 ) + [/AI] + + ============================================ + Offset 0x12d0 (4816) + rectype = 0x1034, recsize = 0x0 + -BEGIN DUMP--------------------------------- + **NO RECORD DATA** + -END DUMP----------------------------------- + recordid = 0x1034, size =0 + [END] + [/END] + + + ============================================ + Offset 0x12d4 (4820) + rectype = 0x1034, recsize = 0x0 + -BEGIN DUMP--------------------------------- + **NO RECORD DATA** + -END DUMP----------------------------------- + recordid = 0x1034, size =0 + [END] + [/END] + + ============================================ + Offset 0x12d8 (4824) + rectype = 0x1034, recsize = 0x0 + -BEGIN DUMP--------------------------------- + **NO RECORD DATA** + -END DUMP----------------------------------- + recordid = 0x1034, size =0 + [END] + [/END] + + ============================================ + Offset 0x12dc (4828) + rectype = 0x1034, recsize = 0x0 + -BEGIN DUMP--------------------------------- + **NO RECORD DATA** + -END DUMP----------------------------------- + recordid = 0x1034, size =0 + [END] + [/END] + + ============================================ + Offset 0x12e0 (4832) + rectype = 0x1034, recsize = 0x0 + -BEGIN DUMP--------------------------------- + **NO RECORD DATA** + -END DUMP----------------------------------- + recordid = 0x1034, size =0 + [END] + [/END] + + ============================================ + rectype = 0x200, recsize = 0xe + -BEGIN DUMP--------------------------------- + 00000000 00 00 00 00 1F 00 00 00 00 00 01 00 00 00 .............. + -END DUMP----------------------------------- + recordid = 0x200, size =14 + [DIMENSIONS] + .firstrow = 0 + .lastrow = 1f + .firstcol = 0 + .lastcol = 1 + .zero = 0 + [/DIMENSIONS] + + ============================================ + rectype = 0x1065, recsize = 0x2 + -BEGIN DUMP--------------------------------- + 00000000 02 00 .. + -END DUMP----------------------------------- + recordid = 0x1065, size =2 + [SINDEX] + .index = 0x0002 (2 ) + [/SINDEX] + + ============================================ + rectype = 0x1065, recsize = 0x2 + -BEGIN DUMP--------------------------------- + 00000000 01 00 .. + -END DUMP----------------------------------- + recordid = 0x1065, size =2 + [SINDEX] + .index = 0x0001 (1 ) + [/SINDEX] + + ============================================ + rectype = 0x1065, recsize = 0x2 + -BEGIN DUMP--------------------------------- + 00000000 03 00 .. + -END DUMP----------------------------------- + recordid = 0x1065, size =2 + [SINDEX] + .index = 0x0003 (3 ) + [/SINDEX] + + ============================================ + rectype = 0xa, recsize = 0x0 + -BEGIN DUMP--------------------------------- + **NO RECORD DATA** + -END DUMP----------------------------------- + recordid = 0xa, size =0 + [EOF] + [/EOF] + + + +

+ The next section breaks those records down into an easier + to read format: +

+ +[UNKNOWN RECORD:ec] +[UNKNOWN RECORD:5d] +[BOF RECORD] + [HEADER] + [FOOTER] + [HCENTER] + [VCENTER] + [PRINTSETUP] + [UNKNOWN RECORD:33] + [FBI] + [FBI] + [PROTECT] + [UNITS] + [CHART] + [BEGIN] + [SCL] // zoom magnification + [PLOTGROWTH] // font scaling + [FRAME] // border around text + [BEGIN] // default line and area format + [LINEFORMAT] + [AREAFORMAT] + [END] + [SERIES] // start of series + [BEGIN] + [AI] // LINK_TYPE_TITLE_OR_TEXT + [AI] // LINK_TYPE_VALUES + [AI] // LINK_TYPE_CATEGORIES + [AI] // ?? + [DATAFORMAT] // Formatting applies to series? + [BEGIN] // ?? + [UNKNOWN RECORD] + [END] + [SeriesToChartGroup] // Used to support > 1 chart? + [END] + [SHTPROPS] // Some defaults for how chart is displayed. + [DEFAULTTEXT] // Describes the characteristics of the next + // record + [TEXT] // Details of the text that follows in the + // next section + [BEGIN] + [UNKNOWN RECORD] // POS record... looks like I missed this one. + // docs seem to indicate it's better to use + // defaults... + [FONTX] // index to font record. + [AI] // link to text? seems to be linking to nothing + [END] + [DEFAULTTEXT] // contains a category type of 3 which is not + // documented (sigh). + [TEXT] // defines position, color etc for text on chart. + [BEGIN] + [UNKNOWN RECORD] // Another pos record + [FONTX] // font + [AI] // reference type is DIRECT (not sure what this + // means) + [END] + [AXISUSED] // number of axis on the chart. + [AXISPARENT] // axis size and location + [BEGIN] // beginning of axis details + [UNKNOWN RECORD] // Another pos record. + [AXIS] // Category axis + [BEGIN] + [CATSERRANGE] // defines tick marks and other stuff + [AXCEXT] // unit information + [TICK] // tick formating characteristics + [END] + [AXIS] // Value axis + [BEGIN] + [VALUERANGE] // defines tick marks and other stuff + [TICK] // tick formating characteristics + [AXISLINEFORMAT] // major grid line axis format + [LINEFORMAT] // what do the lines look like? + [END] + [PLOTAREA] // marks that the frame following belongs + // to the frame. + [FRAME] // border + [BEGIN] + [LINEFORMAT] // border line + [AREAFORMAT] // border area + [END] + [CHARTFORMAT] // marks a chart group + [BEGIN] + [BAR] // indicates a bar chart + [UNKNOWN RECORD] // apparently this record is ignoreable + [LEGEND] // positioning for the legend + [BEGIN] + [UNKNOWN RECORD] // another position record. + [TEXT] // details of the text that follows + // in the next section + [BEGIN] + [UNKNOWN RECORD] // yet another pos record + [AI] // another link (of type direct) + [END] + [END] + [END] + [END] + [END] + [DIMENSIONS] + [SINDEX] + [SINDEX] + [SINDEX] +[EOF] + +

+ Just a quick note on some of the unknown records: +

+
    +
  • EC: MSODRAWING - A Microsoft drawing record. (Need to + track down where this is documented).
    • +
  • 5D: OBJ: Description of a drawing object. (This is going to + be a PITA to implement).
    • +
  • 33: Not documented. :-(
    • +
  • 105f: Not documented. :-(
    • +
  • 104f: POS: Position record (should be able to safely leave this out).
    • +
  • 1022: CHARTFORMATLINK: Can be left out.
    • +
+

+ It is currently suspected that many of those records could be + left out when generating a bar chart from scratch. The way + we will be proceeding with this is to write code that generates + most of these records and then start removing them to see + how this effects the chart in excel. +

+
+
Inserting the Chart into the Workbook +
    +
  • + Unknown record (sid=00eb) is inserted before the SST + record. +
    • +
+ + ============================================ + rectype = 0xeb, recsize = 0x5a + -BEGIN DUMP--------------------------------- + 00000000 0F 00 00 F0 52 00 00 00 00 00 06 F0 18 00 00 00 ....R........... + 00000010 01 08 00 00 02 00 00 00 02 00 00 00 01 00 00 00 ................ + 00000020 01 00 00 00 03 00 00 00 33 00 0B F0 12 00 00 00 ........3....... + 00000030 BF 00 08 00 08 00 81 01 09 00 00 08 C0 01 40 00 ..............@. + 00000040 00 08 40 00 1E F1 10 00 00 00 0D 00 00 08 0C 00 ..@............. + 00000050 00 08 17 00 00 08 F7 00 00 10 .......... + -END DUMP----------------------------------- + recordid = 0xeb, size =90 + [UNKNOWN RECORD:eb] + .id = eb + [/UNKNOWN RECORD] + + ============================================ + +
    +
  • + Any extra font records are inserted as needed +
    • +
  • + Chart records inserted after DBCell records. +
    • +
+
+ + diff --git a/src/documentation/content/xdocs/spreadsheet/converting.xml b/src/documentation/content/xdocs/spreadsheet/converting.xml new file mode 100644 index 0000000000..c8c891bd94 --- /dev/null +++ b/src/documentation/content/xdocs/spreadsheet/converting.xml @@ -0,0 +1,232 @@ + + + + + +
+ Upgrading to POI 3.5, including converting existing HSSF Usermodel code to SS Usermodel (for XSSF and HSSF) + + + +
+ +
Things that have to be changed when upgrading to POI 3.5 +

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.

+
org.apache.poi.hssf.usermodel.HSSFFormulaEvaluator.CellValue +

Annoyingly, java will not let you access a static inner class via + a child of the parent one. So, all references to + org.apache.poi.hssf.usermodel.HSSFFormulaEvaluator.CellValue + will need to be changed to + org.apache.poi.ss.usermodel.FormulaEvaluator.CellValue +

+
+
org.apache.poi.hssf.usermodel.HSSFRow.MissingCellPolicy +

Annoyingly, java will not let you access a static inner class via + a child of the parent one. So, all references to + org.apache.poi.hssf.usermodel.HSSFRow.MissingCellPolicy + will need to be changed to + org.apache.poi.ss.usermodel.Row.MissingCellPolicy +

+
+
DDF and org.apache.poi.hssf.record.RecordFormatException +

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, + org.apache.poi.util.RecordFormatException

+

In addition, org.apache.poi.hssf.record.RecordFormatException + has been changed to inherit from the new + org.apache.poi.util.RecordFormatException, so you may + wish to change catches of the hssf version to the new util version. +

+
+
+
Converting existing HSSF Usermodel code to SS Usermodel (for XSSF and HSSF) + +
Why change? +

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.

+

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.

+
+
org.apache.poi.ss.usermodel +

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.

+
+
Constructors +

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

+

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.

+
+
Other Code +

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.

+
+
+
Worked Examples +
Old HSSF Code + +
+
New, generic SS Usermodel Code + +
+
+ + diff --git a/src/documentation/content/xdocs/spreadsheet/diagram1.xml b/src/documentation/content/xdocs/spreadsheet/diagram1.xml new file mode 100644 index 0000000000..fbbe1f66c3 --- /dev/null +++ b/src/documentation/content/xdocs/spreadsheet/diagram1.xml @@ -0,0 +1,40 @@ + + + + + +
+ HSSF + Overview + + + + +
+ + +
+ Usermodel Class Diagram by Matthew Young +

+ Usermodel +

+
+ + diff --git a/src/documentation/content/xdocs/spreadsheet/diagrams.xml b/src/documentation/content/xdocs/spreadsheet/diagrams.xml new file mode 100644 index 0000000000..1c1f2a76f9 --- /dev/null +++ b/src/documentation/content/xdocs/spreadsheet/diagrams.xml @@ -0,0 +1,56 @@ + + + + + +
+ HSSF + Overview + + + + +
+ + +
Overview +

+ This section is intended for diagrams (UML/etc) that help + explain HSSF. +

+
    +
  • + HSSF usermodel class diagram - + by Matthew Young (myoung at westernasset dot com) +
    • +
+

+ Have more? Add a new "bug" to the bug database with [DOCUMENTATION] + prefacing the description and a link to the file on an http server + somewhere. If you don't have your own webserver, then you can email it + to (acoliver at apache dot org) provided its < 5MB. Diagrams should be + in some format that can be read at least on Linux and Windows. Diagrams + that can be edited are preferrable, but lets face it, there aren't too + many good affordable UML tools yet! And no they don't HAVE to be UML... + just useful. +

+
+ + diff --git a/src/documentation/content/xdocs/spreadsheet/eval-devguide.xml b/src/documentation/content/xdocs/spreadsheet/eval-devguide.xml new file mode 100644 index 0000000000..99eecff4e0 --- /dev/null +++ b/src/documentation/content/xdocs/spreadsheet/eval-devguide.xml @@ -0,0 +1,376 @@ + + + + + +
+ Developing Formula Evaluation + + +
+ +
Introduction +

This document is for developers wishing to contribute to the + FormulaEvaluator API functionality.

+

When evaluating workbooks you may encounter a org.apache.poi.ss.formula.eval.NotImplementedException + which indicates that a function is not (yet) supported by POI. Is there a workaround? + Yes, the POI framework makes it easy to add implementation of new functions. Prior to POI-3.8 + you had to checkout the source code from svn and make a custom build with your function implementation. + Since POI-3.8 you can register new functions in run-time. +

+

Currently, contribution is desired for implementing the standard MS + excel functions. Place holder classes for these have been created, + contributors only need to insert implementation for the + individual "evaluate()" methods that do the actual evaluation.

+
+ +
Overview of FormulaEvaluator +

Briefly, a formula string (along with the sheet and workbook that + form the context in which the formula is evaluated) is first parsed + into RPN tokens using the FormulaParser class . + (If you dont know what RPN tokens are, now is a good time to + read + this.) +

+
The big picture +

RPN tokens are mapped to Eval classes. (Class hierarchy for the Evals + is best understood if you view the class diagram in a class diagram + viewer.) Depending on the type of RPN token (also called as Ptgs + henceforth since that is what the FormulaParser calls the classes) a + specific type of Eval wrapper is constructed to wrap the RPN token and + is pushed on the stack.... UNLESS the Ptg is an OperationPtg. If it is an + OperationPtg, an OperationEval instance is created for the specific + type of OperationPtg. And depending on how many operands it takes, + that many Evals are popped of the stack and passed in an array to + the OperationEval instance's evaluate method which returns an Eval + of subtype ValueEval.Thus an operation in the formula is evaluated.

+ An Eval is of subinterface ValueEval or OperationEval. + Operands are always ValueEvals, Operations are always OperationEvals. +

OperationEval.evaluate(Eval[]) returns an Eval which is supposed + to be of type ValueEval (actually since ValueEval is an interface, + the return value is instance of one of the implementations of + ValueEval). The valueEval resulting from evaluate() is pushed on the + stack and the next RPN token is evaluated.... this continues till + eventually there are no more RPN tokens at which point, if the formula + string was correctly parsed, there should be just one Eval on the + stack - which contains the result of evaluating the formula.

+

Of course I glossed over the details of how AreaPtg and ReferencePtg + are handled a little differently, but the code should be self + explanatory for that. Very briefly, the cells included in AreaPtg and + RefPtg are examined and their values are populated in individual + ValueEval objects which are set into the AreaEval and RefEval (ok, + since AreaEval and RefEval are interfaces, the implementations of + AreaEval and RefEval - but you'll figure all that out from the code)

+

OperationEvals for the standard operators have been implemented and tested.

+
+
+ +
What functions are supported? +

+ As of Feb 2012, POI supports about 140 built-in functions, + see Appendix A for the full list. + You can programmatically list supported / unsuported functions using the following helper methods: +

+ + // list of functions that POI can evaluate + Collection<String> supportedFuncs = WorkbookEvaluator.getSupportedFunctionNames(); + + // list of functions that are not supported by POI + Collection<String> unsupportedFuncs = WorkbookEvaluator.getNotSupportedFunctionNames(); + + +
+ +
Two base interfaces to start your implementation +

+ All Excel formula function classes implement either + org.apache.poi.hssf.record.formula.functions.Function or + org.apache.poi.hssf.record.formula.functions.FreeRefFunction interface. + + Function is a commonn interface for the functions defined in the binary Excel format (BIFF8): these are "classic" Excel functions like SUM, COUNT, LOOKUP, etc. + FreeRefFunction is a common interface for the functions from the Excel Analysis Toolpack and for User-Defined Functions. + In the future these two interfaces are expected be unified into one, but for now you have to start your implementation from two slightly different roots. + +

+
+ +
Which interface to start from? +

+ You are about to implement a function XXX and don't know which interface to start from: Function or FreeRefFunction. + Use the following code to check whether your function is from the excel Analysis Toolpack: +

+ + if(AnalysisToolPack.isATPFunction(functionName)){ + // the function implements org.apache.poi.hssf.record.formula.functions.Function + } else { + // the function implements org.apache.poi.hssf.record.formula.functions.FreeRefFunction + } + +
+ + +
Walkthrough of an "evaluate()" implementation. +

Here is the fun part: lets walk through the implementation of the excel function SQRT() +

+

+ AnalysisToolPack.isATPFunction("SQRTPI") returns false so the base interface is Function. + + There are sub-interfaces that make life easier when implementing numeric functions or functions + with fixed number of arguments, 1-arg, 2-arg and 3-arg function: +

+
    +
  • org.apache.poi.hssf.record.formula.functions.NumericFunction
    • +
  • org.apache.poi.hssf.record.formula.functions.Fixed1ArgFunction
    • +
  • org.apache.poi.hssf.record.formula.functions.Fixed2ArgFunction
    • +
  • org.apache.poi.hssf.record.formula.functions.Fixed3ArgFunction
    • +
  • org.apache.poi.hssf.record.formula.functions.Fixed4ArgFunction
    • +
+

+ Since SQRTPI takes exactly one argument we start our implementation from org.apache.poi.hssf.record.formula.functions.Fixed1ArgFunction: +

+ + + Function SQRTPI = new Fixed1ArgFunction() { + public ValueEval evaluate(int srcRowIndex, int srcColumnIndex, ValueEval arg0) { + try { + // Retrieves a single value from a variety of different argument types according to standard + // Excel rules. Does not perform any type conversion. + ValueEval ve = OperandResolver.getSingleValue(arg0, srcRowIndex, srcColumnIndex); + + // Applies some conversion rules if the supplied value is not already a number. + // Throws EvaluationException(#VALUE!) if the supplied parameter is not a number + double arg = OperandResolver.coerceValueToDouble(ve); + + // this where all the heavy-lifting happens + double result = Math.sqrt(arg*Math.PI); + + // Excel uses the error code #NUM! instead of IEEE NaN and Infinity, + // so when a numeric function evaluates to Double.NaN or Double.Infinity, + // be sure to translate the result to the appropriate error code + if (Double.isNaN(result) || Double.isInfinite(result)) { + throw new EvaluationException(ErrorEval.NUM_ERROR); + } + + return new NumberEval(result); + } catch (EvaluationException e){ + return e.getErrorEval(); + } + } + } + + +

Now when the implementation is ready we need to register it in the formula evaluator:

+ + WorkbookEvaluator.registerFunction("SQRTPI", SQRTPI); + + +

Voila! The formula evaluator now recognizes SQRTPI!

+ +
+ +
Floating-point Arithmetic in Excel +

Excel uses the IEEE Standard for Double Precision Floating Point numbers + except two cases where it does not adhere to IEEE 754: +

+
    +
  1. Positive/Negative Infinities: Infinities occur when you divide by 0. + Excel does not support infinities, rather, it gives a #DIV/0! error in these cases. +
    2. +
  2. Not-a-Number (NaN): NaN is used to represent invalid operations + (such as infinity/infinity, infinity-infinity, or the square root of -1). + NaNs allow a program to continue past an invalid operation. + Excel instead immediately generates an error such as #NUM! or #DIV/0!. +
    3. +
+

Be aware of these two cases when saving results of your scientific calculations in Excel: + “where are my Infinities and NaNs? They are gone!” +

+
+ +
Testing Framework +

Automated testing of the implemented Function is easy. + The source code for this is in the file: o.a.p.h.record.formula.GenericFormulaTestCase.java + This class has a reference to the test xls file (not /a/ test xls, /the/ test xls :) + which may need to be changed for your environment. Once you do that, in the test xls, + locate the entry for the function that you have implemented and enter different tests + in a cell in the FORMULA row. Then copy the "value of" the formula that you entered in the + cell just below it (this is easily done in excel as: + [copy the formula cell] > [go to cell below] > Edit > Paste Special > Values > "ok"). + You can enter multiple such formulas and paste their values in the cell below and the + test framework will automatically test if the formula evaluation matches the expected + value (Again, hard to put in words, so if you will, please take time to quickly look + at the code and the currently entered tests in the patch attachment "FormulaEvalTestData.xls" + file). +

+
+ + +
+ Appendix A +

Functions supported by POI ( as of Feb 2012)

+ + ABS + ACOS + ACOSH + ADDRESS + AND + ASIN + ASINH + ATAN + ATAN2 + ATANH + AVEDEV + AVERAGE + CEILING + CHAR + CHOOSE + CLEAN + COLUMN + COLUMNS + COMBIN + CONCATENATE + COS + COSH + COUNT + COUNTA + COUNTBLANK + COUNTIF + DATE + DAY + DAYS360 + DEGREES + DEVSQ + DOLLAR + ERROR.TYPE + EVEN + EXACT + EXP + FACT + FALSE + FIND + FLOOR + FV + HLOOKUP + HOUR + HYPERLINK + IF + INDEX + INDIRECT + INT + IRR + ISBLANK + ISERROR + ISEVEN + ISLOGICAL + ISNA + ISNONTEXT + ISNUMBER + ISODD + ISREF + ISTEXT + LARGE + LEFT + LEN + LN + LOG + LOG10 + LOOKUP + LOWER + MATCH + MAX + MAXA + MEDIAN + MID + MIN + MINA + MINUTE + MOD + MODE + MONTH + MROUND + NA + NETWORKDAYS + NOT + NOW + NPER + NPV + ODD + OFFSET + OR + PI + PMT + POISSON + POWER + PRODUCT + PV + RADIANS + RAND + RANDBETWEEN + RANK + RATE + REPLACE + RIGHT + ROUND + ROUNDDOWN + ROUNDUP + ROW + ROWS + SEARCH + SECOND + SIGN + SIN + SINH + SMALL + SQRT + STDEV + SUBSTITUTE + SUBTOTAL + SUM + SUMIF + SUMIFS + SUMPRODUCT + SUMSQ + SUMX2MY2 + SUMX2PY2 + SUMXMY2 + T + TAN + TANH + TEXT + TIME + TODAY + TRIM + TRUE + TRUNC + UPPER + VALUE + VAR + VARP + VLOOKUP + WEEKDAY + WORKDAY + YEAR + YEARFRAC + +
+ + diff --git a/src/documentation/content/xdocs/spreadsheet/eval.xml b/src/documentation/content/xdocs/spreadsheet/eval.xml new file mode 100644 index 0000000000..b078879058 --- /dev/null +++ b/src/documentation/content/xdocs/spreadsheet/eval.xml @@ -0,0 +1,354 @@ + + + + + +
+ Formula Evaluation +
+ +
Introduction +

The POI formula evaluation code enables you to calculate the result of + formulas in Excels sheets read-in, or created in POI. This document explains + how to use the API to evaluate your formulas. +

+
+ + +
Why do I need to evaluate formulas? +

The Excel file format (both .xls and .xlsx) stores a "cached" result for + every formula along with the formula itself. This means that when the file + is opened, it can be quickly displayed, without needing to spend a long + time calculating all of the formula results. It also means that when reading + a file through Apache POI, the result is quickly available to you too! +

+

After making changes with Apache POI to either Formula Cells themselves, + or those that they depend on, you should normally perform a Formula + Evaluation to have these "cached" results updated. This is normally done + after all changes have been performed, but before you write the file out. + If you don't do this, there's a good chance that when you open the file in + Excel, until you go to the cell and hit enter or F9, you will either see + the old value or '#VALUE!' for the cell. (Sometimes Excel will notice + itself, and trigger a recalculation on load, but unless you know you are + using volatile functions it's generally best to trigger a Recalulation + through POI) +

+
+ + +
Status +

The code currently provides implementations for all the arithmatic operators. + It also provides implementations for approx. 140 built in + functions in Excel. The framework however makes it easy to add + implementation of new functions. See the Formula + evaluation development guide and javadocs + for details.

+

Both HSSFWorkbook and XSSFWorkbook are supported, so you can + evaluate formulas on both .xls and .xlsx files.

+

Note that user-defined functions are not supported, and is not likely to done + any time soon... at least, not till there is a VB implementation in Java! +

+
+
User API How-TO +

The following code demonstrates how to use the FormulaEvaluator + in the context of other POI excel reading code. +

+

There are several ways in which you can use the FormulaEvalutator API.

+ + +
Using FormulaEvaluator.<strong>evaluate</strong>(Cell cell) +

This evaluates a given cell, and returns the new value, + without affecting the cell

+ +FileInputStream fis = new FileInputStream("c:/temp/test.xls"); +Workbook wb = new HSSFWorkbook(fis); //or new XSSFWorkbook("c:/temp/test.xls") +Sheet sheet = wb.getSheetAt(0); +FormulaEvaluator evaluator = wb.getCreationHelper().createFormulaEvaluator(); + +// suppose your formula is in B3 +CellReference cellReference = new CellReference("B3"); +Row row = sheet.getRow(cellReference.getRow()); +Cell cell = row.getCell(cellReference.getCol()); + +CellValue cellValue = evaluator.evaluate(cell); + +switch (cellValue.getCellType()) { + case Cell.CELL_TYPE_BOOLEAN: + System.out.println(cellValue.getBooleanValue()); + break; + case Cell.CELL_TYPE_NUMERIC: + System.out.println(cellValue.getNumberValue()); + break; + case Cell.CELL_TYPE_STRING: + System.out.println(cellValue.getStringValue()); + break; + case Cell.CELL_TYPE_BLANK: + break; + case Cell.CELL_TYPE_ERROR: + break; + + // CELL_TYPE_FORMULA will never happen + case Cell.CELL_TYPE_FORMULA: + break; +} + +

Thus using the retrieved value (of type + FormulaEvaluator.CellValue - a nested class) returned + by FormulaEvaluator is similar to using a Cell object + containing the value of the formula evaluation. CellValue is + a simple value object and does not maintain reference + to the original cell. +

+
+ + +
Using FormulaEvaluator.<strong>evaluateFormulaCell</strong>(Cell cell) +

evaluateFormulaCell(Cell cell) + will check to see if the supplied cell is a formula cell. + If it isn't, then no changes will be made to it. If it is, + then the formula is evaluated. The value for the formula + is saved alongside it, to be displayed in excel. The + formula remains in the cell, just with a new value

+

The return of the function is the type of the + formula result, such as Cell.CELL_TYPE_BOOLEAN

+ +FileInputStream fis = new FileInputStream("/somepath/test.xls"); +Workbook wb = new HSSFWorkbook(fis); //or new XSSFWorkbook("/somepath/test.xls") +Sheet sheet = wb.getSheetAt(0); +FormulaEvaluator evaluator = wb.getCreationHelper().createFormulaEvaluator(); + +// suppose your formula is in B3 +CellReference cellReference = new CellReference("B3"); +Row row = sheet.getRow(cellReference.getRow()); +Cell cell = row.getCell(cellReference.getCol()); + +if (cell!=null) { + switch (evaluator.evaluateFormulaCell(cell)) { + case Cell.CELL_TYPE_BOOLEAN: + System.out.println(cell.getBooleanCellValue()); + break; + case Cell.CELL_TYPE_NUMERIC: + System.out.println(cell.getNumericCellValue()); + break; + case Cell.CELL_TYPE_STRING: + System.out.println(cell.getStringCellValue()); + break; + case Cell.CELL_TYPE_BLANK: + break; + case Cell.CELL_TYPE_ERROR: + System.out.println(cell.getErrorCellValue()); + break; + + // CELL_TYPE_FORMULA will never occur + case Cell.CELL_TYPE_FORMULA: + break; + } +} + +
+ + +
Using FormulaEvaluator.<strong>evaluateInCell</strong>(Cell cell) +

evaluateInCell(Cell cell) will check to + see if the supplied cell is a formula cell. If it isn't, + then no changes will be made to it. If it is, then the + formula is evaluated, and the new value saved into the cell, + in place of the old formula.

+ +FileInputStream fis = new FileInputStream("/somepath/test.xls"); +Workbook wb = new HSSFWorkbook(fis); //or new XSSFWorkbook("/somepath/test.xls") +Sheet sheet = wb.getSheetAt(0); +FormulaEvaluator evaluator = wb.getCreationHelper().createFormulaEvaluator(); + +// suppose your formula is in B3 +CellReference cellReference = new CellReference("B3"); +Row row = sheet.getRow(cellReference.getRow()); +Cell cell = row.getCell(cellReference.getCol()); + +if (cell!=null) { + switch (evaluator.evaluateInCell(cell).getCellType()) { + case Cell.CELL_TYPE_BOOLEAN: + System.out.println(cell.getBooleanCellValue()); + break; + case Cell.CELL_TYPE_NUMERIC: + System.out.println(cell.getNumericCellValue()); + break; + case Cell.CELL_TYPE_STRING: + System.out.println(cell.getStringCellValue()); + break; + case Cell.CELL_TYPE_BLANK: + break; + case Cell.CELL_TYPE_ERROR: + System.out.println(cell.getErrorCellValue()); + break; + + // CELL_TYPE_FORMULA will never occur + case Cell.CELL_TYPE_FORMULA: + break; + } +} + + +
+ + +
Re-calculating all formulas in a Workbook + +FileInputStream fis = new FileInputStream("/somepath/test.xls"); +Workbook wb = new HSSFWorkbook(fis); //or new XSSFWorkbook("/somepath/test.xls") +FormulaEvaluator evaluator = wb.getCreationHelper().createFormulaEvaluator(); +for(int sheetNum = 0; sheetNum < wb.getNumberOfSheets(); sheetNum++) { + Sheet sheet = wb.getSheetAt(sheetNum); + for(Row r : sheet) { + for(Cell c : r) { + if(c.getCellType() == Cell.CELL_TYPE_FORMULA) { + evaluator.evaluateFormulaCell(c); + } + } + } +} + + +

Alternately, if you know which of HSSF or XSSF you're working + with, then you can call the static + evaluateAllFormulaCells method on the appropriate + HSSFFormulaEvaluator or XSSFFormulaEvaluator class.

+
+
+ + +
Recalculation of Formulas +

+ In certain cases you may want to force Excel to re-calculate formulas when the workbook is opened. + Consider the following example: +

+

+ Open Excel and create a new workbook. On the first sheet set A1=1, B1=1, C1=A1+B1. + Excel automatically calculates formulas and the value in C1 is 2. So far so good. +

+

+ Now modify the workbook with POI: +

+ + Workbook wb = WorkbookFactory.create(new FileInputStream("workbook.xls")); + + Sheet sh = wb.getSheetAt(0); + sh.getRow(0).getCell(0).setCellValue(2); // set A1=2 + + FileOutputStream out = new FileOutputStream("workbook2.xls"); + wb.write(out); + out.close(); + +

+ Now open workbook2.xls in Excel and the value in C1 is still 2 while you expected 3. Wrong? No! + The point is that Excel caches previously calculated results and you need to trigger recalculation to updated them. + It is not an issue when you are creating new workbooks from scratch, but important to remember when you are modifing + existing workbooks with formulas. This can be done in two ways: +

+

+ 1. Re-evaluate formulas with POI's FormulaEvaluator: +

+ + Workbook wb = WorkbookFactory.create(new FileInputStream("workbook.xls")); + + Sheet sh = wb.getSheetAt(0); + sh.getRow(0).getCell(0).setCellValue(2); // set A1=2 + + wb.getCreationHelper().createFormulaEvaluator().evaluateAll(); + +

+ 2. Delegate re-calculation to Excel. The application will perform a full recalculation when the workbook is opened: +

+ + Workbook wb = WorkbookFactory.create(new FileInputStream("workbook.xls")); + + Sheet sh = wb.getSheetAt(0); + sh.getRow(0).getCell(0).setCellValue(2); // set A1=2 + + wb.setForceFormulaRecalculation(true); + +
+ + +
Performance Notes +
    +
  • Generally you should have to create only one FormulaEvaluator + instance per Workbook. The FormulaEvaluator will cache + evaluations of dependent cells, so if you have multiple + formulas all depending on a cell then subsequent evaluations + will be faster. +
    • +
  • You should normally perform all of your updates to cells, + before triggering the evaluation, rather than doing one + cell at a time. By waiting until all the updates/sets are + performed, you'll be able to take best advantage of the caching + for complex formulas. +
    • +
  • If you do end up making changes to cells part way through + evaluation, you should call notifySetFormula or + notifyUpdateCell to trigger suitable cache clearance. + Alternately, you could instantiate a new FormulaEvaluator, + which will start with empty caches. +
    • +
  • Also note that FormulaEvaluator maintains a reference to + the sheet and workbook, so ensure that the evaluator instance + is available for garbage collection when you are done with it + (in other words don't maintain long lived reference to + FormulaEvaluator if you don't really need to - unless + all references to the sheet and workbook are removed, these + don't get garbage collected and continue to occupy potentially + large amounts of memory). +
    • +
  • CellValue instances however do not maintain reference to the + Cell or the sheet or workbook, so these can be long-lived + objects without any adverse effect on performance. +
    • +
+
+
Formula Evaluation Debugging +

POI is not perfect and you may stumble across formula evaluation problems (Java exceptions + or just different results) in your special use case. To support an easy detailed analysis, a special + logging of the full evaluation is provided.

+

The output of this logging may be very large (depends on your EXCEL), so this logging has to be explicitly enabled + for each single formula evaluation. Should not be used in production - only for specific development use.

+

Example use:

+ + // activate logging to console + System.setProperty("org.apache.poi.util.POILogger", "org.apache.poi.util.SystemOutLogger"); + System.setProperty("poi.log.level", POILogger.INFO + ""); + + // open your file + Workbook wb = new HSSFWorkbook(new FileInputStream("foobar.xls")); + FormulaEvaluator evaluator = wb.getCreationHelper().createFormulaEvaluator(); + + // get your cell + Cell cell = wb.getSheet(0).getRow(0).getCell(0); // just a dummy example + + // perform debug output for the next evaluate-call only + evaluator.setDebugEvaluationOutputForNextEval(true); + evaluator.evaluateFormulaCell(cell); + evaluator.evaluateFormulaCell(cell); // no logging performed for this next evaluate-call + +

The special Logger called "POI.FormulaEval" is used (useful if you use the CommonsLogger and a detailed logging configuration). + The used log levels are WARN and INFO (for detailed parameter info and results) - the level are so high to allow this + special logging without beeing disturbed by the bunch of DEBUG log entries from other classes.

+
+ + diff --git a/src/documentation/content/xdocs/spreadsheet/examples.xml b/src/documentation/content/xdocs/spreadsheet/examples.xml new file mode 100644 index 0000000000..89c17cbe84 --- /dev/null +++ b/src/documentation/content/xdocs/spreadsheet/examples.xml @@ -0,0 +1,101 @@ + + + + + +
+ HSSF and XSSF Examples + + + +
+ +
HSSF and XSSF examples +

POI 3.5 and later comes with a number of examples that demonstrate how you can use POI API to create documents from "real life". + The examples are based on common XSSF-HSSF interfaces so that you can generate either *.xls or *.xlsx output just by setting a command-line argument: +

+ + BusinessPlan -xls + or + BusinessPlan -xlsx + +

All sample source is available in SVN

+
+
Business Plan +

The BusinessPlan + application creates a sample business plan with three phases, weekly iterations and time highlighting. Demonstrates advanced cell formatting + (number and date formats, alignmnets, fills, borders) and various settings for organizing data in a sheet (freezed panes, groupped rows). +

+

+ business plan demo +

+
+
Calendar +

The Calendar + demo creates a multi sheet calendar. Each month is on a separate sheet. +

+

+ calendar demo +

+
+
Loan Calculator +

The LoanCalculator + demo creates a simple loan calculator. Demonstrates advance usage of cell formulas and named ranges. +

+

+ loan calculator demo +

+
+
Timesheet +

The Timesheet + demo creates a weekly timesheet with automatic calculation of total hours. Demonstrates advance usage of cell formulas. +

+

+ timesheet demo +

+
+
Conditional Formats +

The ConditionalFormats + demo is a collection of short examples showing what you can do with Excel conditional formating in POI: +

+
    +
  • Highlight cells based on their values
    • +
  • Highlight a range of cells based on a formula
    • +
  • Hide errors
    • +
  • Hide the duplicate values
    • +
  • Highlight duplicate entries in a column
    • +
  • Highlight items that are in a list on the worksheet
    • +
  • Highlight payments that are due in the next thirty days
    • +
  • Shade alternating rows on the worksheet
    • +
  • Shade bands of rows on the worksheet
    • +
+
+
ToHtml +

The ToHtml + example shows how to display a spreadsheet in HTML using the classes for spreadsheet display. +

+
+
ToCSV +

The ToCSV + example demonstrates one way to convert an Excel spreadsheet into a CSV file. +

+
+ + diff --git a/src/documentation/content/xdocs/spreadsheet/excelant.xml b/src/documentation/content/xdocs/spreadsheet/excelant.xml new file mode 100644 index 0000000000..cf94dd5f22 --- /dev/null +++ b/src/documentation/content/xdocs/spreadsheet/excelant.xml @@ -0,0 +1,319 @@ + + + + + +
+ ExcelAnt - Ant Tasks for Validating Excel Spreadsheets + + + + +
+ +
ExcelAnt - Ant Tasks for Validating Excel Spreadsheets + +
Introduction +

ExcelAnt is a set of Ant tasks that make it possible to verify or test + a workbook without having to write Java code. Of course, the tasks themselves + are written in Java, but to use this frame work you only need to know a little + bit about Ant.

+

This document covers the basic usage and set up of ExcelAnt.

+

This document will assume basic familiarity with Ant and Ant build files.

+
+
Setup +

To start with, you'll need to have the POI 3.8 or higher jar files. If you test only .xls +workbooks then you need to have the following jars in your path:

+
    +
  • poi-excelant-$version-YYYYDDMM.jar
    • +
  • poi-$version-YYYYDDMM.jar
    • +
  • poi-ooxml-$version-YYYYDDMM.jar
    • +
+

If you evaluate .xlsx workbooks then you need to add these:

+
    +
  • poi-ooxml-schemas-$version-YYYYDDMM.jar
    • +
  • xmlbeans.jar
    • +
  • dom4j.jar
    • +
+

For example, if you have these jars in a lib/ dir in your project, your build.xml + might look like this:

+ + + + + + + +]]> +

Next, you'll need to define the Ant tasks. There are several ways to use ExcelAnt:

+ +
  • The traditional way:
+ +]]> +

+ Where excelant.path refers to the classpath with POI jars. + Using this approach the provided extensions will live in the default namespace. Note that the default task/typenames (evaluate, test) may be too generic and should either be explicitly overridden or used with a namespace. +

+
  • Similar, but assigning a namespace URI:
+ + + + + + + + + + +]]> +
+ +
A Simple Example +

The simplest example of using Excel is the ability to validate that POI is giving you back + the value you expect it to. Does this mean that POI is inaccurate? Hardly. There are cases + where POI is unable to evaluate cells for a variety of reasons. If you need to write code + to integrate a worksheet into an app, you may want to know that it's going to work before + you actually try to write that code. ExcelAnt helps with that.

+ +

Consider the mortgage-calculation.xls file found in the Examples + (/examples/src/org/apache/poi/ss/examples/excelant/simple-mortgage-calculation.xls). This sheet + is shown below:

+ + + +

This sheet calculates the principal and interest payment for a mortgage based + on the amount of the loan, term and rate. To write a simple ExcelAnt test you + need to tell ExcelAnt about the file like this:

+ + + + + + + + + +]]> + + +

This code sets up ExcelAnt to access the file defined in the ant property + xls.file. Then it creates a 'test' named 'checkValue'. Finally it tries + to evaluate the B4 on the sheet named 'MortgageCalculator'. There are some assumptions + here that are worth explaining. For starters, ExcelAnt is focused on the testing + numerically oriented sheets. The <evaluate> task is actually evaluating the + cell as a formula using a FormulaEvaluator instance from POI. Therefore it will fail + if you point it to a cell that doesn't contain a formula or a test a plain old number.

+ +

Having said all that, here is what the output looks like:

+ + + +
+ +
Setting Values into a Cell +

So now we know that at a minimum POI can use our sheet to calculate the existing value. + This is an important point: in many cases sheets have dependencies, i.e., cells they reference. + As is often the case, these cells may have dependencies, which may have dependencies, etc. + The point is that sometimes a dependent cell may get adjusted by a macro or a function + and it may be that POI doesn't have the capabilities to do the same thing. This test + verifies that we can rely on POI to retrieve the default value, based on the stored values + of the sheet. Now we want to know if we can manipulate those dependencies and verify + the output.

+ +

To verify that we can manipulate cell values, we need a way in ExcelAnt to set a value. + This is provided by the following task types:

+
    +
  • setDouble() - sets the specified cell as a double.
    • +
  • setFormula() - sets the specified cell as a formula.
    • +
  • setString() = sets the specified cell as a String.
    • +
+ +

For the purposes of this example we'll use the <setDouble> task. Let's + start with a $240,000, 30 year loan at 11% (let's pretend it's like 1984). Here + is how we will set that up:

+ + + + + +]]> + +

Don't forget that we're verifying the behavior so you need to put all this + into the sheet. That is how I got the result of $2,285 and change. So save your + changes and run it; you should get the following:

+ + + +
+ +
Getting More Details + +

This is great, it's working! However, suppose you want to see a little more detail. The + ExcelAnt tasks leverage the Ant logging so you can add the -verbose and -debug flags to + the Ant command line to get more detail. Try adding -verbose. Here is what + you should see:

+ + + + +

We see a little more detail. Notice that we see that there is a setting for global precision. + Up until now we've been setting the precision on each evaluate that we call. This + is obviously useful but it gets cumbersome. It would be better if there were a way + that we could specify a global precision - and there is. There is a <precision> + tag that you can specify as a child of the <excelant> tag. Let's go back to + our original task we set up earlier and modify it:

+ + + + + + + + + + + +]]> + +

In this example we have set the global precision to 1.0e-3. This means that + in the absence of something more stringent, all tests in the task will use + the global precision. We can still override this by specifying the + precision attribute of all of our <evaluate> task. Let's first run + this task with the global precision and the -verbose flag:

+ + + + +

As the output clearly shows, the test itself has no precision but there is + the global precision. Additionally, it tells us we're going to use that + more stringent global value. Now suppose that for this test we want + to use a more stringent precision, say 1.0e-4. We can do that by adding + the precision attribute back to the <evaluate> task:

+ + + + + + + + + + +]]> + + +

Now when you re-run this test with the verbose flag you will see that + your test ran and passed with the higher precision:

+ +
+ +
Leveraging User Defined Functions +

POI has an excellent feature (besides ExcelAnt) called User Defined Functions, + that allows you to write Java code that will be used in place of custom VB + code or macros is a spreadsheet. If you have read the documentation and written + your own FreeRefFunction implmentations, ExcelAnt can make use of this code. + For each <excelant> task you define you can nest a <udf> tag + which allows you to specify the function alias and the class name.

+ +

Consider the previous example of the mortgage calculator. What if, instead + of being a formula in a cell, it was a function defined in a VB macro? As luck + would have it, we already have an example of this in the examples from the + User Defined Functions example, so let's use that. In the example spreadsheet + there is a tab for MortgageCalculatorFunction, which will use. If you look in + cell B4, you see that rather than a messy cell based formula, there is only the function + call. Let's not get bogged down in the function/Java implementation, as these + are covered in the User Defined Function documentation. Let's just add + a new target and test to our existing build file:

+ + + + + + + + + + + + +]]> + +

So if you look at this carefully it looks the same as the previous examples. We + still use the global precision, we're still setting values, and we still want + to evaluate a cell. The only real differences are the sheet name and the + addition of the function.

+
+
+ + diff --git a/src/documentation/content/xdocs/spreadsheet/formula.xml b/src/documentation/content/xdocs/spreadsheet/formula.xml new file mode 100644 index 0000000000..3f319fce46 --- /dev/null +++ b/src/documentation/content/xdocs/spreadsheet/formula.xml @@ -0,0 +1,99 @@ + + + + + +
+ Formula Support + + + +
+ +
Introduction +

+ This document describes the current state of formula support in POI. + The information in this document currently applies to the 3.5 version of POI. + Since this area is a work in progress, this document will be updated with new features as and + when they are added. +

+ +
+
The basics +

+ In org.apache.poi.hssf.usermodel.HSSFCell + setCellFormula("formulaString") is used to add a formula to sheet and + getCellFormula() is used to retrieve the string representation of a formula. +

+

+ We aim to support the complete excel grammar for formulas. Thus, the string that you pass in + to the setCellFormula call should be what you expect to type into excel. Also, note + that you should NOT add a "=" to the front of the string. +

+
+
Supported Features +
    +
  • References: single cell & area, 2D & 3D, relative & absolute
    • +
  • Literals: Number, text, boolean, error and array
    • +
  • Operators: arithmetic and logical, some region operators
    • +
  • Built-in functions: over 350 recognised, 280 evaluatable
    • +
  • Add-in functions: 3 from Analysis Toolpack
    • +
+
+
Not yet supported +
    +
  • Manipulating array/table formulas (In Excel, formulas that look like "{=...}" as opposed to "=...")
    • +
  • Region operators: union, intersection
    • +
  • Parsing of previously uncalled add-in functions
    • +
  • Preservation of whitespace in formulas (when POI manipulates them)
    • +
+
+ +
Internals +

+ Formulas in Excel are stored as sequences of tokens in Reverse Polish Notation order. The + open office XLS spec is the best + documentation you will find for the format. +

+ +

+ The tokens used by excel are modelled as individual *Ptg classes in the + org.apache.poi.hssf.record.formula package. +

+

+ The task of parsing a formula string into an array of RPN ordered tokens is done by the + org.apache.poi.ss.formula.FormulaParser class. This class implements a hand + written recursive descent parser. +

+

+ Formula tokens in Excel are stored in one of three possible operand classes : + Reference, Value and Array. Based on the location of a token, its class can change + in complicated and undocumented ways. While we have support for most cases, we + are not sure if we have covered all bases (since there is no documentation for this area.) + We would therefore like you to report any + occurrence of #VALUE! in a cell upon opening a POI generated workbook in excel. (Check that + typing the formula into Excel directly gives a valid result.) +

+

Check out the javadocs for details. +

+
+ + + diff --git a/src/documentation/content/xdocs/spreadsheet/hacking-hssf.xml b/src/documentation/content/xdocs/spreadsheet/hacking-hssf.xml new file mode 100644 index 0000000000..eb10f4fc6b --- /dev/null +++ b/src/documentation/content/xdocs/spreadsheet/hacking-hssf.xml @@ -0,0 +1,90 @@ + + + + + +
+ Hacking HSSF + + + + +
+ +
Where Can I Find Documentation on Feature X +

+ You might find the + 'Excel 97 Developer's Kit' (out of print, Microsoft Press, no + restrictive covenants, available on Amazon.com) helpful for + understanding the file format. +

+

+ Also useful is the open office XLS spec. We + are collaborating with the maintainer of the spec so if you think you can add something to their + document just send through your changes. +

+
+
Help, I Can't Find Feature X Documented Anywhere +
    +
  1. + Look at OpenOffice.org or Gnumeric sources if its implemented there. +
    2. +
  2. + Use org.apache.poi.hssf.dev.BiffViewer to view the structure of the + file. Experiment by adding one criteria entry at a time. See what it + does to the structure, infer behavior and structure from it. Using the + unix diff command (or get cygwin from www.cygwin.com for windows) you + can figure out a lot very quickly. Unimplemented records show up as + 'UNKNOWN' and prints a hex dump. +
    3. +
+
+
Low-level Record Generation +

+ Low level records can be time consuming to created. We created a record + generator to help generate some of the simpler tasks. +

+

+ We use XML + descriptors to generate the Java code (which sure beats the heck out of + the PERL scripts originally used ;-) for low level records. The + generator is kinda alpha-ish right now and could use some enhancement, + so you may find that to be about 1/2 of the work. Notice this is in + org.apache.poi.hssf.record.definitions. +

+
+
Important Notice +

One thing to note: If you are making a large code contribution we need to ensure + any participants in this process have never + signed a "Non Disclosure Agreement" with Microsoft, and have not + received any information covered by such an agreement. If they have + they'll not be able to participate in the POI project. For large contributions we + may ask you to sign an agreement.

+
+
What Can I Work On? +

Check our todo list or simply look for missing functionality. Start small + and work your way up.

+
+
What Else Should I Know? +

Make sure you read the contributing section + as it contains more generation information about contributing to POI in general.

+
+ + diff --git a/src/documentation/content/xdocs/spreadsheet/how-to.xml b/src/documentation/content/xdocs/spreadsheet/how-to.xml new file mode 100644 index 0000000000..e09366cf1b --- /dev/null +++ b/src/documentation/content/xdocs/spreadsheet/how-to.xml @@ -0,0 +1,877 @@ + + + + + +
+ The New Halloween Document + + + + + + +
+ +
How to use the HSSF API + +
Capabilities +

This release of the how-to outlines functionality for the + current svn trunk. + Those looking for information on previous releases should + look in the documentation distributed with that release.

+

+ HSSF allows numeric, string, date or formuala cell values to be written to + or read from an XLS file. Also + in this release is row and column sizing, cell styling (bold, + italics, borders,etc), and support for both built-in and user + defined data formats. Also available is + an event-based API for reading XLS files. + It differs greatly from the read/write API + and is intended for intermediate developers who need a smaller + memory footprint. +

+
+
Different APIs +

There are a few different ways to access the HSSF API. These + have different characteristics, so you should read up on + all to select the best for you.

+
    +
  • User API (HSSF and XSSF)
    • +
  • Event API (HSSF Only)
    • +
  • Event API with extensions to be Record Aware (HSSF Only)
    • +
  • XSSF and SAX (Event API)
    • +
  • SXSSF (Streaming User API)
    • +
  • Low Level API
    • +
+
+
+
General Use + +
User API (HSSF and XSSF) +
Writing a new file + +

The high level API (package: org.apache.poi.ss.usermodel) + is what most people should use. Usage is very simple. +

+

Workbooks are created by creating an instance of + org.apache.poi.ss.usermodel.Workbook. Either create + a concrete class directly + (org.apache.poi.hssf.usermodel.HSSFWorkbook or + org.apache.poi.xssf.usermodel.XSSFWorkbook), or use + the handy factory class + org.apache.poi.ss.usermodel.WorkbookFactory. +

+

Sheets are created by calling createSheet() from an existing + instance of Workbook, the created sheet is automatically added in + sequence to the workbook. Sheets do not in themselves have a sheet + name (the tab at the bottom); you set + the name associated with a sheet by calling + Workbook.setSheetName(sheetindex,"SheetName",encoding). + For HSSF, the name may be in 8bit format + (HSSFWorkbook.ENCODING_COMPRESSED_UNICODE) + or Unicode (HSSFWorkbook.ENCODING_UTF_16). Default + encoding for HSSF is 8bit per char. For XSSF, the name + is automatically handled as unicode. +

+

Rows are created by calling createRow(rowNumber) from an existing + instance of Sheet. Only rows that have cell values should be + added to the sheet. To set the row's height, you just call + setRowHeight(height) on the row object. The height must be given in + twips, or 1/20th of a point. If you prefer, there is also a + setRowHeightInPoints method. +

+

Cells are created by calling createCell(column, type) from an + existing Row. Only cells that have values should be added to the + row. Cells should have their cell type set to either + Cell.CELL_TYPE_NUMERIC or Cell.CELL_TYPE_STRING depending on + whether they contain a numeric or textual value. Cells must also have + a value set. Set the value by calling setCellValue with either a + String or double as a parameter. Individual cells do not have a + width; you must call setColumnWidth(colindex, width) (use units of + 1/256th of a character) on the Sheet object. (You can't do it on + an individual basis in the GUI either).

+

Cells are styled with CellStyle objects which in turn contain + a reference to an Font object. These are created via the + Workbook object by calling createCellStyle() and createFont(). + Once you create the object you must set its parameters (colors, + borders, etc). To set a font for an CellStyle call + setFont(fontobj). +

+

Once you have generated your workbook, you can write it out by + calling write(outputStream) from your instance of Workbook, passing + it an OutputStream (for instance, a FileOutputStream or + ServletOutputStream). You must close the OutputStream yourself. HSSF + does not close it for you. +

+

Here is some example code (excerpted and adapted from + org.apache.poi.hssf.dev.HSSF test class):

+ +
+
Reading or modifying an existing file + +

Reading in a file is equally simple. To read in a file, create a +new instance of org.apache.poi.poifs.Filesystem, passing in an open InputStream, such as a FileInputStream +for your XLS, to the constructor. Construct a new instance of +org.apache.poi.hssf.usermodel.HSSFWorkbook passing the +Filesystem instance to the constructor. From there you have access to +all of the high level model objects through their assessor methods +(workbook.getSheet(sheetNum), sheet.getRow(rownum), etc). +

+

Modifying the file you have read in is simple. You retrieve the +object via an assessor method, remove it via a parent object's remove +method (sheet.removeRow(hssfrow)) and create objects just as you +would if creating a new xls. When you are done modifying cells just +call workbook.write(outputstream) just as you did above.

+

An example of this can be seen in +org.apache.poi.hssf.usermodel.examples.HSSFReadWrite.

+
+
+ + +
Event API (HSSF Only) + +

The event API is newer than the User API. It is intended for intermediate + developers who are willing to learn a little bit of the low level API + structures. Its relatively simple to use, but requires a basic + understanding of the parts of an Excel file (or willingness to + learn). The advantage provided is that you can read an XLS with a + relatively small memory footprint. +

+

One important thing to note with the basic Event API is that it + triggers events only for things actually stored within the file. + With the XLS file format, it is quite common for things that + have yet to be edited to simply not exist in the file. This means + there may well be apparent "gaps" in the record stream, which + you either need to work around, or use the + Record Aware extension + to the Event API.

+

To use this API you construct an instance of + org.apache.poi.hssf.eventmodel.HSSFRequest. Register a class you + create that supports the + org.apache.poi.hssf.eventmodel.HSSFListener interface using the + HSSFRequest.addListener(yourlistener, recordsid). The recordsid + should be a static reference number (such as BOFRecord.sid) contained + in the classes in org.apache.poi.hssf.record. The trick is you + have to know what these records are. Alternatively you can call + HSSFRequest.addListenerForAllRecords(mylistener). In order to learn + about these records you can either read all of the javadoc in the + org.apache.poi.hssf.record package or you can just hack up a + copy of org.apache.poi.hssf.dev.EFHSSF and adapt it to your + needs. TODO: better documentation on records.

+

Once you've registered your listeners in the HSSFRequest object + you can construct an instance of + org.apache.poi.poifs.filesystem.FileSystem (see POIFS howto) and + pass it your XLS file inputstream. You can either pass this, along + with the request you constructed, to an instance of HSSFEventFactory + via the HSSFEventFactory.processWorkbookEvents(request, Filesystem) + method, or you can get an instance of DocumentInputStream from + Filesystem.createDocumentInputStream("Workbook") and pass + it to HSSFEventFactory.processEvents(request, inputStream). Once you + make this call, the listeners that you constructed receive calls to + their processRecord(Record) methods with each Record they are + registered to listen for until the file has been completely read. +

+

A code excerpt from org.apache.poi.hssf.dev.EFHSSF (which is + in CVS or the source distribution) is reprinted below with excessive + comments:

+ +
+ + +
Record Aware Event API (HSSF Only) +

+This is an extension to the normal +Event API. With this, your listener +will be called with extra, dummy records. These dummy records should +alert you to records which aren't present in the file (eg cells that have +yet to be edited), and allow you to handle these. +

+

+There are three dummy records that your HSSFListener will be called with: +

+
    +
  • org.apache.poi.hssf.eventusermodel.dummyrecord.MissingRowDummyRecord +
    + This is called during the row record phase (which typically occurs before + the cell records), and indicates that the row record for the given + row is not present in the file.
    • +
  • org.apache.poi.hssf.eventusermodel.dummyrecord.MissingCellDummyRecord +
    + This is called during the cell record phase. It is called when a cell + record is encountered which leaves a gap between it an the previous one. + You can get multiple of these, before the real cell record.
    • +
  • org.apache.poi.hssf.eventusermodel.dummyrecord.LastCellOfRowDummyRecord +
    + This is called after the last cell of a given row. It indicates that there + are no more cells for the row, and also tells you how many cells you have + had. For a row with no cells, this will be the only record you get.
    • +
+

+To use the Record Aware Event API, you should create an +org.apache.poi.hssf.eventusermodel.MissingRecordAwareHSSFListener, and pass +it your HSSFListener. Then, register the MissingRecordAwareHSSFListener +to the event model, and start that as normal. +

+

+One example use for this API is to write a CSV outputter, which always +outputs a minimum number of columns, even where the file doesn't contain +some of the rows or cells. It can be found at +/src/examples/src/org/apache/poi/hssf/eventusermodel/examples/XLS2CSVmra.java, +and may be called on the command line, or from within your own code. +The latest version is always available from +subversion. +

+

+In POI versions before 3.0.3, this code lived in the scratchpad section. + If you're using one of these older versions of POI, you will either + need to include the scratchpad jar on your classpath, or build from a + subversion checkout. +

+
+ + +
XSSF and SAX (Event API) + +

If memory footprint is an issue, then for XSSF, you can get at + the underlying XML data, and process it yourself. This is intended + for intermediate developers who are willing to learn a little bit of + low level structure of .xlsx files, and who are happy processing + XML in java. Its relatively simple to use, but requires a basic + understanding of the file structure. The advantage provided is that + you can read a XLSX file with a relatively small memory footprint. +

+

One important thing to note with the basic Event API is that it + triggers events only for things actually stored within the file. + With the XLSX file format, it is quite common for things that + have yet to be edited to simply not exist in the file. This means + there may well be apparent "gaps" in the record stream, which + you need to work around.

+

To use this API you construct an instance of + org.apache.poi.xssf.eventmodel.XSSFReader. This will optionally + provide a nice interace on the shared strings table, and the styles. + It provides methods to get the raw xml data from the rest of the + file, which you will then pass to SAX.

+

This example shows how to get at a single known sheet, or at + all sheets in the file. It is based on the example in svn + src/examples/src/org/apache/poi/xssf/eventusermodel/exmaples/FromHowTo.java

+ sheets = r.getSheetsData(); + while(sheets.hasNext()) { + System.out.println("Processing new sheet:\n"); + InputStream sheet = sheets.next(); + InputSource sheetSource = new InputSource(sheet); + parser.parse(sheetSource); + sheet.close(); + System.out.println(""); + } + } + + public XMLReader fetchSheetParser(SharedStringsTable sst) throws SAXException { + XMLReader parser = + XMLReaderFactory.createXMLReader( + "org.apache.xerces.parsers.SAXParser" + ); + ContentHandler handler = new SheetHandler(sst); + parser.setContentHandler(handler); + return parser; + } + + /** + * See org.xml.sax.helpers.DefaultHandler javadocs + */ + private static class SheetHandler extends DefaultHandler { + private SharedStringsTable sst; + private String lastContents; + private boolean nextIsString; + + private SheetHandler(SharedStringsTable sst) { + this.sst = sst; + } + + public void startElement(String uri, String localName, String name, + Attributes attributes) throws SAXException { + // c => cell + if(name.equals("c")) { + // Print the cell reference + System.out.print(attributes.getValue("r") + " - "); + // Figure out if the value is an index in the SST + String cellType = attributes.getValue("t"); + if(cellType != null && cellType.equals("s")) { + nextIsString = true; + } else { + nextIsString = false; + } + } + // Clear contents cache + lastContents = ""; + } + + public void endElement(String uri, String localName, String name) + throws SAXException { + // Process the last contents as required. + // Do now, as characters() may be called more than once + if(nextIsString) { + int idx = Integer.parseInt(lastContents); + lastContents = new XSSFRichTextString(sst.getEntryAt(idx)).toString(); + nextIsString = false; + } + + // v => contents of a cell + // Output after we've seen the string contents + if(name.equals("v")) { + System.out.println(lastContents); + } + } + + public void characters(char[] ch, int start, int length) + throws SAXException { + lastContents += new String(ch, start, length); + } + } + + public static void main(String[] args) throws Exception { + FromHowTo howto = new FromHowTo(); + howto.processOneSheet(args[0]); + howto.processAllSheets(args[0]); + } +} +]]> +
+ +
SXSSF (Streaming Usermodel API) +

+ SXSSF (package: org.apache.poi.xssf.streaming) is an API-compatible streaming extension of XSSF to be used when + very large spreadsheets have to be produced, and heap space is limited. + SXSSF achieves its low memory footprint by limiting access to the rows that + are within a sliding window, while XSSF gives access to all rows in the + document. Older rows that are no longer in the window become inaccessible, + as they are written to the disk. +

+

+ You can specify the window size at workbook construction time via new SXSSFWorkbook(int windowSize) + or you can set it per-sheet via SXSSFSheet#setRandomAccessWindowSize(int windowSize) +

+

+ When a new row is created via createRow() and the total number + of unflushed records would exceed the specified window size, then the + row with the lowest index value is flushed and cannot be accessed + via getRow() anymore. +

+

+ The default window size is 100 and defined by SXSSFWorkbook.DEFAULT_WINDOW_SIZE. +

+

+ A windowSize of -1 indicates unlimited access. In this case all + records that have not been flushed by a call to flushRows() are available + for random access. +

+

+ Note that SXSSF allocates temporary files that you must always clean up explicitly, by calling the dispose method. +

+

The example below writes a sheet with a window of 100 rows. When the row count reaches 101, + the row with rownum=0 is flushed to disk and removed from memory, when rownum reaches 102 then the row with rownum=1 is flushed, etc. +

+ + + +

The next example turns off auto-flushing (windowSize=-1) and the code manually controls how portions of data are written to disk

+ +

SXSSF flushes sheet data in temporary files (a temp file per sheet) and the size of these temporary files +can grow to a very large value. For example, for a 20 MB csv data the size of the temp xml becomes more than a gigabyte. +If the size of the temp files is an issue, you can tell SXSSF to use gzip compression: +

+ +
+ + +
Low Level APIs + +

The low level API is not much to look at. It consists of lots of +"Records" in the org.apache.poi.hssf.record.* package, +and set of helper classes in org.apache.poi.hssf.model.*. The +record classes are consistent with the low level binary structures +inside a BIFF8 file (which is embedded in a POIFS file system). You +probably need the book: "Microsoft Excel 97 Developer's Kit" +from Microsoft Press in order to understand how these fit together +(out of print but easily obtainable from Amazon's used books). In +order to gain a good understanding of how to use the low level APIs +should view the source in org.apache.poi.hssf.usermodel.* and +the classes in org.apache.poi.hssf.model.*. You should read the +documentation for the POIFS libraries as well.

+
+
Generating XLS from XML +

If you wish to generate an XLS file from some XML, it is possible to +write your own XML processing code, then use the User API to write out +the document.

+

The other option is to use Cocoon. +In Cocoon, there is the HSSF Serializer, +which takes in XML (in the gnumeric format), and outputs an XLS file for you.

+
+
HSSF Class/Test Application + +

The HSSF application is nothing more than a test for the high +level API (and indirectly the low level support). The main body of +its code is repeated above. To run it: +

+
    +
  • download the poi-alpha build and untar it (tar xvzf + tarball.tar.gz) +
    • +
  • set up your classpath as follows: + export HSSFDIR={wherever you put HSSF's jar files} +export LOG4JDIR={wherever you put LOG4J's jar files} +export CLASSPATH=$CLASSPATH:$HSSFDIR/hssf.jar:$HSSFDIR/poi-poifs.jar:$HSSFDIR/poi-util.jar:$LOG4JDIR/jog4j.jar +
  • type: + java org.apache.poi.hssf.dev.HSSF ~/myxls.xls write
    • +
+

+

This should generate a test sheet in your home directory called "myxls.xls".

+
    +
  • Type: + java org.apache.poi.hssf.dev.HSSF ~/input.xls output.xls +
    +
    +This is the read/write/modify test. It reads in the spreadsheet, modifies a cell, and writes it back out. +Failing this test is not necessarily a bad thing. If HSSF tries to modify a non-existant sheet then this will +most likely fail. No big deal.
    • +
+
+
Logging facility +

POI can dynamically select its logging implementation. POI tries to + create a logger using the System property named "org.apache.poi.util.POILogger". + Out of the box this can be set to one of three values: +

+
    +
  • org.apache.poi.util.CommonsLogger
    • +
  • org.apache.poi.util.NullLogger
    • +
  • org.apache.poi.util.SystemOutLogger
    • +
+

+ If the property is not defined or points to an invalid classthen the NullLogger is used. +

+

+ Refer to the commons logging package level javadoc for more information concerning how to + configure commons logging. +

+
+
HSSF Developer's Tools + +

HSSF has a number of tools useful for developers to debug/develop +stuff using HSSF (and more generally XLS files). We've already +discussed the app for testing HSSF read/write/modify capabilities; +now we'll talk a bit about BiffViewer. Early on in the development of +HSSF, it was decided that knowing what was in a record, what was +wrong with it, etc. was virtually impossible with the available +tools. So we developed BiffViewer. You can find it at +org.apache.poi.hssf.dev.BiffViewer. It performs two basic +functions and a derivative. +

+

The first is "biffview". To do this you run it (assumes +you have everything setup in your classpath and that you know what +you're doing enough to be thinking about this) with an xls file as a +parameter. It will give you a listing of all understood records with +their data and a list of not-yet-understood records with no data +(because it doesn't know how to interpret them). This listing is +useful for several things. First, you can look at the values and SEE +what is wrong in quasi-English. Second, you can send the output to a +file and compare it. +

+

The second function is "big freakin dump", just pass a +file and a second argument matching "bfd" exactly. This +will just make a big hexdump of the file. +

+

Lastly, there is "mixed" mode which does the same as +regular biffview, only it includes hex dumps of certain records +intertwined. To use that just pass a file with a second argument +matching "on" exactly.

+

In the next release cycle we'll also have something called a +FormulaViewer. The class is already there, but its not very useful +yet. When it does something, we'll document it.

+ +
+
What's Next? + +

Further effort on HSSF is going to focus on the following major areas:

+
    +
  • Performance: POI currently uses a lot of memory for large sheets.
    • +
  • Charts: This is a hard problem, with very little documentation.
    • +
+

So jump in!

+ +
+ +
+ + diff --git a/src/documentation/content/xdocs/spreadsheet/index.xml b/src/documentation/content/xdocs/spreadsheet/index.xml new file mode 100644 index 0000000000..11e58d3b7e --- /dev/null +++ b/src/documentation/content/xdocs/spreadsheet/index.xml @@ -0,0 +1,119 @@ + + + + + +
+ POI-HSSF and POI-XSSF - Java API To Access Microsoft Excel Format Files + Overview + + + + +
+ + +
+ Overview + +

HSSF is the POI Project's pure Java implementation of the + Excel '97(-2007) file format. XSSF is the POI Project's pure + Java implementation of the Excel 2007 OOXML (.xlsx) file + format.

+

HSSF and XSSF provides ways to read spreadsheets create, + modify, read and write XLS spreadsheets. They provide: +

+
    +
  • low level structures for those with special needs
    • +
  • an eventmodel api for efficient read-only access
    • +
  • a full usermodel api for creating, reading and modifying XLS files
    • +
+

For people converting from pure HSSF usermodel, who wish + to use the joint SS Usermodel for HSSF and XSSF support, then + see the ss usermodel converting + guide. +

+

+ An alternate way of generating a spreadsheet is via the Cocoon serializer (yet you'll still be using HSSF indirectly). + With Cocoon you can serialize any XML datasource (which might be a ESQL page outputting in SQL for instance) by simply + applying the stylesheet and designating the serializer. +

+

+ If you're merely reading spreadsheet data, then use the + eventmodel api in either the org.apache.poi.hssf.eventusermodel + package, or the org.apache.poi.xssf.eventusermodel package, depending + on your file format. +

+

+ If you're modifying spreadsheet data then use the usermodel api. You + can also generate spreadsheets this way. +

+

+ Note that the usermodel system has a higher memory footprint than + the low level eventusermodel, but have the major advantage of being + much simpler to work with. Also please be aware that as the new + XSSF supported Excel 2007 OOXML (.xlsx) files are XML based, + the memory footprint for processing them is higher than for the + older HSSF supported (.xls) binary files. +

+ + + +
+ +
+SXSSF (Since POI 3.8 beta3) +

Since 3.8-beta3, POI provides a low-memory footprint SXSSF API built on top of XSSF.

+

+SXSSF is an API-compatible streaming extension of XSSF to be used when +very large spreadsheets have to be produced, and heap space is limited. +SXSSF achieves its low memory footprint by limiting access to the rows that +are within a sliding window, while XSSF gives access to all rows in the +document. Older rows that are no longer in the window become inaccessible, +as they are written to the disk. +

+

+In auto-flush mode the size of the access window can be specified, to hold a certain number of rows in memory. +When that value is reached, the creation of an additional row causes the row with the lowest index to to be +removed from the access window and written to disk. Or, the window size can be set to grow dynamically; +it can be trimmed periodically by an explicit call to flushRows(int keepRows) as needed. +

+

+Due to the streaming nature of the implementation, there are the following +limitations when compared to XSSF: +

+
    +
  • Only a limited number of rows are accessible at a point in time.
    • +
  • Sheet.clone() is not supported.
    • +
  • Formula evaluation is not supported
    • +
+ +

See more details at SXSSF How-To

+ +

The table below synopsizes the comparative features of POI's Spreadsheet API:

+

Spreadsheet API Feature Summary

+ +

+ Spreadsheet API Feature Summary +

+
+ + + diff --git a/src/documentation/content/xdocs/spreadsheet/limitations.xml b/src/documentation/content/xdocs/spreadsheet/limitations.xml new file mode 100644 index 0000000000..bbb806bf1f --- /dev/null +++ b/src/documentation/content/xdocs/spreadsheet/limitations.xml @@ -0,0 +1,58 @@ + + + + + +
+ Limitations + + + +
+ +
Version 3.7 limitations +

+ The intent of this document is to outline some of the known limitations of the + POI HSSF API's. It is not intended to be complete list of every bug or missing + feature of HSSF, rather it's purpose is to provide a broad feel for some of the + functionality that is missing or broken. +

+
    +
  • + Charts

    + You can not currently create charts. You can + however create a chart in Excel, modify the chart data values using HSSF and write + a new spreadsheet out. This is possible because POI attempts to keep existing records + intact as far as possible.

    +
    • +
  • + Macros

    + Macros can not be created. However, reading and re-writing files containing macros will + safely preserve the macros.

    +
    • +
  • + Pivot Tables

    + Generating pivot tables is not supported. It has been reported that files containing pivot + tables can be read and re-written safely. +
    • +
+
+ + diff --git a/src/documentation/content/xdocs/spreadsheet/quick-guide.xml b/src/documentation/content/xdocs/spreadsheet/quick-guide.xml new file mode 100644 index 0000000000..89590e0380 --- /dev/null +++ b/src/documentation/content/xdocs/spreadsheet/quick-guide.xml @@ -0,0 +1,2108 @@ + + + + + +
+ Busy Developers' Guide to HSSF and XSSF Features +
+ +
Busy Developers' Guide to Features +

+ Want to use HSSF and XSSF read and write spreadsheets in a hurry? This + guide is for you. If you're after more in-depth coverage of the HSSF and + XSSF user-APIs, please consult the HOWTO + guide as it contains actual descriptions of how to use this stuff. +

+
Index of Features +
    +
  • How to create a new workbook
    • +
  • How to create a sheet
    • +
  • How to create cells
    • +
  • How to create date cells
    • +
  • Working with different types of cells
    • +
  • Iterate over rows and cells
    • +
  • Getting the cell contents
    • +
  • Text Extraction
    • +
  • Files vs InputStreams
    • +
  • Aligning cells
    • +
  • Working with borders
    • +
  • Fills and color
    • +
  • Merging cells
    • +
  • Working with fonts
    • +
  • Custom colors
    • +
  • Reading and writing
    • +
  • Use newlines in cells.
    • +
  • Create user defined data formats
    • +
  • Fit Sheet to One Page
    • +
  • Set print area for a sheet
    • +
  • Set page numbers on the footer of a sheet
    • +
  • Shift rows
    • +
  • Set a sheet as selected
    • +
  • Set the zoom magnification for a sheet
    • +
  • Create split and freeze panes
    • +
  • Repeating rows and columns
    • +
  • Headers and Footers
    • +
  • Drawing Shapes
    • +
  • Styling Shapes
    • +
  • Shapes and Graphics2d
    • +
  • Outlining
    • +
  • Images
    • +
  • Named Ranges and Named Cells
    • +
  • How to set cell comments
    • +
  • How to adjust column width to fit the contents
    • +
  • Hyperlinks
    • +
  • Data Validations
    • +
  • Embedded Objects
    • +
  • Autofilters
    • +
  • Conditional Formatting
    • +
  • Hiding and Un-Hiding Rows
    • +
+
+
Features + +
New Workbook + + Workbook wb = new HSSFWorkbook(); + FileOutputStream fileOut = new FileOutputStream("workbook.xls"); + wb.write(fileOut); + fileOut.close(); + + Workbook wb = new XSSFWorkbook(); + FileOutputStream fileOut = new FileOutputStream("workbook.xlsx"); + wb.write(fileOut); + fileOut.close(); + +
+ +
New Sheet + + Workbook wb = new HSSFWorkbook(); // or new XSSFWorkbook(); + Sheet sheet1 = wb.createSheet("new sheet"); + Sheet sheet2 = wb.createSheet("second sheet"); + + // Note that sheet name is Excel must not exceed 31 characters + // and must not contain any of the any of the following characters: + // 0x0000 + // 0x0003 + // colon (:) + // backslash (\) + // asterisk (*) + // question mark (?) + // forward slash (/) + // opening square bracket ([) + // closing square bracket (]) + + // You can use org.apache.poi.ss.util.WorkbookUtil#createSafeSheetName(String nameProposal)} + // for a safe way to create valid names, this utility replaces invalid characters with a space (' ') + String safeName = WorkbookUtil.createSafeSheetName("[O'Brien's sales*?]"); // returns " O'Brien's sales " + Sheet sheet3 = wb.createSheet(safeName); + + FileOutputStream fileOut = new FileOutputStream("workbook.xls"); + wb.write(fileOut); + fileOut.close(); + +
+ +
Creating Cells + + Workbook wb = new HSSFWorkbook(); + //Workbook wb = new XSSFWorkbook(); + CreationHelper createHelper = wb.getCreationHelper(); + Sheet sheet = wb.createSheet("new sheet"); + + // Create a row and put some cells in it. Rows are 0 based. + Row row = sheet.createRow((short)0); + // Create a cell and put a value in it. + Cell cell = row.createCell(0); + cell.setCellValue(1); + + // Or do it on one line. + row.createCell(1).setCellValue(1.2); + row.createCell(2).setCellValue( + createHelper.createRichTextString("This is a string")); + row.createCell(3).setCellValue(true); + + // Write the output to a file + FileOutputStream fileOut = new FileOutputStream("workbook.xls"); + wb.write(fileOut); + fileOut.close(); + +
+ +
Creating Date Cells + + Workbook wb = new HSSFWorkbook(); + //Workbook wb = new XSSFWorkbook(); + CreationHelper createHelper = wb.getCreationHelper(); + Sheet sheet = wb.createSheet("new sheet"); + + // Create a row and put some cells in it. Rows are 0 based. + Row row = sheet.createRow(0); + + // Create a cell and put a date value in it. The first cell is not styled + // as a date. + Cell cell = row.createCell(0); + cell.setCellValue(new Date()); + + // we style the second cell as a date (and time). It is important to + // create a new cell style from the workbook otherwise you can end up + // modifying the built in style and effecting not only this cell but other cells. + CellStyle cellStyle = wb.createCellStyle(); + cellStyle.setDataFormat( + createHelper.createDataFormat().getFormat("m/d/yy h:mm")); + cell = row.createCell(1); + cell.setCellValue(new Date()); + cell.setCellStyle(cellStyle); + + //you can also set date as java.util.Calendar + cell = row.createCell(2); + cell.setCellValue(Calendar.getInstance()); + cell.setCellStyle(cellStyle); + + // Write the output to a file + FileOutputStream fileOut = new FileOutputStream("workbook.xls"); + wb.write(fileOut); + fileOut.close(); + +
+ +
Working with different types of cells + + Workbook wb = new HSSFWorkbook(); + Sheet sheet = wb.createSheet("new sheet"); + Row row = sheet.createRow((short)2); + row.createCell(0).setCellValue(1.1); + row.createCell(1).setCellValue(new Date()); + row.createCell(2).setCellValue(Calendar.getInstance()); + row.createCell(3).setCellValue("a string"); + row.createCell(4).setCellValue(true); + row.createCell(5).setCellType(Cell.CELL_TYPE_ERROR); + + // Write the output to a file + FileOutputStream fileOut = new FileOutputStream("workbook.xls"); + wb.write(fileOut); + fileOut.close(); + +
+ + +
Files vs InputStreams +

When opening a workbook, either a .xls HSSFWorkbook, or a .xlsx + XSSFWorkbook, the Workbook can be loaded from either a File + or an InputStream. Using a File object allows for + lower memory consumption, while an InputStream requires more + memory as it has to buffer the whole file.

+

If using WorkbookFactory, it's very easy to use one or + the other:

+ + // Use a file + Workbook wb = WorkbookFactory.create(new File("MyExcel.xls")); + + // Use an InputStream, needs more memory + Workbook wb = WorkbookFactory.create(new FileInputStream("MyExcel.xlsx")); + +

If using HSSFWorkbook or XSSFWorkbook directly, + you should generally go through NPOIFSFileSystem or + OPCPackage, to have full control of the lifecycle (including + closing the file when done):

+ + // HSSFWorkbook, File + NPOIFSFileSytem fs = new NPOIFSFileSystem(new File("file.xls")); + HSSFWorkbook wb = new HSSFWorkbook(fs.getRoot()); + .... + fs.close(); + + // HSSFWorkbook, InputStream, needs more memory + NPOIFSFileSytem fs = new NPOIFSFileSystem(myInputStream); + HSSFWorkbook wb = new HSSFWorkbook(fs.getRoot()); + + // XSSFWorkbook, File + OPCPackage pkg = OPCPackage.open(new File("file.xlsx")); + XSSFWorkbook wb = new XSSFWorkbook(pkg); + .... + pkg.close(); + + // XSSFWorkbook, InputStream, needs more memory + OPCPackage pkg = OPCPackage.open(myInputStream); + XSSFWorkbook wb = new XSSFWorkbook(pkg); + .... + pkg.close(); + +
+ + +
Demonstrates various alignment options + + public static void main(String[] args) throws Exception { + Workbook wb = new XSSFWorkbook(); //or new HSSFWorkbook(); + + Sheet sheet = wb.createSheet(); + Row row = sheet.createRow((short) 2); + row.setHeightInPoints(30); + + createCell(wb, row, (short) 0, CellStyle.ALIGN_CENTER, CellStyle.VERTICAL_BOTTOM); + createCell(wb, row, (short) 1, CellStyle.ALIGN_CENTER_SELECTION, CellStyle.VERTICAL_BOTTOM); + createCell(wb, row, (short) 2, CellStyle.ALIGN_FILL, CellStyle.VERTICAL_CENTER); + createCell(wb, row, (short) 3, CellStyle.ALIGN_GENERAL, CellStyle.VERTICAL_CENTER); + createCell(wb, row, (short) 4, CellStyle.ALIGN_JUSTIFY, CellStyle.VERTICAL_JUSTIFY); + createCell(wb, row, (short) 5, CellStyle.ALIGN_LEFT, CellStyle.VERTICAL_TOP); + createCell(wb, row, (short) 6, CellStyle.ALIGN_RIGHT, CellStyle.VERTICAL_TOP); + + // Write the output to a file + FileOutputStream fileOut = new FileOutputStream("xssf-align.xlsx"); + wb.write(fileOut); + fileOut.close(); + + } + + /** + * Creates a cell and aligns it a certain way. + * + * @param wb the workbook + * @param row the row to create the cell in + * @param column the column number to create the cell in + * @param halign the horizontal alignment for the cell. + */ + private static void createCell(Workbook wb, Row row, short column, short halign, short valign) { + Cell cell = row.createCell(column); + cell.setCellValue("Align It"); + CellStyle cellStyle = wb.createCellStyle(); + cellStyle.setAlignment(halign); + cellStyle.setVerticalAlignment(valign); + cell.setCellStyle(cellStyle); + } + +
+ +
Working with borders + + Workbook wb = new HSSFWorkbook(); + Sheet sheet = wb.createSheet("new sheet"); + + // Create a row and put some cells in it. Rows are 0 based. + Row row = sheet.createRow(1); + + // Create a cell and put a value in it. + Cell cell = row.createCell(1); + cell.setCellValue(4); + + // Style the cell with borders all around. + CellStyle style = wb.createCellStyle(); + style.setBorderBottom(CellStyle.BORDER_THIN); + style.setBottomBorderColor(IndexedColors.BLACK.getIndex()); + style.setBorderLeft(CellStyle.BORDER_THIN); + style.setLeftBorderColor(IndexedColors.GREEN.getIndex()); + style.setBorderRight(CellStyle.BORDER_THIN); + style.setRightBorderColor(IndexedColors.BLUE.getIndex()); + style.setBorderTop(CellStyle.BORDER_MEDIUM_DASHED); + style.setTopBorderColor(IndexedColors.BLACK.getIndex()); + cell.setCellStyle(style); + + // Write the output to a file + FileOutputStream fileOut = new FileOutputStream("workbook.xls"); + wb.write(fileOut); + fileOut.close(); + +
+ +
Iterate over rows and cells +

Sometimes, you'd like to just iterate over all the rows in + a sheet, or all the cells in a row. This is possible with + a simple for loop.

+

Luckily, this is very easy. Row defines a + CellIterator inner class to handle iterating over + the cells (get one with a call to row.cellIterator()), + and Sheet provides a rowIterator() method to + give an iterator over all the rows. These implement the + java.lang.Iterable interface to allow foreach loops.

+ + + Sheet sheet = wb.getSheetAt(0); + for (Row row : sheet) { + for (Cell cell : row) { + // Do something here + } + } + +
+
Iterate over cells, with control of missing / blank cells +

In some cases, when iterating, you need full control over how + missing or blank cells are treated, and you need to ensure you + visit every cell and not just those defined in the file. (The + CellIterator will only return the cells defined in the file, which + is largely those with values or stylings, but it depends on Excel).

+

In cases such as these, you should fetch the first and last column + information for a row, then call getCell(int, MissingCellPolicy) + to fetch the cell. Use a + MissingCellPolicy + to control how blank or null cells are handled.

+ + // Decide which rows to process + int rowStart = Math.min(15, sheet.getFirstRowNum()); + int rowEnd = Math.max(1400, sheet.getLastRowNum()); + + for (int rowNum = rowStart; rowNum < rowEnd; rowNum++) { + Row r = sheet.getRow(rowNum); + + int lastColumn = Math.max(r.getLastCellNum(), MY_MINIMUM_COLUMN_COUNT); + + for (int cn = 0; cn < lastColumn; cn++) { + Cell c = r.getCell(cn, Row.RETURN_BLANK_AS_NULL); + if (c == null) { + // The spreadsheet is empty in this cell + } else { + // Do something useful with the cell's contents + } + } + } + +
+ + +
Getting the cell contents +

To get the contents of a cell, you first need to + know what kind of cell it is (asking a string cell + for its numeric contents will get you a + NumberFormatException for example). So, you will + want to switch on the cell's type, and then call + the appropriate getter for that cell.

+

In the code below, we loop over every cell + in one sheet, print out the cell's reference + (eg A3), and then the cell's contents.

+ + // import org.apache.poi.ss.usermodel.*; + + Sheet sheet1 = wb.getSheetAt(0); + for (Row row : sheet1) { + for (Cell cell : row) { + CellReference cellRef = new CellReference(row.getRowNum(), cell.getColumnIndex()); + System.out.print(cellRef.formatAsString()); + System.out.print(" - "); + + switch (cell.getCellType()) { + case Cell.CELL_TYPE_STRING: + System.out.println(cell.getRichStringCellValue().getString()); + break; + case Cell.CELL_TYPE_NUMERIC: + if (DateUtil.isCellDateFormatted(cell)) { + System.out.println(cell.getDateCellValue()); + } else { + System.out.println(cell.getNumericCellValue()); + } + break; + case Cell.CELL_TYPE_BOOLEAN: + System.out.println(cell.getBooleanCellValue()); + break; + case Cell.CELL_TYPE_FORMULA: + System.out.println(cell.getCellFormula()); + break; + default: + System.out.println(); + } + } + } + +
+ + +
Text Extraction +

For most text extraction requirements, the standard + ExcelExtractor class should provide all you need.

+ + InputStream inp = new FileInputStream("workbook.xls"); + HSSFWorkbook wb = new HSSFWorkbook(new POIFSFileSystem(inp)); + ExcelExtractor extractor = new ExcelExtractor(wb); + + extractor.setFormulasNotResults(true); + extractor.setIncludeSheetNames(false); + String text = extractor.getText(); + +

For very fancy text extraction, XLS to CSV etc, + take a look at + /src/examples/src/org/apache/poi/hssf/eventusermodel/examples/XLS2CSVmra.java +

+
+ +
Fills and colors + + Workbook wb = new XSSFWorkbook(); + Sheet sheet = wb.createSheet("new sheet"); + + // Create a row and put some cells in it. Rows are 0 based. + Row row = sheet.createRow((short) 1); + + // Aqua background + CellStyle style = wb.createCellStyle(); + style.setFillBackgroundColor(IndexedColors.AQUA.getIndex()); + style.setFillPattern(CellStyle.BIG_SPOTS); + Cell 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(IndexedColors.ORANGE.getIndex()); + style.setFillPattern(CellStyle.SOLID_FOREGROUND); + cell = row.createCell((short) 2); + cell.setCellValue("X"); + cell.setCellStyle(style); + + // Write the output to a file + FileOutputStream fileOut = new FileOutputStream("workbook.xls"); + wb.write(fileOut); + fileOut.close(); + +
+ +
Merging cells + + Workbook wb = new HSSFWorkbook(); + Sheet sheet = wb.createSheet("new sheet"); + + Row row = sheet.createRow((short) 1); + Cell cell = row.createCell((short) 1); + cell.setCellValue("This is a test of merging"); + + sheet.addMergedRegion(new CellRangeAddress( + 1, //first row (0-based) + 1, //last row (0-based) + 1, //first column (0-based) + 2 //last column (0-based) + )); + + // Write the output to a file + FileOutputStream fileOut = new FileOutputStream("workbook.xls"); + wb.write(fileOut); + fileOut.close(); + +
+ +
Working with fonts + + Workbook wb = new HSSFWorkbook(); + Sheet sheet = wb.createSheet("new sheet"); + + // Create a row and put some cells in it. Rows are 0 based. + Row row = sheet.createRow(1); + + // Create a new font and alter it. + Font font = wb.createFont(); + font.setFontHeightInPoints((short)24); + font.setFontName("Courier New"); + font.setItalic(true); + font.setStrikeout(true); + + // Fonts are set into a style so create a new one to use. + CellStyle style = wb.createCellStyle(); + style.setFont(font); + + // Create a cell and put a value in it. + Cell cell = row.createCell(1); + cell.setCellValue("This is a test of fonts"); + cell.setCellStyle(style); + + // Write the output to a file + FileOutputStream fileOut = new FileOutputStream("workbook.xls"); + wb.write(fileOut); + fileOut.close(); + +

+ Note, the maximum number of unique fonts in a workbook is limited to 32767 ( + the maximum positive short). You should re-use fonts in your apllications instead of + creating a font for each cell. +Examples: +

+

Wrong:

+ + for (int i = 0; i < 10000; i++) { + Row row = sheet.createRow(i); + Cell cell = row.createCell((short) 0); + + CellStyle style = workbook.createCellStyle(); + Font font = workbook.createFont(); + font.setBoldweight(Font.BOLDWEIGHT_BOLD); + style.setFont(font); + cell.setCellStyle(style); + } + +

Correct:

+ + + CellStyle style = workbook.createCellStyle(); + Font font = workbook.createFont(); + font.setBoldweight(Font.BOLDWEIGHT_BOLD); + style.setFont(font); + for (int i = 0; i < 10000; i++) { + Row row = sheet.createRow(i); + Cell cell = row.createCell((short) 0); + cell.setCellStyle(style); + } + + +
+ +
Custom colors +

HSSF:

+ + HSSFWorkbook wb = new HSSFWorkbook(); + HSSFSheet sheet = wb.createSheet(); + HSSFRow row = sheet.createRow((short) 0); + HSSFCell cell = row.createCell((short) 0); + cell.setCellValue("Default Palette"); + + //apply some colors from the standard palette, + // as in the previous examples. + //we'll use red text on a lime background + + HSSFCellStyle style = wb.createCellStyle(); + style.setFillForegroundColor(HSSFColor.LIME.index); + style.setFillPattern(HSSFCellStyle.SOLID_FOREGROUND); + + HSSFFont font = wb.createFont(); + font.setColor(HSSFColor.RED.index); + style.setFont(font); + + cell.setCellStyle(style); + + //save with the default palette + FileOutputStream out = new FileOutputStream("default_palette.xls"); + wb.write(out); + out.close(); + + //now, let's replace RED and LIME in the palette + // with a more attractive combination + // (lovingly borrowed from freebsd.org) + + cell.setCellValue("Modified Palette"); + + //creating a custom palette for the workbook + HSSFPalette palette = wb.getCustomPalette(); + + //replacing the standard red with freebsd.org red + palette.setColorAtIndex(HSSFColor.RED.index, + (byte) 153, //RGB red (0-255) + (byte) 0, //RGB green + (byte) 0 //RGB blue + ); + //replacing lime with freebsd.org gold + palette.setColorAtIndex(HSSFColor.LIME.index, (byte) 255, (byte) 204, (byte) 102); + + //save with the modified palette + // note that wherever we have previously used RED or LIME, the + // new colors magically appear + out = new FileOutputStream("modified_palette.xls"); + wb.write(out); + out.close(); + +

XSSF:

+ + XSSFWorkbook wb = new XSSFWorkbook(); + XSSFSheet sheet = wb.createSheet(); + XSSFRow row = sheet.createRow(0); + XSSFCell cell = row.createCell( 0); + cell.setCellValue("custom XSSF colors"); + + XSSFCellStyle style1 = wb.createCellStyle(); + style1.setFillForegroundColor(new XSSFColor(new java.awt.Color(128, 0, 128))); + style1.setFillPattern(CellStyle.SOLID_FOREGROUND); + +
+ +
Reading and Rewriting Workbooks + + InputStream inp = new FileInputStream("workbook.xls"); + //InputStream inp = new FileInputStream("workbook.xlsx"); + + Workbook wb = WorkbookFactory.create(inp); + Sheet sheet = wb.getSheetAt(0); + Row row = sheet.getRow(2); + Cell cell = row.getCell(3); + if (cell == null) + cell = row.createCell(3); + cell.setCellType(Cell.CELL_TYPE_STRING); + cell.setCellValue("a test"); + + // Write the output to a file + FileOutputStream fileOut = new FileOutputStream("workbook.xls"); + wb.write(fileOut); + fileOut.close(); + +
+ +
Using newlines in cells + + Workbook wb = new XSSFWorkbook(); //or new HSSFWorkbook(); + Sheet sheet = wb.createSheet(); + + Row row = sheet.createRow(2); + Cell cell = row.createCell(2); + cell.setCellValue("Use \n with word wrap on to create a new line"); + + //to enable newlines you need set a cell styles with wrap=true + CellStyle cs = wb.createCellStyle(); + cs.setWrapText(true); + cell.setCellStyle(cs); + + //increase row height to accomodate two lines of text + row.setHeightInPoints((2*sheet.getDefaultRowHeightInPoints())); + + //adjust column width to fit the content + sheet.autoSizeColumn((short)2); + + FileOutputStream fileOut = new FileOutputStream("ooxml-newlines.xlsx"); + wb.write(fileOut); + fileOut.close(); + +
+ +
Data Formats + + Workbook wb = new HSSFWorkbook(); + Sheet sheet = wb.createSheet("format sheet"); + CellStyle style; + DataFormat format = wb.createDataFormat(); + Row row; + Cell cell; + short rowNum = 0; + short colNum = 0; + + row = sheet.createRow(rowNum++); + cell = row.createCell(colNum); + cell.setCellValue(11111.25); + style = wb.createCellStyle(); + style.setDataFormat(format.getFormat("0.0")); + cell.setCellStyle(style); + + row = sheet.createRow(rowNum++); + cell = row.createCell(colNum); + cell.setCellValue(11111.25); + style = wb.createCellStyle(); + style.setDataFormat(format.getFormat("#,##0.0000")); + cell.setCellStyle(style); + + FileOutputStream fileOut = new FileOutputStream("workbook.xls"); + wb.write(fileOut); + fileOut.close(); + +
+ +
Fit Sheet to One Page + + Workbook wb = new HSSFWorkbook(); + Sheet sheet = wb.createSheet("format sheet"); + PrintSetup ps = sheet.getPrintSetup(); + + sheet.setAutobreaks(true); + + ps.setFitHeight((short)1); + ps.setFitWidth((short)1); + + + // Create various cells and rows for spreadsheet. + + FileOutputStream fileOut = new FileOutputStream("workbook.xls"); + wb.write(fileOut); + fileOut.close(); + +
+ +
Set Print Area + + Workbook wb = new HSSFWorkbook(); + Sheet sheet = wb.createSheet("Sheet1"); + //sets the print area for the first sheet + wb.setPrintArea(0, "$A$1:$C$2"); + + //Alternatively: + wb.setPrintArea( + 0, //sheet index + 0, //start column + 1, //end column + 0, //start row + 0 //end row + ); + + FileOutputStream fileOut = new FileOutputStream("workbook.xls"); + wb.write(fileOut); + fileOut.close(); + +
+ + +
Set Page Numbers on Footer + + Workbook wb = new HSSFWorkbook(); // or new XSSFWorkbook(); + Sheet sheet = wb.createSheet("format sheet"); + Footer footer = sheet.getFooter(); + + footer.setRight( "Page " + HeaderFooter.page() + " of " + HeaderFooter.numPages() ); + + + + // Create various cells and rows for spreadsheet. + + FileOutputStream fileOut = new FileOutputStream("workbook.xls"); + wb.write(fileOut); + fileOut.close(); + +
+ + +
Using the Convenience Functions +

+ The convenience functions provide + utility features such as setting borders around merged + regions and changing style attributes without explicitly + creating new styles. +

+ + Workbook wb = new HSSFWorkbook(); // or new XSSFWorkbook() + Sheet sheet1 = wb.createSheet( "new sheet" ); + + // Create a merged region + Row row = sheet1.createRow( 1 ); + Row row2 = sheet1.createRow( 2 ); + Cell cell = row.createCell( 1 ); + cell.setCellValue( "This is a test of merging" ); + CellRangeAddress region = CellRangeAddress.valueOf("B2:E5"); + sheet1.addMergedRegion( region ); + + // Set the border and border colors. + final short borderMediumDashed = CellStyle.BORDER_MEDIUM_DASHED; + RegionUtil.setBorderBottom( borderMediumDashed, + region, sheet1, wb ); + RegionUtil.setBorderTop( borderMediumDashed, + region, sheet1, wb ); + RegionUtil.setBorderLeft( borderMediumDashed, + region, sheet1, wb ); + RegionUtil.setBorderRight( borderMediumDashed, + region, sheet1, wb ); + RegionUtil.setBottomBorderColor(IndexedColors.AQUA.getIndex(), region, sheet1, wb); + RegionUtil.setTopBorderColor(IndexedColors.AQUA.getIndex(), region, sheet1, wb); + RegionUtil.setLeftBorderColor(IndexedColors.AQUA.getIndex(), region, sheet1, wb); + RegionUtil.setRightBorderColor(IndexedColors.AQUA.getIndex(), region, sheet1, wb); + + // Shows some usages of HSSFCellUtil + CellStyle style = wb.createCellStyle(); + style.setIndention((short)4); + CellUtil.createCell(row, 8, "This is the value of the cell", style); + Cell cell2 = CellUtil.createCell( row2, 8, "This is the value of the cell"); + CellUtil.setAlignment(cell2, wb, CellStyle.ALIGN_CENTER); + + // Write out the workbook + FileOutputStream fileOut = new FileOutputStream( "workbook.xls" ); + wb.write( fileOut ); + fileOut.close(); + +
+ + +
Shift rows up or down on a sheet + + Workbook wb = new HSSFWorkbook(); + Sheet sheet = wb.createSheet("row sheet"); + + // Create various cells and rows for spreadsheet. + + // Shift rows 6 - 11 on the spreadsheet to the top (rows 0 - 5) + sheet.shiftRows(5, 10, -5); + + +
+ + +
Set a sheet as selected + + Workbook wb = new HSSFWorkbook(); + Sheet sheet = wb.createSheet("row sheet"); + sheet.setSelected(true); + + +
+ + +
Set the zoom magnification +

+ The zoom is expressed as a fraction. For example to + express a zoom of 75% use 3 for the numerator and + 4 for the denominator. +

+ + Workbook wb = new HSSFWorkbook(); + Sheet sheet1 = wb.createSheet("new sheet"); + sheet1.setZoom(3,4); // 75 percent magnification + +
+ + +
Splits and freeze panes +

+ There are two types of panes you can create; freeze panes and split panes. +

+

+ A freeze pane is split by columns and rows. You create + a freeze pane using the following mechanism: +

+

+ sheet1.createFreezePane( 3, 2, 3, 2 ); +

+

+ The first two parameters are the columns and rows you + wish to split by. The second two parameters indicate + the cells that are visible in the bottom right quadrant. +

+

+ + Split pains appear differently. The split area is + divided into four separate work area's. The split + occurs at the pixel level and the user is able to + adjust the split by dragging it to a new position. +

+

+ + Split panes are created with the following call: +

+

+ sheet2.createSplitPane( 2000, 2000, 0, 0, Sheet.PANE_LOWER_LEFT ); +

+

+ + The first parameter is the x position of the split. + This is in 1/20th of a point. A point in this case + seems to equate to a pixel. The second parameter is + the y position of the split. Again in 1/20th of a point. +

+

+ The last parameter indicates which pane currently has + the focus. This will be one of Sheet.PANE_LOWER_LEFT, + PANE_LOWER_RIGHT, PANE_UPPER_RIGHT or PANE_UPPER_LEFT. +

+ + Workbook wb = new HSSFWorkbook(); + Sheet sheet1 = wb.createSheet("new sheet"); + Sheet sheet2 = wb.createSheet("second sheet"); + Sheet sheet3 = wb.createSheet("third sheet"); + Sheet sheet4 = wb.createSheet("fourth sheet"); + + // Freeze just one row + sheet1.createFreezePane( 0, 1, 0, 1 ); + // Freeze just one column + sheet2.createFreezePane( 1, 0, 1, 0 ); + // Freeze the columns and rows (forget about scrolling position of the lower right quadrant). + sheet3.createFreezePane( 2, 2 ); + // Create a split with the lower left side being the active quadrant + sheet4.createSplitPane( 2000, 2000, 0, 0, Sheet.PANE_LOWER_LEFT ); + + FileOutputStream fileOut = new FileOutputStream("workbook.xls"); + wb.write(fileOut); + fileOut.close(); + +
+ + +
Repeating rows and columns +

+ It's possible to set up repeating rows and columns in + your printouts by using the setRepeatingRows() and + setRepeatingColumns() methods in the Sheet class. +

+

+ These methods expect a CellRangeAddress parameter + which specifies the range for the rows or columns to + repeat. + For setRepeatingRows(), it should specify a range of + rows to repeat, with the column part spanning all + columns. + For setRepeatingColums(), it should specify a range of + columns to repeat, with the row part spanning all + rows. + If the parameter is null, the repeating rows or columns + will be removed. +

+ + Workbook wb = new HSSFWorkbook(); // or new XSSFWorkbook(); + Sheet sheet1 = wb.createSheet("Sheet1"); + Sheet sheet2 = wb.createSheet("Sheet2"); + + // Set the rows to repeat from row 4 to 5 on the first sheet. + sheet1.setRepeatingRows(CellRangeAddress.valueOf("4:5")); + // Set the columns to repeat from column A to C on the second sheet + sheet2.setRepeatingColumns(CellRangeAddress.valueOf("A:C")); + + FileOutputStream fileOut = new FileOutputStream("workbook.xls"); + wb.write(fileOut); + fileOut.close(); + +
+ +
Headers and Footers +

+ Example is for headers but applies directly to footers. +

+ + Workbook wb = new HSSFWorkbook(); + Sheet sheet = wb.createSheet("new sheet"); + + Header header = sheet.getHeader(); + header.setCenter("Center Header"); + header.setLeft("Left Header"); + header.setRight(HSSFHeader.font("Stencil-Normal", "Italic") + + HSSFHeader.fontSize((short) 16) + "Right w/ Stencil-Normal Italic font and size 16"); + + FileOutputStream fileOut = new FileOutputStream("workbook.xls"); + wb.write(fileOut); + fileOut.close(); + +
+ + +
Drawing Shapes +

+ POI supports drawing shapes using the Microsoft Office + drawing tools. Shapes on a sheet are organized in a + hiearchy of groups and and shapes. The top-most shape + is the patriarch. This is not visisble on the sheet + at all. To start drawing you need to call createPatriarch + on the HSSFSheet class. This has the + effect erasing any other shape information stored + in that sheet. By default POI will leave shape + records alone in the sheet unless you make a call to + this method. +

+

+ To create a shape you have to go through the following + steps: +

+
    +
  1. Create the patriarch.
    2. +
  2. Create an anchor to position the shape on the sheet.
    3. +
  3. Ask the patriarch to create the shape.
    4. +
  4. Set the shape type (line, oval, rectangle etc...)
    5. +
  5. Set any other style details converning the shape. (eg: + line thickness, etc...)
    6. +
+ + HSSFPatriarch patriarch = sheet.createDrawingPatriarch(); + a = new HSSFClientAnchor( 0, 0, 1023, 255, (short) 1, 0, (short) 1, 0 ); + HSSFSimpleShape shape1 = patriarch.createSimpleShape(a1); + shape1.setShapeType(HSSFSimpleShape.OBJECT_TYPE_LINE); + +

+ Text boxes are created using a different call: +

+ + HSSFTextbox textbox1 = patriarch.createTextbox( + new HSSFClientAnchor(0,0,0,0,(short)1,1,(short)2,2)); + textbox1.setString(new HSSFRichTextString("This is a test") ); + +

+ It's possible to use different fonts to style parts of + the text in the textbox. Here's how: +

+ + HSSFFont font = wb.createFont(); + font.setItalic(true); + font.setUnderline(HSSFFont.U_DOUBLE); + HSSFRichTextString string = new HSSFRichTextString("Woo!!!"); + string.applyFont(2,5,font); + textbox.setString(string ); + +

+ Just as can be done manually using Excel, it is possible + to group shapes together. This is done by calling + createGroup() and then creating the shapes + using those groups. +

+

+ It's also possible to create groups within groups. +

+ Any group you create should contain at least two + other shapes or subgroups. +

+ Here's how to create a shape group: +

+ + // Create a shape group. + HSSFShapeGroup group = patriarch.createGroup( + new HSSFClientAnchor(0,0,900,200,(short)2,2,(short)2,2)); + + // Create a couple of lines in the group. + HSSFSimpleShape shape1 = group.createShape(new HSSFChildAnchor(3,3,500,500)); + shape1.setShapeType(HSSFSimpleShape.OBJECT_TYPE_LINE); + ( (HSSFChildAnchor) shape1.getAnchor() ).setAnchor((short)3,3,500,500); + HSSFSimpleShape shape2 = group.createShape(new HSSFChildAnchor((short)1,200,400,600)); + shape2.setShapeType(HSSFSimpleShape.OBJECT_TYPE_LINE); + +

+ If you're being observant you'll noticed that the shapes + that are added to the group use a new type of anchor: + the HSSFChildAnchor. What happens is that + the created group has it's own coordinate space for + shapes that are placed into it. POI defaults this to + (0,0,1023,255) but you are able to change it as desired. + Here's how: +

+ + myGroup.setCoordinates(10,10,20,20); // top-left, bottom-right + +

+ If you create a group within a group it's also going + to have it's own coordinate space. +

+
+ + +
Styling Shapes +

+ By default shapes can look a little plain. It's possible + to apply different styles to the shapes however. The + sorts of things that can currently be done are: +

+
    +
  • Change the fill color.
    • +
  • Make a shape with no fill color.
    • +
  • Change the thickness of the lines.
    • +
  • Change the style of the lines. Eg: dashed, dotted.
    • +
  • Change the line color.
    • +
+

+ Here's an examples of how this is done: +

+ + HSSFSimpleShape s = patriarch.createSimpleShape(a); + s.setShapeType(HSSFSimpleShape.OBJECT_TYPE_OVAL); + s.setLineStyleColor(10,10,10); + s.setFillColor(90,10,200); + s.setLineWidth(HSSFShape.LINEWIDTH_ONE_PT * 3); + s.setLineStyle(HSSFShape.LINESTYLE_DOTSYS); + +
+ +
Shapes and Graphics2d +

+ While the native POI shape drawing commands are the + recommended way to draw shapes in a shape it's sometimes + desirable to use a standard API for compatibility with + external libraries. With this in mind we created some + wrappers for Graphics and Graphics2d. +

+ + It's important to not however before continuing that + Graphics2d is a poor match to the capabilities + of the Microsoft Office drawing commands. The older + Graphics class offers a closer match but is + still a square peg in a round hole. + +

+ All Graphics commands are issued into an HSSFShapeGroup. + Here's how it's done: +

+ + a = new HSSFClientAnchor( 0, 0, 1023, 255, (short) 1, 0, (short) 1, 0 ); + group = patriarch.createGroup( a ); + group.setCoordinates( 0, 0, 80 * 4 , 12 * 23 ); + float verticalPointsPerPixel = a.getAnchorHeightInPoints(sheet) / (float)Math.abs(group.getY2() - group.getY1()); + g = new EscherGraphics( group, wb, Color.black, verticalPointsPerPixel ); + g2d = new EscherGraphics2d( g ); + drawChemicalStructure( g2d ); + +

+ The first thing we do is create the group and set it's coordinates + to match what we plan to draw. Next we calculate a reasonable + fontSizeMultipler then create the EscherGraphics object. + Since what we really want is a Graphics2d + object we create an EscherGraphics2d object and pass in + the graphics object we created. Finally we call a routine + that draws into the EscherGraphics2d object. +

+

+ The vertical points per pixel deserves some more explanation. + One of the difficulties in converting Graphics calls + into escher drawing calls is that Excel does not have + the concept of absolute pixel positions. It measures + it's cell widths in 'characters' and the cell heights in points. + Unfortunately it's not defined exactly what type of character it's + measuring. Presumably this is due to the fact that the Excel will be + using different fonts on different platforms or even within the same + platform. +

+

+ Because of this constraint we've had to implement the concept of a + verticalPointsPerPixel. This the amount the font should be scaled by when + you issue commands such as drawString(). To calculate this value + use the follow formula: +

+ + multipler = groupHeightInPoints / heightOfGroup + +

+ The height of the group is calculated fairly simply by calculating the + difference between the y coordinates of the bounding box of the shape. The + height of the group can be calculated by using a convenience called + HSSFClientAnchor.getAnchorHeightInPoints(). +

+

+ Many of the functions supported by the graphics classes + are not complete. Here's some of the functions that are known + to work. +

+
    +
  • fillRect()
    • +
  • fillOval()
    • +
  • drawString()
    • +
  • drawOval()
    • +
  • drawLine()
    • +
  • clearRect()
    • +
+

+ Functions that are not supported will return and log a message + using the POI logging infrastructure (disabled by default). +

+
+ +
+ Outlining +

+ Outlines are great for grouping sections of information + together and can be added easily to columns and rows + using the POI API. Here's how: +

+ + Workbook wb = new HSSFWorkbook(); + Sheet sheet1 = wb.createSheet("new sheet"); + + sheet1.groupRow( 5, 14 ); + sheet1.groupRow( 7, 14 ); + sheet1.groupRow( 16, 19 ); + + sheet1.groupColumn( (short)4, (short)7 ); + sheet1.groupColumn( (short)9, (short)12 ); + sheet1.groupColumn( (short)10, (short)11 ); + + FileOutputStream fileOut = new FileOutputStream(filename); + wb.write(fileOut); + fileOut.close(); + +

+ To collapse (or expand) an outline use the following calls: +

+ + sheet1.setRowGroupCollapsed( 7, true ); + sheet1.setColumnGroupCollapsed( (short)4, true ); + +

+ The row/column you choose should contain an already + created group. It can be anywhere within the group. +

+
+
+
+ +
+ Images +

+ Images are part of the drawing support. To add an image just + call createPicture() on the drawing patriarch. + At the time of writing the following types are supported: +

+
    +
  • PNG
    • +
  • JPG
    • +
  • DIB
    • +
+

+ It should be noted that any existing drawings may be erased + once you add a image to a sheet. +

+ + //create a new workbook + Workbook wb = new XSSFWorkbook(); //or new HSSFWorkbook(); + + //add picture data to this workbook. + InputStream is = new FileInputStream("image1.jpeg"); + byte[] bytes = IOUtils.toByteArray(is); + int pictureIdx = wb.addPicture(bytes, Workbook.PICTURE_TYPE_JPEG); + is.close(); + + CreationHelper helper = wb.getCreationHelper(); + + //create sheet + Sheet sheet = wb.createSheet(); + + // Create the drawing patriarch. This is the top level container for all shapes. + Drawing drawing = sheet.createDrawingPatriarch(); + + //add a picture shape + ClientAnchor anchor = helper.createClientAnchor(); + //set top-left corner of the picture, + //subsequent call of Picture#resize() will operate relative to it + anchor.setCol1(3); + anchor.setRow1(2); + Picture pict = drawing.createPicture(anchor, pictureIdx); + + //auto-size picture relative to its top-left corner + pict.resize(); + + //save workbook + String file = "picture.xls"; + if(wb instanceof XSSFWorkbook) file += "x"; + FileOutputStream fileOut = new FileOutputStream(file); + wb.write(fileOut); + fileOut.close(); + + + Picture.resize() works only for JPEG and PNG. Other formats are not yet supported. + +

Reading images from a workbook:

+ + + List lst = workbook.getAllPictures(); + for (Iterator it = lst.iterator(); it.hasNext(); ) { + PictureData pict = (PictureData)it.next(); + String ext = pict.suggestFileExtension(); + byte[] data = pict.getData(); + if (ext.equals("jpeg")){ + FileOutputStream out = new FileOutputStream("pict.jpg"); + out.write(data); + out.close(); + } + } + +
+ +
+ Named Ranges and Named Cells +

+ Named Range is a way to refer to a group of cells by a name. Named Cell is a + degenerate case of Named Range in that the 'group of cells' contains exactly one + cell. You can create as well as refer to cells in a workbook by their named range. + When working with Named Ranges, the classes: org.apache.poi.hssf.util.CellReference and + & org.apache.poi.hssf.util.AreaReference are used (these + work for both XSSF and HSSF, despite the package name). +

+

+ Creating Named Range / Named Cell +

+ + // setup code + String sname = "TestSheet", cname = "TestName", cvalue = "TestVal"; + Workbook wb = new HSSFWorkbook(); + Sheet sheet = wb.createSheet(sname); + sheet.createRow(0).createCell((short) 0).setCellValue(cvalue); + + // 1. create named range for a single cell using areareference + Name namedCell = wb.createName(); + namedCell.setNameName(cname); + String reference = sname+"!A1:A1"; // area reference + namedCell.setRefersToFormula(reference); + + // 2. create named range for a single cell using cellreference + Name namedCel2 = wb.createName(); + namedCel2.setNameName(cname); + String reference = sname+"!A1"; // cell reference + namedCel2.setRefersToFormula(reference); + + // 3. create named range for an area using AreaReference + Name namedCel3 = wb.createName(); + namedCel3.setNameName(cname); + String reference = sname+"!A1:C5"; // area reference + namedCel3.setRefersToFormula(reference); + + // 4. create named formula + Name namedCel4 = wb.createName(); + namedCel4.setNameName("my_sum"); + namedCel4.setRefersToFormula("SUM(sname+!$I$2:$I$6)"); + +

+ Reading from Named Range / Named Cell +

+ + // setup code + String cname = "TestName"; + Workbook wb = getMyWorkbook(); // retrieve workbook + + // retrieve the named range + int namedCellIdx = wb.getNameIndex(cellName); + Name aNamedCell = wb.getNameAt(namedCellIdx); + + // retrieve the cell at the named range and test its contents + AreaReference aref = new AreaReference(aNamedCell.getRefersToFormula()); + CellReference[] crefs = aref.getAllReferencedCells(); + for (int i=0; i<crefs.length; i++) { + Sheet s = wb.getSheet(crefs[i].getSheetName()); + Row r = sheet.getRow(crefs[i].getRow()); + Cell c = r.getCell(crefs[i].getCol()); + // extract the cell contents based on cell type etc. + } + +

+ Reading from non-contiguous Named Ranges +

+ + // Setup code + String cname = "TestName"; + Workbook wb = getMyWorkbook(); // retrieve workbook + + // Retrieve the named range + // Will be something like "$C$10,$D$12:$D$14"; + int namedCellIdx = wb.getNameIndex(cellName); + Name aNamedCell = wb.getNameAt(namedCellIdx); + + // Retrieve the cell at the named range and test its contents + // Will get back one AreaReference for C10, and + // another for D12 to D14 + AreaReference[] arefs = AreaReference.generateContiguous(aNamedCell.getRefersToFormula()); + for (int i=0; i<arefs.length; i++) { + // Only get the corners of the Area + // (use arefs[i].getAllReferencedCells() to get all cells) + CellReference[] crefs = arefs[i].getCells(); + for (int j=0; j<crefs.length; j++) { + // Check it turns into real stuff + Sheet s = wb.getSheet(crefs[j].getSheetName()); + Row r = s.getRow(crefs[j].getRow()); + Cell c = r.getCell(crefs[j].getCol()); + // Do something with this corner cell + } + } + +

+ Note, when a cell is deleted, Excel does not delete the + attached named range. As result, workbook can contain + named ranges that point to cells that no longer exist. + You should check the validity of a reference before + constructing AreaReference +

+ + if(name.isDeleted()){ + //named range points to a deleted cell. + } else { + AreaReference ref = new AreaReference(name.getRefersToFormula()); + } + +
+ +
Cell Comments - HSSF and XSSF +

+ A comment is a rich text note that is attached to & + associated with a cell, separate from other cell content. + Comment content is stored separate from the cell, and is displayed in a drawing object (like a text box) + that is separate from, but associated with, a cell +

+ + Workbook wb = new XSSFWorkbook(); //or new HSSFWorkbook(); + + CreationHelper factory = wb.getCreationHelper(); + + Sheet sheet = wb.createSheet(); + + Rowl row = sheet.createRow(3); + Cell cell = row.createCell(5); + cell.setCellValue("F4"); + + Drawing drawing = sheet.createDrawingPatriarch(); + + // When the comment box is visible, have it show in a 1x3 space + ClientAnchor anchor = factory.createClientAnchor(); + anchor.setCol1(cell.getColumnIndex()); + anchor.setCol2(cell.getColumnIndex()+1); + anchor.setRow1(row.getRowNul()); + anchor.setRow2(row.getRowNul()+3); + + // Create the comment and set the text+author + Comment comment = drawing.createCellComment(anchor); + RichTextString str = factory.createRichTextString("Hello, World!"); + comment.setString(str); + comment.setAuthor("Apache POI"); + + // Assign the comment to the cell + cell.setCellComment(comment); + + String fname = "comment-xssf.xls"; + if(wb instanceof XSSFWorkbook) fname += "x"; + FileOutputStream out = new FileOutputStream(fname); + wb.write(out); + out.close(); + +

+ Reading cell comments +

+ + Cell cell = sheet.get(3).getColumn((short)1); + Comment comment = cell.getCellComment(); + if (comment != null) { + RichTextString str = comment.getString(); + String author = comment.getAuthor(); + } + // alternatively you can retrieve cell comments by (row, column) + comment = sheet.getCellComment(3, 1); + +
+ + +
Adjust column width to fit the contents + + Sheet sheet = workbook.getSheetAt(0); + sheet.autoSizeColumn(0); //adjust width of the first column + sheet.autoSizeColumn(1); //adjust width of the second column + +

+ Note, that Sheet#autoSizeColumn() does not evaluate formula cells, + the width of formula cells is calculated based on the cached formula result. + If your workbook has many formulas then it is a good idea to evaluate them before auto-sizing. +

+ + To calculate column width Sheet.autoSizeColumn uses Java2D classes + that throw exception 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: java.awt.headless=true . + +
+ +
How to read hyperlinks + + Sheet sheet = workbook.getSheetAt(0); + + Cell cell = sheet.getRow(0).getCell((short)0); + Hyperlink link = cell.getHyperlink(); + if(link != null){ + System.out.println(link.getAddress()); + } + +
+
How to create hyperlinks + + Workbook wb = new XSSFWorkbook(); //or new HSSFWorkbook(); + CreationHelper createHelper = wb.getCreationHelper(); + + //cell style for hyperlinks + //by default hyperlinks are blue and underlined + CellStyle hlink_style = wb.createCellStyle(); + Font hlink_font = wb.createFont(); + hlink_font.setUnderline(Font.U_SINGLE); + hlink_font.setColor(IndexedColors.BLUE.getIndex()); + hlink_style.setFont(hlink_font); + + Cell cell; + Sheet sheet = wb.createSheet("Hyperlinks"); + //URL + cell = sheet.createRow(0).createCell((short)0); + cell.setCellValue("URL Link"); + + Hyperlink link = createHelper.createHyperlink(Hyperlink.LINK_URL); + link.setAddress("http://poi.apache.org/"); + cell.setHyperlink(link); + cell.setCellStyle(hlink_style); + + //link to a file in the current directory + cell = sheet.createRow(1).createCell((short)0); + cell.setCellValue("File Link"); + link = createHelper.createHyperlink(Hyperlink.LINK_FILE); + link.setAddress("link1.xls"); + cell.setHyperlink(link); + cell.setCellStyle(hlink_style); + + //e-mail link + cell = sheet.createRow(2).createCell((short)0); + cell.setCellValue("Email Link"); + link = createHelper.createHyperlink(Hyperlink.LINK_EMAIL); + //note, if subject contains white spaces, make sure they are url-encoded + link.setAddress("mailto:poi@apache.org?subject=Hyperlinks"); + cell.setHyperlink(link); + cell.setCellStyle(hlink_style); + + //link to a place in this workbook + + //create a target sheet and cell + Sheet sheet2 = wb.createSheet("Target Sheet"); + sheet2.createRow(0).createCell((short)0).setCellValue("Target Cell"); + + cell = sheet.createRow(3).createCell((short)0); + cell.setCellValue("Worksheet Link"); + Hyperlink link2 = createHelper.createHyperlink(Hyperlink.LINK_DOCUMENT); + link2.setAddress("'Target Sheet'!A1"); + cell.setHyperlink(link2); + cell.setCellStyle(hlink_style); + + FileOutputStream out = new FileOutputStream("hyperinks.xlsx"); + wb.write(out); + out.close(); + +
+ +
Data Validations +

+ As of version 3.8, POI has slightly different syntax to work with data validations with .xls and .xlsx formats. +

+
+ hssf.usermodel (binary .xls format) +

Check the value a user enters into a cell against one or more predefined value(s).

+

The following code will limit the value the user can enter into cell A1 to one of three integer values, 10, 20 or 30.

+ + HSSFWorkbook workbook = new HSSFWorkbook(); + HSSFSheet sheet = workbook.createSheet("Data Validation"); + CellRangeAddressList addressList = new CellRangeAddressList( + 0, 0, 0, 0); + DVConstraint dvConstraint = DVConstraint.createExplicitListConstraint( + new String[]{"10", "20", "30"}); + DataValidation dataValidation = new HSSFDataValidation + (addressList, dvConstraint); + dataValidation.setSuppressDropDownArrow(true); + sheet.addValidationData(dataValidation); + +

Drop Down Lists:

+

This code will do the same but offer the user a drop down list to select a value from.

+ + HSSFWorkbook workbook = new HSSFWorkbook(); + HSSFSheet sheet = workbook.createSheet("Data Validation"); + CellRangeAddressList addressList = new CellRangeAddressList( + 0, 0, 0, 0); + DVConstraint dvConstraint = DVConstraint.createExplicitListConstraint( + new String[]{"10", "20", "30"}); + DataValidation dataValidation = new HSSFDataValidation + (addressList, dvConstraint); + dataValidation.setSuppressDropDownArrow(false); + sheet.addValidationData(dataValidation); + +

Messages On Error:

+

To create a message box that will be shown to the user if the value they enter is invalid.

+ + dataValidation.setErrorStyle(DataValidation.ErrorStyle.STOP); + dataValidation.createErrorBox("Box Title", "Message Text"); + +

Replace 'Box Title' with the text you wish to display in the message box's title bar + and 'Message Text' with the text of your error message.

+

Prompts:

+

To create a prompt that the user will see when the cell containing the data validation receives focus

+ + dataValidation.createPromptBox("Title", "Message Text"); + dataValidation.setShowPromptBox(true); + +

The text encapsulated in the first parameter passed to the createPromptBox() method will appear emboldened + and as a title to the prompt whilst the second will be displayed as the text of the message. + The createExplicitListConstraint() method can be passed and array of String(s) containing interger, floating point, dates or text values.

+ +

Further Data Validations:

+

To obtain a validation that would check the value entered was, for example, an integer between 10 and 100, + use the DVConstraint.createNumericConstraint(int, int, String, String) factory method.

+ + dvConstraint = DVConstraint.createNumericConstraint( + DVConstraint.ValidationType.INTEGER, + DVConstraint.OperatorType.BETWEEN, "10", "100"); + +

Look at the javadoc for the other validation and operator types; also note that not all validation + types are supported for this method. The values passed to the two String parameters can be formulas; the '=' symbol is used to denote a formula

+ + dvConstraint = DVConstraint.createNumericConstraint( + DVConstraint.ValidationType.INTEGER, + DVConstraint.OperatorType.BETWEEN, "=SUM(A1:A3)", "100"); + +

It is not possible to create a drop down list if the createNumericConstraint() method is called, + the setSuppressDropDownArrow(false) method call will simply be ignored.

+

Date and time constraints can be created by calling the createDateConstraint(int, String, String, String) + or the createTimeConstraint(int, String, String). Both are very similar to the above and are explained in the javadoc.

+

Creating Data Validations From Spreadsheet Cells.

+

The contents of specific cells can be used to provide the values for the data validation + and the DVConstraint.createFormulaListConstraint(String) method supports this. + To specify that the values come from a contiguous range of cells do either of the following:

+ + dvConstraint = DVConstraint.createFormulaListConstraint("$A$1:$A$3"); + +

or

+ + Name namedRange = workbook.createName(); + namedRange.setNameName("list1"); + namedRange.setRefersToFormula("$A$1:$A$3"); + dvConstraint = DVConstraint.createFormulaListConstraint("list1"); + +

and in both cases the user will be able to select from a drop down list containing the values from cells A1, A2 and A3.

+

The data does not have to be as the data validation. To select the data from a different sheet however, the sheet + must be given a name when created and that name should be used in the formula. So assuming the existence of a sheet named 'Data Sheet' this will work:

+ + Name namedRange = workbook.createName(); + namedRange.setNameName("list1"); + namedRange.setRefersToFormula("'Data Sheet'!$A$1:$A$3"); + dvConstraint = DVConstraint.createFormulaListConstraint("list1"); + +

as will this:

+ + dvConstraint = DVConstraint.createFormulaListConstraint("'Data Sheet'!$A$1:$A$3"); + +

whilst this will not:

+ + Name namedRange = workbook.createName(); + namedRange.setNameName("list1"); + namedRange.setRefersToFormula("'Sheet1'!$A$1:$A$3"); + dvConstraint = DVConstraint.createFormulaListConstraint("list1"); +

and nor will this:

+ dvConstraint = DVConstraint.createFormulaListConstraint("'Sheet1'!$A$1:$A$3"); + +
+
+ xssf.usermodel (.xlsx format) +

+Data validations work similarly when you are creating an xml based, SpreadsheetML, +workbook file; but there are differences. Explicit casts are required, for example, +in a few places as much of the support for data validations in the xssf stream was +built into the unifying ss stream, of which more later. Other differences are +noted with comments in the code. +

+ +

Check the value the user enters into a cell against one or more predefined value(s).

+ + XSSFWorkbook workbook = new XSSFWorkbook(); + XSSFSheet sheet = workbook.createSheet("Data Validation"); + XSSFDataValidationHelper dvHelper = new XSSFDataValidationHelper(sheet); + XSSFDataValidationConstraint dvConstraint = (XSSFDataValidationConstraint) + dvHelper.createExplicitListConstraint(new String[]{"11", "21", "31"}); + CellRangeAddressList addressList = new CellRangeAddressList(0, 0, 0, 0); + XSSFDataValidation validation =(XSSFDataValidation)dvHelper.createValidation( + dvConstraint, addressList); + + // Here the boolean value false is passed to the setSuppressDropDownArrow() + // method. In the hssf.usermodel examples above, the value passed to this + // method is true. + validation.setSuppressDropDownArrow(false); + + // Note this extra method call. If this method call is omitted, or if the + // boolean value false is passed, then Excel will not validate the value the + // user enters into the cell. + validation.setShowErrorBox(true); + sheet.addValidationData(validation); + + +

Drop Down Lists:

+

This code will do the same but offer the user a drop down list to select a value from.

+ + XSSFWorkbook workbook = new XSSFWorkbook(); + XSSFSheet sheet = workbook.createSheet("Data Validation"); + XSSFDataValidationHelper dvHelper = new XSSFDataValidationHelper(sheet); + XSSFDataValidationConstraint dvConstraint = (XSSFDataValidationConstraint) + dvHelper.createExplicitListConstraint(new String[]{"11", "21", "31"}); + CellRangeAddressList addressList = new CellRangeAddressList(0, 0, 0, 0); + XSSFDataValidation validation = (XSSFDataValidation)dvHelper.createValidation( + dvConstraint, addressList); + validation.setShowErrorBox(true); + sheet.addValidationData(validation); + +

Note that the call to the setSuppressDropDowmArrow() method can either be simply excluded or replaced with:

+ + validation.setSuppressDropDownArrow(true); + + +

Prompts and Error Messages:

+

+These both exactly mirror the hssf.usermodel so please refer to the 'Messages On Error:' and 'Prompts:' sections above. +

+ +

Further Data Validations:

+

+To obtain a validation that would check the value entered was, for example, +an integer between 10 and 100, use the XSSFDataValidationHelper(s) createNumericConstraint(int, int, String, String) factory method. +

+ + + XSSFDataValidationConstraint dvConstraint = (XSSFDataValidationConstraint) + dvHelper.createNumericConstraint( + XSSFDataValidationConstraint.ValidationType.INTEGER, + XSSFDataValidationConstraint.OperatorType.BETWEEN, + "10", "100"); + +

+The values passed to the final two String parameters can be formulas; the '=' symbol is used to denote a formula. +Thus, the following would create a validation the allows values only if they fall between the results of summing two cell ranges +

+ + XSSFDataValidationConstraint dvConstraint = (XSSFDataValidationConstraint) + dvHelper.createNumericConstraint( + XSSFDataValidationConstraint.ValidationType.INTEGER, + XSSFDataValidationConstraint.OperatorType.BETWEEN, + "=SUM(A1:A10)", "=SUM(B24:B27)"); + +

+It is not possible to create a drop down list if the createNumericConstraint() method is called, +the setSuppressDropDownArrow(true) method call will simply be ignored. +

+

+Please check the javadoc for other constraint types as examples for those will not be included here. +There are, for example, methods defined on the XSSFDataValidationHelper class allowing you to create +the following types of constraint; date, time, decimal, integer, numeric, formula, text length and custom constraints. +

+

Creating Data Validations From Spread Sheet Cells:

+

+One other type of constraint not mentioned above is the formula list constraint. +It allows you to create a validation that takes it value(s) from a range of cells. This code +

+ +XSSFDataValidationConstraint dvConstraint = (XSSFDataValidationConstraint) + dvHelper.createFormulaListConstraint("$A$1:$F$1"); + + +

+would create a validation that took it's values from cells in the range A1 to F1. +

+

+The usefulness of this technique can be extended if you use named ranges like this; +

+ + + XSSFName name = workbook.createName(); + name.setNameName("data"); + name.setRefersToFormula("$B$1:$F$1"); + XSSFDataValidationHelper dvHelper = new XSSFDataValidationHelper(sheet); + XSSFDataValidationConstraint dvConstraint = (XSSFDataValidationConstraint) + dvHelper.createFormulaListConstraint("data"); + CellRangeAddressList addressList = new CellRangeAddressList( + 0, 0, 0, 0); + XSSFDataValidation validation = (XSSFDataValidation) + dvHelper.createValidation(dvConstraint, addressList); + validation.setSuppressDropDownArrow(true); + validation.setShowErrorBox(true); + sheet.addValidationData(validation); + +

+OpenOffice Calc has slightly different rules with regard to the scope of names. +Excel supports both Workbook and Sheet scope for a name but Calc does not, it seems only to support Sheet scope for a name. +Thus it is often best to fully qualify the name for the region or area something like this; +

+ + XSSFName name = workbook.createName(); + name.setNameName("data"); + name.setRefersToFormula("'Data Validation'!$B$1:$F$1"); + .... + +

+This does open a further, interesting opportunity however and that is to place all of the data for the validation(s) into named ranges of cells on a hidden sheet within the workbook. These ranges can then be explicitly identified in the setRefersToFormula() method argument. +

+
+
ss.usermodel +

+The classes within the ss.usermodel package allow developers to create code that can be used +to generate both binary (.xls) and SpreadsheetML (.xlsx) workbooks. +

+

+The techniques used to create data validations share much in common with the xssf.usermodel examples above. +As a result just one or two examples will be presented here. +

+

Check the value the user enters into a cell against one or more predefined value(s).

+ + Workbook workbook = new XSSFWorkbook(); // or new HSSFWorkbook + Sheet sheet = workbook.createSheet("Data Validation"); + DataValidationHelper dvHelper = sheet.getDataValidationHelper(); + DataValidationConstraint dvConstraint = dvHelper.createExplicitListConstraint( + new String[]{"13", "23", "33"}); + CellRangeAddressList addressList = new CellRangeAddressList(0, 0, 0, 0); + DataValidation validation = dvHelper.createValidation( + dvConstraint, addressList); + // Note the check on the actual type of the DataValidation object. + // If it is an instance of the XSSFDataValidation class then the + // boolean value 'false' must be passed to the setSuppressDropDownArrow() + // method and an explicit call made to the setShowErrorBox() method. + if(validation instanceof XSSFDataValidation) { + validation.setSuppressDropDownArrow(false); + validation.setShowErrorBox(true); + } + else { + // If the Datavalidation contains an instance of the HSSFDataValidation + // class then 'true' should be passed to the setSuppressDropDownArrow() + // method and the call to setShowErrorBox() is not necessary. + validation.setSuppressDropDownArrow(true); + } + sheet.addValidationData(validation); + + +

Drop Down Lists:

+ +

This code will do the same but offer the user a drop down list to select a value from.

+ + + Workbook workbook = new XSSFWorkbook(); // or new HSSFWorkbook + Sheet sheet = workbook.createSheet("Data Validation"); + DataValidationHelper dvHelper = sheet.getDataValidationHelper(); + DataValidationConstraint dvConstraint = dvHelper.createExplicitListConstraint( + new String[]{"13", "23", "33"}); + CellRangeAddressList addressList = new CellRangeAddressList(0, 0, 0, 0); + DataValidation validation = dvHelper.createValidation( + dvConstraint, addressList); + // Note the check on the actual type of the DataValidation object. + // If it is an instance of the XSSFDataValidation class then the + // boolean value 'false' must be passed to the setSuppressDropDownArrow() + // method and an explicit call made to the setShowErrorBox() method. + if(validation instanceof XSSFDataValidation) { + validation.setSuppressDropDownArrow(true); + validation.setShowErrorBox(true); + } + else { + // If the Datavalidation contains an instance of the HSSFDataValidation + // class then 'true' should be passed to the setSuppressDropDownArrow() + // method and the call to setShowErrorBox() is not necessary. + validation.setSuppressDropDownArrow(false); + } + sheet.addValidationData(validation); + + +

Prompts and Error Messages:

+

+These both exactly mirror the hssf.usermodel so please refer to the 'Messages On Error:' and 'Prompts:' sections above. +

+

+As the differences between the ss.usermodel and xssf.usermodel examples are small - +restricted largely to the way the DataValidationHelper is obtained, the lack of any +need to explicitly cast data types and the small difference in behaviour between +the hssf and xssf interpretation of the setSuppressDropDowmArrow() method, +no further examples will be included in this section. +

+

Advanced Data Validations.

+

Dependent Drop Down Lists.

+

+In some cases, it may be necessary to present to the user a sheet which contains more than one drop down list. +Further, the choice the user makes in one drop down list may affect the options that are presented to them in +the second or subsequent drop down lists. One technique that may be used to implement this behaviour will now be explained. +

+

+There are two keys to the technique; one is to use named areas or regions of cells to hold the data for the drop down lists, +the second is to use the INDIRECT() function to convert between the name and the actual addresses of the cells. +In the example section there is a complete working example- called LinkedDropDownLists.java - +that demonstrates how to create linked or dependent drop down lists. Only the more relevant points are explained here. +

+

+To create two drop down lists where the options shown in the second depend upon the selection made in the first, +begin by creating a named region of cells to hold all of the data for populating the first drop down list. +Next, create a data validation that will look to this named area for its data, something like this; +

+ + CellRangeAddressList addressList = new CellRangeAddressList(0, 0, 0, 0); + DataValidationHelper dvHelper = sheet.getDataValidationHelper(); + DataValidationConstraint dvConstraint = dvHelper.createFormulaListConstraint( + "CHOICES"); + DataValidation validation = dvHelper.createValidation( + dvConstraint, addressList); + sheet.addValidationData(validation); + +

+Note that the name of the area - in the example above it is 'CHOICES' - +is simply passed to the createFormulaListConstraint() method. This is sufficient +to cause Excel to populate the drop down list with data from that named region. +

+

+Next, for each of the options the user could select in the first drop down list, +create a matching named region of cells. The name of that region should match the +text the user could select in the first drop down list. Note, in the example, +all upper case letters are used in the names of the regions of cells. +

+ +

+Now, very similar code can be used to create a second, linked, drop down list; +

+ + + CellRangeAddressList addressList = new CellRangeAddressList(0, 0, 1, 1); + DataValidationConstraint dvConstraint = dvHelper.createFormulaListConstraint( + "INDIRECT(UPPER($A$1))"); + DataValidation validation = dvHelper.createValidation( + dvConstraint, addressList); + sheet.addValidationData(validation); + + +

+The key here is in the following Excel function - INDIRECT(UPPER($A$1)) - which is used to populate the second, +linked, drop down list. Working from the inner-most pair of brackets, it instructs Excel to look +at the contents of cell A1, to convert what it reads there into upper case – as upper case letters are used +in the names of each region - and then convert this name into the addresses of those cells that contain +the data to populate another drop down list. +

+
+
+ +
Embedded Objects +

It is possible to perform more detailed processing of an embedded Excel, Word or PowerPoint document, + or to work with any other type of embedded object.

+

HSSF:

+ + POIFSFileSystem fs = new POIFSFileSystem(new FileInputStream("excel_with_embeded.xls")); + HSSFWorkbook workbook = new HSSFWorkbook(fs); + for (HSSFObjectData obj : workbook.getAllEmbeddedObjects()) { + //the OLE2 Class Name of the object + String oleName = obj.getOLE2ClassName(); + if (oleName.equals("Worksheet")) { + DirectoryNode dn = (DirectoryNode) obj.getDirectory(); + HSSFWorkbook embeddedWorkbook = new HSSFWorkbook(dn, fs, false); + //System.out.println(entry.getName() + ": " + embeddedWorkbook.getNumberOfSheets()); + } else if (oleName.equals("Document")) { + DirectoryNode dn = (DirectoryNode) obj.getDirectory(); + HWPFDocument embeddedWordDocument = new HWPFDocument(dn, fs); + //System.out.println(entry.getName() + ": " + embeddedWordDocument.getRange().text()); + } else if (oleName.equals("Presentation")) { + DirectoryNode dn = (DirectoryNode) obj.getDirectory(); + SlideShow embeddedPowerPointDocument = new SlideShow(new HSLFSlideShow(dn, fs)); + //System.out.println(entry.getName() + ": " + embeddedPowerPointDocument.getSlides().length); + } else { + if(obj.hasDirectoryEntry()){ + // The DirectoryEntry is a DocumentNode. Examine its entries to find out what it is + DirectoryNode dn = (DirectoryNode) obj.getDirectory(); + for (Iterator entries = dn.getEntries(); entries.hasNext();) { + Entry entry = (Entry) entries.next(); + //System.out.println(oleName + "." + entry.getName()); + } + } else { + // There is no DirectoryEntry + // Recover the object's data from the HSSFObjectData instance. + byte[] objectData = obj.getObjectData(); + } + } + } + +

XSSF:

+ + XSSFWorkbook workbook = new XSSFWorkbook("excel_with_embeded.xlsx"); + for (PackagePart pPart : workbook.getAllEmbedds()) { + String contentType = pPart.getContentType(); + // Excel Workbook - either binary or OpenXML + if (contentType.equals("application/vnd.ms-excel")) { + HSSFWorkbook embeddedWorkbook = new HSSFWorkbook(pPart.getInputStream()); + } + // Excel Workbook - OpenXML file format + else if (contentType.equals("application/vnd.openxmlformats-officedocument.spreadsheetml.sheet")) { + OPCPackage docPackage = OPCPackage.open(pPart.getInputStream()); + XSSFWorkbook embeddedWorkbook = new XSSFWorkbook(docPackage); + } + // Word Document - binary (OLE2CDF) file format + else if (contentType.equals("application/msword")) { + HWPFDocument document = new HWPFDocument(pPart.getInputStream()); + } + // Word Document - OpenXML file format + else if (contentType.equals("application/vnd.openxmlformats-officedocument.wordprocessingml.document")) { + OPCPackage docPackage = OPCPackage.open(pPart.getInputStream()); + XWPFDocument document = new XWPFDocument(docPackage); + } + // PowerPoint Document - binary file format + else if (contentType.equals("application/vnd.ms-powerpoint")) { + HSLFSlideShow slideShow = new HSLFSlideShow(pPart.getInputStream()); + } + // PowerPoint Document - OpenXML file format + else if (contentType.equals("application/vnd.openxmlformats-officedocument.presentationml.presentation")) { + OPCPackage docPackage = OPCPackage.open(pPart.getInputStream()); + XSLFSlideShow slideShow = new XSLFSlideShow(docPackage); + } + // Any other type of embedded object. + else { + System.out.println("Unknown Embedded Document: " + contentType); + InputStream inputStream = pPart.getInputStream(); + } + } + +
+ +

(Since POI-3.7)

+
Autofilters + + Workbook wb = new HSSFWorkbook(); //or new XSSFWorkbook(); + Sheet sheet = wb.createSheet(); + sheet.setAutoFilter(CellRangeAddress.valueOf("C5:F200")); + +
+ +
Conditional Formatting + + Workbook workbook = new HSSFWorkbook(); // or new XSSFWorkbook(); + Sheet sheet = workbook.createSheet(); + + SheetConditionalFormatting sheetCF = sheet.getSheetConditionalFormatting(); + + ConditionalFormattingRule rule1 = sheetCF.createConditionalFormattingRule(ComparisonOperator.EQUAL, "0"); + FontFormatting fontFmt = rule1.createFontFormatting(); + fontFmt.setFontStyle(true, false); + fontFmt.setFontColorIndex(IndexedColors.DARK_RED.index); + + BorderFormatting bordFmt = rule1.createBorderFormatting(); + bordFmt.setBorderBottom(BorderFormatting.BORDER_THIN); + bordFmt.setBorderTop(BorderFormatting.BORDER_THICK); + bordFmt.setBorderLeft(BorderFormatting.BORDER_DASHED); + bordFmt.setBorderRight(BorderFormatting.BORDER_DOTTED); + + PatternFormatting patternFmt = rule1.createPatternFormatting(); + patternFmt.setFillBackgroundColor(IndexedColors.YELLOW.index); + + ConditionalFormattingRule rule2 = sheetCF.createConditionalFormattingRule(ComparisonOperator.BETWEEN, "-10", "10"); + ConditionalFormattingRule [] cfRules = + { + rule1, rule2 + }; + + CellRangeAddress[] regions = { + CellRangeAddress.valueOf("A3:A5") + }; + + sheetCF.addConditionalFormatting(regions, cfRules); + +

See more examples on Excel conditional formatting in + ConditionalFormats.java +

+ +
+ +
Hiding and Un-Hiding Rows +

+ Using Excel, it is possible to hide a row on a worksheet by selecting that row (or rows), + right clicking once on the right hand mouse button and selecting 'Hide' from the pop=up menu that appears. +

+

+ To emulate this using POI, simply call the setZeroHeight() method on an instance of either + XSSFRow or HSSFRow (the method is defined on the ss.usermodel.Row interface that both classes implement), like this: +

+ + Workbook workbook = new XSSFWorkbook(); // OR new HSSFWorkbook() + Sheet sheet = workbook.createSheet(0); + Row row = workbook.createRow(0); + row.setZeroHeight(); + +

+ If the file were saved away to disc now, then the first row on the first sheet would not be visible. +

+

+ Using Excel, it is possible to unhide previously hidden rows by selecting the row above and the row below + the one that is hidden and then pressing and holding down the Ctrl key, the Shift and the pressing + the number 9 before releasing them all. +

+

+ To emulate this behaviour using POI do something like this: +

+ + Workbook workbook = WorkbookFactory.create(new File(.......)); + Sheet = workbook.getSheetAt(0); + Iterator<Row> row Iter = sheet.iterator(); + while(rowIter.hasNext()) { + Row row = rowIter.next(); + if(row.getZeroHeight()) { + row.setZeroHeight(false); + } + } + +

+ If the file were saved away to disc now, any previously hidden rows on the first sheet of the workbook would now be visible. +

+

+ The example illustrates two features. Firstly, that it is possible to unhide a row simply by calling the setZeroHeight() + method and passing the boolean value 'false'. Secondly, it ilustrates how to test whther a row is hidden or not. + Simply call the getZeroHeight() method and it will return 'true' if the row is hidden, 'false' otherwise. +

+
+ + diff --git a/src/documentation/content/xdocs/spreadsheet/record-generator.xml b/src/documentation/content/xdocs/spreadsheet/record-generator.xml new file mode 100644 index 0000000000..8ce8fe5d89 --- /dev/null +++ b/src/documentation/content/xdocs/spreadsheet/record-generator.xml @@ -0,0 +1,212 @@ + + + + + +
+ Record Generator HOWTO + + + + +
+ +
How to Use the Record Generator + +
History +

+ The record generator was born from frustration with translating + the Excel records to Java classes. Doing this manually is a time + consuming process. It's also very easy to make mistakes. +

+

+ A utility was needed to take the defintition of what a + record looked like and do all the boring and repetitive work. +

+
+ +
Capabilities +

+ The record generator takes XML as input and produces the following + output: +

+
    +
  • A Java file capabile of decoding and encoding the record.
    • +
  • A test class that provides a fill-in-the-blanks implementation + of a test case for ensuring the record operates as + designed.
    • +
+
+
Usage +

+ The record generator is invoked as an Ant target + (generate-records). It goes through looking for all files in + src/records/defintitions ending with _record.xml. + It then creates two files; the Java record definition and the + Java test case template. +

+

+ The records themselves have the following general layout: +

+ + The frame record indicates whether there is a border + around the displayed text of a chart. + Glen Stampoultzis (glens at apache.org) + + + + + + + + + + + + ]]> +

+ The following table details the allowable types and sizes for + the fields. +

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TypeSizeJava Type
int1byte
int2short
int4int
int8long
intvarwordarray of shorts
bits1A byte comprising of a bits (defined by the bit element) +
bits2An short comprising of a bits
bits4A int comprising of a bits
float8double
hbstringjava expressionString
+

+ The Java records are regenerated each time the record generator is + run, however the test stubs are only created if the test stub does + not already exist. What this means is that you may change test + stubs but not the generated records. +

+
+
Custom Field Types +

+ Occationally the builtin types are not enough. More control + over the encoding and decoding of the streams is required. This + can be achieved using a custom type. +

+

+ A custom type lets you escape to java to define the way in which + the field encodes and decodes. To code a custom type you + declare your field like this: +

+ + ]]> +

+ Where the class name specified after custom: is a + class implementing the interface CustomField. +

+

+ You can then implement the encoding yourself. +

+
+
How it Works +

+ The record generation works by taking an XML file and styling it + using XLST. Given that XSLT is a little limited in some ways it was + necessary to add a little Java code to the mix. +

+

+ See record.xsl, record_test.xsl, FieldIterator.java, + RecordUtil.java, RecordGenerator.java +

+

+ There is a corresponding "type" generator for HWPF. + See the HWPF documentation for details. +

+
+
Limitations +

+ The record generator does not handle all possible record types and + goes not intend to perform this function. When dealing with a + non-standard record sometimes the cost-benifit of coding the + record by hand will be greater than attempting modify the + generator. The main point of the record generator is to save + time, so keep that in mind. +

+

+ Currently the the XSL file that generates the record calls out to + Java objects. The Java code for the record generation is + currently quite messy with minimal comments. +

+
+
+ + diff --git a/src/documentation/content/xdocs/spreadsheet/use-case.xml b/src/documentation/content/xdocs/spreadsheet/use-case.xml new file mode 100644 index 0000000000..acd66fc6e1 --- /dev/null +++ b/src/documentation/content/xdocs/spreadsheet/use-case.xml @@ -0,0 +1,200 @@ + + + + + +
+ HSSF Use Cases + + + +
+ +
HSSF Use Cases +
Use Case 1: Read existing HSSF + +

Primary Actor: HSSF client

+

Scope: HSSF

+

Level: Summary

+

Stakeholders and Interests:

+
    +
  • HSSF client- wants to read content + of HSSF file
    • +
  • HSSF - understands HSSF file
    • +
  • POIFS - understands underlying POI + file system
    • +
+

Precondition: None

+

Minimal Guarantee: None

+

Main Success Guarantee:

+
    +
  1. HSSF client requests HSSF to read + a HSSF file, providing an InputStream + containing HSSF file in question.
    2. +
  2. HSSF requests POIFS to read the HSSF + file, passing the InputStream + object to POIFS (POIFS use case 1, read existing file system)
    3. +
  3. HSSF reads the "Workbook" + file (use case 4, read workbook entry)
    4. +
+

Extensions:

+

2a. Exceptions +thrown by POIFS will be passed on to the HSSF client.

+
+
Use Case 2: Write HSSF file + +

Primary Actor: HSSF client

+

Scope: HSSF

+

Level: Summary

+

Stakeholders and Interests:

+
    +
  • HSSF client- wants to write file + out.
    • +
  • HSSF - knows how to write file + out.
    • +
  • POIFS - knows how to write file + system out.
    • +
+

Precondition:

+
    +
  • File has been + read (use case 1, read existing HSSF file) and subsequently modified + or file has been created (use case 3, create HSSF file)
    • +
+

Minimal Guarantee: None

+

Main Success Guarantee:

+
    +
  1. HSSF client + provides an OutputStream to + write the file to.
    2. +
  2. HSSF writes + the "Workbook" to its associated POIFS file system (use case + 5, write workbook entry)
    3. +
  3. HSSF + requests POIFS to write its file system out, using the OutputStream + obtained from the HSSF client (POIFS use case 2, write file system).
    4. +
+

Extensions:

+

3a. Exceptions +from POIFS are passed to the HSSF client.

+ +
+
Use Case 3:Create HSSF file + +

Primary Actor: HSSF client

+

Scope: HSSF

+

+Level: Summary

+

Stakeholders and Interests:

+
    +
  • HSSF client- wants to create a new + file.
    • +
  • HSSF - knows how to create a new + file.
    • +
  • POIFS - knows how to creat a new + file system.
    • +
+

Precondition:

+

Minimal Guarantee: None

+

Main Success Guarantee:

+
    +
  1. HSSF requests + POIFS to create a new file system (POIFS use case 3, create new file + system)
    2. +
+

Extensions: +None

+ +
+
Use Case 4: Read workbook entry +

Primary Actor: HSSF

+

Scope: HSSF

+

+Level: Summary

+

Stakeholders and Interests:

+
    +
  • HSSF - knows how to read the + workbook entry
    • +
  • POIFS - knows how to manage the file + system.
    • +
+

Precondition:

+
    +
  • The file + system has been read (use case 1, read existing HSSF file) or has + been created and written to (use case 3, create HSSF file system; + use case 5, write workbook entry).
    • +
+

Minimal +Guarantee: None

+

Main Success Guarantee:

+
    +
  1. + HSSF requests POIFS for the "Workbook" file
    2. +
  2. POIFS returns + an InputStream for the file.
    3. +
  3. HSSF reads + from the InputStream provided by POIFS
    4. +
  4. HSSF closes + the InputStream provided by POIFS
    5. +
+

Extensions:

+

3a. Exceptions +thrown by POIFS will be passed on

+
+
Use Case 5: Write workbook entry + + +

Primary Actor: HSSF

+

Scope: HSSF

+

+Level: Summary

+

Stakeholders and Interests:

+
    +
  • HSSF - knows how to manage the + write the workbook entry.
    • +
  • POIFS - knows how to manage the file + system.
    • +
+

Precondition: +

+
    +
  • Either an existing HSSF file has + been read (use case 1, read existing HSSF file) or an HSSF file has + been created (use case 3, create HSSF file).
    • +
+

Minimal Guarantee: None

+

Main Success Guarantee:

+
    +
  1. HSSF + checks the POIFS file system directory for the "Workbook" + file (POIFS use case 8, read file system directory)
    2. +
  2. If "Workbook" is in the directory, HSSF requests POIFS to + replace it with the new workbook entry (POIFS use case 4, replace file + in file system). Otherwise, HSSF requests POIFS to write the new + workbook file, with the name "Workbook" (POIFS use case 6, + write new file to file system)
    3. +
+

Extensions:None

+
+ +
+ + diff --git a/src/documentation/content/xdocs/spreadsheet/user-defined-functions.xml b/src/documentation/content/xdocs/spreadsheet/user-defined-functions.xml new file mode 100644 index 0000000000..bbc8434df9 --- /dev/null +++ b/src/documentation/content/xdocs/spreadsheet/user-defined-functions.xml @@ -0,0 +1,414 @@ + + + + + +
+ User Defined Functions + + + + +
+ +
How to Create and Use User Defined Functions + +
Description +

This document describes the User Defined Functions within POI. + User defined functions allow you to take code that is written in VBA + and re-write in Java and use within POI. Consider the following example.

+
+
An Example +

Suppose you are given a spreadsheet that can calculate the principal and interest + payments for a mortgage. The user enters the principal loan amount, the interest rate + and the term of the loan. The Excel spreadsheet does the rest.

+

+ mortgage calculation spreadsheet +

+

When you actually look at the workbook you discover that rather than having + the formula in a cell it has been written as VBA function. You review the + function and determine that it could be written in Java:

+

+ VBA code +

+

If we write a small program to try to evaluate this cell, we'll fail. Consider this source code:

+ +

If you run this code, you're likely to get the following error:

+ + + +

How would we make it so POI can use this sheet?

+
+ +
Defining Your Function +

To 'convert' this code to Java and make it available to POI you need to implement + a FreeRefFunction instance. FreeRefFunction is an interface in the org.apache.poi.ss.formula.functions + package. This interface defines one method, evaluate(ValueEval[] args, OperationEvaluationContext ec), + which is how you will receive the argument values from POI.

+

The evaluate() method as defined above is where you will convert the ValueEval instances to the + proper number types. The following code snippet shows you how to get your values:

+ + + +

The first thing we do is check the number of arguments being passed since there is no sense + in attempting to go further if you are missing critical information.

+

Next we declare our variables, in our case we need variables for:

+
    +
  • principal - the amount of the loan
    • +
  • rate - the interest rate as a decimal
    • +
  • years - the length of the loan in years
    • +
  • result - the result of the calculation
    • +
+

Next, we use the OperandResolver to convert the ValueEval instances to doubles, though not directly. + First we start by getting discreet values. Using the OperandResolver.getSingleValue() method + we retrieve each of the values passed in by the cell in the spreadsheet. Next, we use the + OperandResolver again to convert the ValueEval instances to doubles, in this case. This + class has other methods of coercion for gettings Strings, ints and booleans. Now that we've + got our primitive values we can move on to calculating the value.

+

As shown previously, we have the VBA source. We need to add code to our class to calculate + the payment. To do this you could simply add it to the method we've already created but I've + chosen to add it as its own method. Add the following method:

+ +

The biggest change necessary is related to the exponents; Java doesn't have a notation for this + so we had to add calls to Math.pow(). Now we need to add this call to our previous method:

+ +

Having done that, the last things we need to do are to check to make sure we didn't get a bad result and, + if not, we need to return the value. Add the following code to the class:

+ +

Then add a line of code to our evaluate method to call this new static method, complete our try/catch and return the value:

+ + +

So the whole class would be as follows:

+ + result is NaN or Infinity + */ + static final void checkValue(double result) throws EvaluationException { + if (Double.isNaN(result) || Double.isInfinite(result)) { + throw new EvaluationException(ErrorEval.NUM_ERROR); + } + } + +} + + ]]> + +

Great! Now we need to go back to our original program that failed to evaluate our cell and add code that will allow it run our new Java code.

+ +
+ +
Registering Your Function +

Now we need to register our function in the Workbook, so that the Formula Evaluator can resolve the name "calculatePayment" +and map it to the actual implementation (CalculateMortgage). This is done using the UDFFinder object. +The UDFFinder manages FreeRefFunctions which are our analogy for the VBA code. We need to create a UDFFinder. There are + a few things we need to know in order to do this:

+
    +
  • The name of the function in the VBA code (in our case it is calculatePayment)
    • +
  • The Class name of our FreeRefFunction
    • +
+

UDFFinder is actually an interface, so we need to use an actual implementation of this interface. Therefore we use the org.apache.poi.ss.formula.udf.DefaultUDFFinder class. If you refer to the Javadocs you'll see that this class expects to get two arrays, one + containing the alias and the other containing an instance of the class that will represent that alias. In our case our alias will be calculatePayment + and our class instance will be of the CalculateMortgage type. This class needs to be available at compile and runtime. Be sure to keep these arrays + well organized because you'll run into problems if these arrays are of different sizes or the alias aren't in the same relative position in their respective + arrays. Add the following code:

+ +

Now we have our UDFFinder instance and we've created the AggregatingUDFFinder instance. The last step is to pass this to our Workbook:

+ + +

So now the whole class will look like this:

+ +

Now that our evaluator is aware of the UDFFinder which in turn is aware of our FreeRefFunction, we're ready to re-run our example:

+ Evaluator mortgage-calculation.xls Sheet1!B4 +

which prints the following output in the console:

+ +

That is it! Now you can create Java code and register it, allowing your POI based appliction to run spreadsheets that previously were inaccessible.

+

This example can be found in the src/examples/src/org/apache/poi/ss/examples/formula folder in the source.

+
+
+ + + diff --git a/src/documentation/content/xdocs/status.xml b/src/documentation/content/xdocs/status.xml new file mode 100644 index 0000000000..79bafa2e4f --- /dev/null +++ b/src/documentation/content/xdocs/status.xml @@ -0,0 +1,1523 @@ + + + + + + + + + + + + + + + + + + + + + + + + 51585 - WorkbookFactory.create() hangs when creating a workbook + 55873 - Support for COUNTIFS function + 55723 - Inconsistent behavior in HSSFSheet.setAutoFilter() function, also make XSSF work when setAutoFilter is called multiple times + 51158 - Writing a workbook multiple times produces unreadable content + 45776 - Fix corrupt file problem using TextRun.setText + 41246 - AIOOBE with missing notes entries + 48593 - Multiple Saves Causes Slide Corruption + 55579 - Support embedding OLE objects into HSLF + 55818 - Add encryption support + 55731 - Fix StringBuilder logic in DataFormatter.cleanFormatForNumber + 55730 - Fix org.apache.poi.ss.usermodel.BuiltinFormats.java for 0x29-0x2c + 55901 - Avoid using RMI based exception from PropertySetFactory, as it's not needed nor helpful + 55850 - Fix NullPointerException during Xml-extraction from xslx + 55640 - Avoid IndexOutOfboundsException when setting nested row grouping + 55745 - fix handling of tables in XSSF if there are comments as well + 55560 - Patch for hiding slides in HSLF + 53176 - Fixed auto shapes render problem in pptx files + 55661 - CellStyle support for get/set Shrink To Fit + 49237 - HSSF Row Style XfIndex is 12 not 16 bits of data + 53475 - OOXML encrypted document fix for cspname being optional + 55733 - XWPFWordExtractor needs to handle .docx files with neither headers nor footers + 55729 - DataFormatter should format Error cells, returning the Excel error string + 55612 - Performance improvement in HSSFCellStyle.getDataFormatString() + 55611 - Performance improvement in DateUtil.isADateFormat(int, String) + 55578 - Support embedding OLE1.0 packages in HSSF + 49658 - Support embedding EMF/WMF pictures in HSSF + 52400 - Fix handling some types of TNEF files + 54400 - Updating the index in the LinkTable whenever sheets are removed + 49940 - Apply patch to avoid XmlValueDisconnectedException when saving a file twice + 55369 - Add support for collapsing rows in SXSSF + 55692 - Give a more helpful error if an Encrypted .xlsx file is passed to HSSF + 55650 - Avoid AIOOBE if a non-existant Xfs is requested for a style + 55658 - Don't fail in SXSSF if a numeric cell is overwritten with a string + 55341 - Constants for HAIR and DOTTED border styles are swapped + Add Eclipse project files + 55647 - When creating a temp file, ensure the name isn't already taken + 54722 - Extract text from HSLF tables + 55544 - Support for SHA-512 hashes on OOXML protected documents, as used by Office 2013 + + + 53798 - Add fix for XmlValueDisconnectException during shifting rows + 54524 - Fix handling of special case in FormulaShifter + 50298 - Fix corruption of Workbook when setting sheet order + 55419 - Fix SimpleFractionException when fraction goes to greater than overflow + 54786 - Add support for quoting in date formatting + 52233 - Do not make the XSSFSheet invalid during write() + 55195 - MultiOperandNumericFunction.collectValue() currently uses concrete final classes but should use interfaces instead + 55380 - Endless loop in CellRangeUtil.mergeRanges() when regions are overlapping + 55347/45551 - Integrate 55292 into XSSF extractors -- extract text from text boxes in xlsx files + 55361/Tika 792 - Avoid CTMarkup NoSuchMethodException stack trace by adding two beans to ooxml-lite" + 55294 and 52186 - Fix column grouping in XSSF. + 55292 - Enhancements to XSSFSimpleShape (textbox) including: ability to add multiple paragraphs, formatting (read/write) and text extraction. + 55191 - Avoid a ClassCastException if a HPSF string property isn't directly stored as a string + HSMF ascii encoding detection should use the CodePage properties where available + HSMF fixed length property parsing should be more forgiving of some type differences from the property default + 54233 - Some HPSF documents require UnicodeStrings to be 4-byte aligned, spot these from the otherwise invalid length + Upgrade version of JUnit to 4.11 to avoid problems when executing unit tests using Apache Ant >= 1.7 + + + 54925 - Avoid issues if the length of a StyleTextPropAtom prop is longer than the parent text + 54564 - Fix error message text for a workbook with no sheets when a sheet operation is performed + 53972 - Presence of PLV record shouldn't affect HSSF Data Validation + 55142 - Not all XWPF SDT blocks need newlines + 54920 - XSSFDrawing.createCellComment causes CommentsTable to lose reference to comment in cell A1 + 54982 - ExtractorFactory does not close files when extracting via OCPPackage.open() + 54607 - NullPointerException in XSSFSheet.getTopRow() when the top row is 1 + 54686 - Improve how DataFormatter handles fractions + 55066 - Don't load XWPF Footnotes twice + 54849 - Controlled content/Form (Std/StdBlock) content + github2 - HSSFWorkbook.getAllEmbeddedObjects() needs to recurse into container Shapes + github4 - Expose from XWPFParagraph the number level and format, if applied + github3 - Extract references from XWPF footnotes + 55053 - Update License links following ECMA site re-organisation + 49658 - Support embedding EMF/WMF pictures in HSSF + 55047 - REPT formula support + 55042 - COMPLEX formula support + 55041 - CODE formula support + 55001 - Support Unicode text (TextCharsAtom) in HSLF TextShape + 54682 - UnhandledDataStructure should sanity check before allocating, not after + 54673 - Simple wildcard support in HLOOKUP, VOOLKUP, MATCH, COUNTIF + 54625 - Register user-defined functions in instance scope instead of static + 54469 - Support for financial functions IPMT and PPMT + 54407 - Avoid XmlValueDisconnectedException when merging slides + 54356 - Support of statistical function SLOPE + 54403 - Support of statistical function INTERCEPT + 54557 - Don't mis-detect format patterns like .000 as dates + 54506 - Support unusual .xls files with a BOOK directory entry (normally it is Workbook) + 54508 - EDATE formula support + 53810 - NPOIFS fix for 0 not -1 padded partially used XBATs + 54402 - IfError handling of indirect references + 53966 - IfError support (from Analysis Toolpak) + 53650 - Prevent unreadable content and disalow to overwrite rows from input template in SXSSF + 54228,53672 - Fixed XSSF to read cells with missing R attribute + 54206 - Ensure that shared formuals are updated when shifting rows in a spreadsheet + Synchronize table headers with parent sheet in XSSF + 54210 - Fixed rendering text in flipped shapes in PPT2PNG and PPTX2PNG + + + 54188 - Avoid NPE in PPT2PNG + 52628 - Replace System.err info messages with a POILogger + 54137 - improved performance of DataFormatter with Fractions + 54099 - Ensure that CTHMerge and CTTcBorders go to poi-ooxml-schemas jar + 54111 - Fixed extracting text from table cells in HSLF + 52583 - add support for drop-down lists in doc to html convertion + 52863 - add workaround for files with broken CHP SPRMs + 53182 - Reading combined character styling and direct formatting of a character run + 52311 - Conversion to html : Problem in titles number + 53914 - TableRow#getTopBorder() return bottom's border + 53282 - Avoid exception when parsing OPC relationships with non-breaking spaces + 54016 - Avoid exception when parsing workbooks with DConRefRecord in row aggregate + 54008 - Fixed Ant build to support build directories with blanks + 53374 - Avoid exceptions when parsing hyperlinks of type "javascript://" + 53404 - Fixed compatibility bug with modifying xls files created by POI-3.6 and earlier + 53979 - Support fetching properties of Numbered Lists from PPT files + 53784 - Partial HSMF support for fixed sized properties + 53943 - added method processSymbol() to allow converting word symbols + 53763 - avoid style mess when using HSSFOptimiser + 52972 - preserve leading / trailing spaces in SXSSF + 53965 - Fixed XmlValueOutOfRangeExceptio calling getDataValidations for custom validations with XSSFSheet + 53974 - Avoid NPE when constructing HSSFWorbook on Google App Engine + 53568 - Fixed null returned by XSSFPicture.getPictureData() + 53950 - fixed setForceFormulaRecalculation to reset workbook-level "manual" flag + 52211 - avoid unnessary re-coverting content types to US-ASCII, it can cause exceptions on ibm mainframes + 53568 - Set shapes anchors in XSSF when reading from existing drawings + HSSFOptimiser will now also tidy away un-used cell styles, in addition to duplicate styles + 53493 - Fixed memory and temporary file leak in SXSSF + 53780 - Fixed memory and temporary file leak in SXSSF + 53380 - ArrayIndexOutOfBounds Excetion parsing word 97 document. + 53434 - Subtotal is not return correct value. + 53642 - [PATCH] XLS formula evaluation logging + 53561 - Unexpected adding of drawings into a workbook + 53413 - [GSoC] Improved work with shapes. HSSF + 53361 - feature: enhancements in EscherAggregate + 53302 - [Patch] EscherAggregate does not handle Continue records + 53144 - First comment not cloned after cloneSheet() + 53028 - Broken auto fit row height in the cells with word wrap + 53010 - [GSoC2012] Improve drawing support in HSSF + 52764 - Unmodified cell comments disappear after HSSFWorkbook.write + 52300 - Corrupted File after cloneSheet() + 52272 - [PATCH] Inserting images on cloned sheet with images. + 51796 - The [EscherClientAnchorRecord] for object (eg: TextBox,Shape) may get lost. + 51683 - [HSSF] Improve support for Shapes and Shape Groups + 51676 - Using drawingPatriarch.createCellComment(anchor) leads to File error: data may have been lost + 51675 - Background images cause problems in HSSF spreadsheet + 51455 - It would be really nice to be able to set the background picture of a comment + 51341 - Adding Image to Header in Excel Using HSSF + 51280 - when we insert a new image to the existing excel file that corrupts the previous images + 50696 - File Error: data may have been lost + 48989 - If we have a comment but the row is not created we will not be able to get it. + 48873 - Comments not saving in XLS files with collapsible columns + 48654 - Not able to read Excel (xls) file having drawing objects + 48590 - Excel chrashes after using removeCellComment methods + 46444 - cloning cloned sheet with autofilters corrupts the workbook + 45129 - Lost picture in file output after saving with POI + 47624 - File Error Data May Have been Lost error while opening commented workbook(excel file) + 46143 - setLineStyleColor for comments donot work + 53699 - Patch to correct BorderStyle enum positions + 53064 - Ugly Duckling case study + 53644 - XLS formula bugfix (CalFieldFunc) + WeekDay addon + 53446 - Fixed some problems extracting PNGs + 53205 - Fixed some parsing errors and encoding issues in HDGF + 53204 - Improved performanceof PageSettingsBlock in HSSF + 53500 - Getter for repeating rows and columns + 53369 - Fixed tests failing on JDK 1.7 + 53360 - Fixed SXSSF to correctly write text before escaped Unicode control character + Change HSMF Types to have full data on ID, Name and Length, rather than just being a simple ID + 48469 - Updated case study + 53476 - Support Complex Name in formulas + 53414 - properly update sheet dimensions when adding column + Add File based constructor to OPCPackage, alongside existing String one (which constructed a File from the string internally) + 53389 - Handle formatting General and @ formats even if a locale is prefixed to them + 53271 - Removed unconditional asserts in SXSSF + 53025 - Updatad documentation and example on using Data Validations + 53227 - Corrected AddDimensionedImage.java to support XSSF/SXSSF + 53058 - Utility for representing drawings contained in a binary Excel file as a XML tree + 53165 - HWPF support for fetching the description (alt text) of a picture + 48528 - support negative arguments to the DATE() function + 53092 - allow specifying of a TimeZone to DateUtil.getJavaDate(), for when it is known that a file comes from a different (known) timezone to the current machine + 53043 - don't duplicate hyperlink relationships when saving XSSF file + 53101 - fixed evaluation of SUM over cell range > 255 + 49529 - avoid exception when cloning sheets with no drawing records and initialized drawing patriarch + + + 52928 - DateFormatConverter: an utility to convert instances of java.text.DateFormat to Excel format patterns + 52895 - show SSTIndex instead of XFIndex in LabelSSTRecord.toString() + 52835 - Tolerate missing Count and UniqueCount attributes when parsing shared strings table in XSSF eventusermodel + 52818 - Added implementation for RANK() + 52682 - allow setting text with trailing carriage return in HSLF + 52244 - use correct text attributes when presentation has multiple TxMasterStyleAtoms of the same type + support setting background color of sheet tab in XSSF + 51564 - support for enforcing fields update in XWPF + 51673 - support grouping rows in SXSSF + 51780 - support replacement of content types in OPC packages + 52784 - replace ISO control characters with question marks in SXSSF to be consistent with XSSF + 52057 - updated formula test framework to be aware of recently added Functions + 52574 - support setting header / footer page margins in HSSF + 52583 - fixed WorkbookUtil#createSafeSheetName to escape colon + 51710 - fixed reading shared formulas in XSSF + 52708 - misc improvements in CellFormat + 52690 - added a getter for length of encrypted data in Ecma and Agile decryptors + 52255 - support adding TIFF,EPS and WPG pictures in OOXML documents + 52078 - avoid OutOfMemoryError when rendering groupped pictures in HSLF + 52745 - fixed XSSFRichtextString.append to preserve leading / trailing spaces + 52716 - tolerate hyperlinks that have neither location nor relation + 52599 - avoid duplicate text when rendering slides in HSLF + 52598 - respect slide background when rendering slides in HSLF + 51731 - fixed painting shape outlines in HSLF + 52701 - fixed seting vertical alignment for XSLFTableCell + 52687 - fixed merging slides with pictures with associated custom tags + allow runtime registration of functions in FormulaEvaluator + 52665 - When reading from a ZipFileZipEntrySource that has already been closed, give IllegalArgumentException rather than NPE + 52664 - MAPIMessage may not always have name chunks when checking for 7 bit encodings + 52649 - fixed namespace issue in WordToFoConverter + 52385 - avoid trancated array and vector data when reading OLE properties + 52662 - CharacterRun NPE fix when fetching symbol fonts, where no fonts are defined + 52658 - support mergin table cells in XSLF + validate row number and column index in SXSSF when creating new rows / cells + 51498 - fixed evaluation of blank cells in COUNTIF + 52576 - support changing external file references in HSSFWorkbook + 49896 - support external references in FormulaRenderer + 52527 - avoid exception when matching shared formula records in HSSF + 52568 - Added methods to set/get an XWPFRun's text color + 52566 - Added methods to set/get vertical alignment and color in XWPFTableCell + 52562 - Added methods to get/set a table row's Can't Split and Repeat Header attributes in XWPF + 52561 - Added methods to set table inside borders and cell margins in XWPF + 52569 - Support DConRefRecord in HSSF + 52575 - added an option to ignore missing workbook references in formula evaluator + Validate address of hyperlinks in XSSF + 52540 - Relax the M4.1 constraint on reading OOXML files, as some Office produced ones do have 2 Core Properties, despite the specification explicitly forbidding this + 52462 - Added implementation for SUMIFS() + POIXMLPropertiesTextExtractor support for extracting custom OOXML properties as text + 52449 - Support writing XWPF documents with glossaries (Glossaries are not yet supported, but can now be written out again without changes) + 52446 - Handle files which have been truncated by a few bytes in NPropertyTable + 52438 - Update CellDateFormatter to handle times without seconds + 52389 - Support ?/? as well as #/# fractions, and tighten DataFormatter rules for fraction matching + 52200 - Updated XWPF table example code + 52378 - Support for WORKDAY and NETWORKDAYS functions + 52349 - Merge the logic between the TEXT function and DataFormatter + 52349 - Correctly support excel style date format strings in the TEXT function + 52369 - XSSFExcelExtractor should format numeric cells based on the format strings applied to them + 52369 - Event based XSSF parsing should handle formatting of formula values in XSSFSheetXMLHandler + 52348 - Avoid exception when creating cell style in a workbook that has an empty xf table + 52219 - fixed XSSFSimpleShape to set rich text attributes from XSSFRichtextString + 52314 - enhanced SheetUtil.getColumnWidth + + + 52204 - Deprecated XSSFWorkbook(String path) constructor because it does not close underlying .zip file + 46288 - fixed refcount of Fill pictures in HSLF + 51961 - support compression of temp files in SXSSF + 52268 - support cloning sheets with drawings in XSSF + 52285 - Support XWPF smart tags text in Paragraphs + 51875 - More XSSF new-line in formula support + POIFS EntryUtils.copyNodes(POFS,POIFS) now uses FilteringDirectoryNode, so can exclude from copying nodes not just directly under the root + POIFS Helper FilteringDirectoryNode, which wraps a DirectoryEntry and allows certain parts to be ignored + 52209 - fixed inserting multiple pictures in XSLF + 51803 - fixed HSLF TextExtractor to extract content from master slide + 52190 - null check on XWPF setFontFamily + 52062 - ensure that temporary files in SXSSF are deleted + 50936 - Exception parsing MS Word 8.0 file (as duplicate of 47958) + 47958 - ArrayIndexOutOfBoundsException from PicturesTable.getAllPictures() during Escher tree walk + 51944 - PAPFormattedDiskPage.getPAPX - IndexOutOfBounds + 52032 - HWPF - ArrayIndexOutofBoundsException with no stack trace (broken after revision 1178063) + support for converting pptx files into images with a PPTX2PNG tool + 52050 - Support for the Excel RATE function + 51566 - HSLF fix for finishing parsing the picture stream on the first non-valid type + 51974 - Avoid HWPF issue when identifying the picture type + 52035 - Fix signed issue with very large word 6 files + 51949 - Avoid NPE on double close of ZipFileZipEntrySource + 51950 - XWPF fix for footnotes not always being present in a document + 51963 - Correct AreaReference handling of references containing a sheet name which includes a comma + 51955 - XSSFReader supplied StylesTables need to have the theme data available + 51716 - Removed incorrect assert in SXSSFSheet#getSXSSFSheet + 51834 - Opening and Writing .doc file results in corrupt document + 51902 - Picture.fillRawImageContent - ArrayIndexOutOfBoundsException (duplicate) + 51890 - ArrayIndexOutOfBounds ExceptionPicture.fillRawImageContent + Allow the passing of a File object to WorkbookFactory.create, which permits lower memory processing than the InputStream version + 51873 - update HSMF to ignore Outlook 2002 Olk10SideProp entries, which don't behave like normal chunks + 51850 - support creating comments in XSSF on an earlier slide when later ones already have them + 51804 - optionally include Master Slide text in XSLF text extraction, as HSLF already offers + New PackagePart method getRelatedPart(PackageRelationship) to simplify navigation of relations between OPC Parts + 51832 - handle XLS files where the WRITEPROTECT record preceeds the FILEPASS one, rather than following as normal + 51809 - correct GTE handling in COUNTIF + Add HWPF API to update range text and delete bookmarks + HWPF Bookmarks tables are correctly updated on text updates + 51670 - avoid LeftoverDataException when reading .xls files with invalid LabelRecords + 51196 - prevent NPE in XWPFPicture.getPictureData() + 51771 - prevent NPE when getting object data from OLEShape in HSLF + 51196 - more progress with Chart APi in XSSF + 51785 - Allow XSSF setForceFormulaRecalculation to work with the minimal ooxml-schemas jar + 51772 - IllegalArgumentException Parsing MS Word 97 - 2003 + XSLFPowerPointExtractor support for including comment authors with comment text + Converted XSLFPowerPointExtractor to use UserModel for all text extraction + XSLF initial UserModel support for Notes and Comments for Slides + HSLF: support for uncompressed OLE embeddings + + + 51678 - Extracting text from Bug51524.zip is slow + 51671 - HWPFDocument.write based on NPOIFSFileSystem throws a NullPointerException + support for tables and hyperlinks in XSLF + 51535 - correct signed vs unsigned short reading in NDocumentInputStream + 51634 - support SXSSF streaming from templates + initial support for XSLF usermodel API + 51187 - fixed OPCPackage to correctly handle self references + 51635 - Improved performance of XSSFSheet#write + 47731 - Word Extractor considers text copied from some website as an embedded object + Add Word-to-Text converter and use it as replacement for WordExtractor + 51604 - replace text fails for doc ( poi 3.8 beta release from download site ) + Fixed incorrect encoding of non-breaking space (0xA0) in SXSSF + Support for conditional formatting in XSSF + Support isRightToLeft and setRightToLeft on the common spreadsheet Sheet interface, as per existing HSSF support + 50209 - Fixed evaluation of Subtotals to ignore nested subtotals + 44431 - HWPFDocument.write destroys fields + 50401 - fixed EscherProperty to return property name instead of 'unknown' for complex properties + Initial support for endnotes and footnotes in HWPF + 51470 - avoid exception when cloning XSSF sheets with background images + 51481 - Fixed autofilters in HSSF to avoid warnings in Excel 2007 + 51533 - Avoid exception when changing name of a sheet containing shared formulas + Support for appending images to existing drawings in HSSF + Initial support for bookmarks in HWPF + 46250 - Fixed cloning worksheets with images + 51524 - PapBinTable constructor is slow (regression) + 51514 - allow HSSFObjectData to work with both POIFS and NPOIFS + 51514 - avoid NPE when copying nodes from one HSSF workbook to a new one, when opened from NPOIFS + 51504 - avoid NPE when DefaultRowHeight or DefaultColumnWidth records are missing + 51502 - Correct Subtotal function javadoc entry + Support for hyperlinks in SXSSF + 49933 - Word 6/95 documents with sections cause ArrayIndexOutOfBoundsException + 51469 - XSSF support for row styles, to match existing HSSF functionality + 51476 - Correct XSSF cell formatting in HTML export + 51486 - XWPF support for adding new footnotes + 48065 - Problems with save output of HWPF (losing formatting) + 47563 - Exception when working with table + 47287 - StringIndexOutOfBoundsException in CharacterRun.replaceText() + 46817 - Regression: Text from some table cells missing + Add getOverallRange() method to HWPFDocumentCore + PAPX referenced outside of TextPiecesTable are ignored now and not loaded + Fix main part range (and section) detection for files with additional parts (like footers/headers). + Fix wrong TextPiece parsing in very rare cases like Bug33519.doc + Inner tables are correctly supported + Allow user to retrieve Table nesting level (based on file information) + Functionality of internal tool HWPFLister is greatly improved, including output of document PAPX and paragraphs + Expand Word structures definitions (TAP, PAP, TLP, etc) based on official documentation + Add Excel-to-HTML converter (2007 versions) + Add Word-to-HTML converter (95-2007 versions) + Skip wrong-type SPRMs when characters SPRM is expected + Add toStrings() methods to internal HWPF structures: BorderCode, PAPX, Paragraph, PieceDescriptor, Section, SEPX, SprmOperation, TextPiece etc. + 51474 - SXSSF handling for null strings + 48294 - Fixed HSSFWorkbook.setSheetOrder() to respect inter-sheet references + 51448 - Avoid exception when evaluating workbooks with more than 256 sheets + 51458 - Correct BitField wrapping when setting large values + 51460 - Improve HSSF performance when loading very long rows, by switching the CellValue array to an iterator + 51444 - Prevent corrupted output when saving files created by LibreOffice 3.3 + 51422 - Support using RecalcIdRecord to trigger a full formula recalculation on load + 50474 - Example demonstrating how to update Excel workbook embedded in a WordprocessingML document + 51431 - Avoid IndexOutOfBoundException when removing freeze panes in XSSF + 48877 - Fixed XSSFRichTextString to respect leading and trailing line breaks + 49564 - Fixed default behaviour of XSSFCellStyle.getLocked() + 48314 - Fixed setting column and row breaks in XSSF + 51424 - Ignore exceptions in ParagraphSprmUncompressor + 51415 - Fixed Workbook.createSheet(sheetName) to truncate names longer than 31 characters + 51332 - Fixed internal IDs of shapes generated by HSSFPatriarch when there are more than 1023 drawing objects + 48408 - Improved documentation for Sheet.setColumnWidth + 51390 - Added handling of additional properties to HWPF ParagraphSprmCompressor + 51389 - Support for sprmPJc paragraph SPRM in HWPF + 48469 - New Case Study for POI web site + 50681 - Avoid exceptions in HSSFDataFormat.getDataFormatString() + 50681 - Fixed autosizing columns beyond 255 character limit + 51374 - Fixed incorrect setting of lastPrinted OOXML core property + 51351 - Word to XSL-FO converter + 50458 - Fixed missing shapeId in XSSF drawings + 51339 - Fixed arithmetic rounding in formula evaluation + 51356 - Support autoSizeColumn in SXSSF + 51335 - Parse picture goal and crop sizes in HWPF + 51305 - Add sprmTCellPaddingDefault support in HWPF + 51265 - Enhanced Handling of Picture Parts in XWPF + 51292 - Additional HWPF Table Cell Descriptor values + + + 51098 - Correctly calculate image width/height, if image fits into one cell + 47147 - Correct extra paragraphs from XWPF Table Cells + 51188 - Support for getting and setting XPWF zoom settings + 51134 - Support for adding Numbering and Styles to a XWPF document that doesn't already have them + 51273 - Formula Value Cache fix for repeated evaluations + 51171 - Improved performance of SharedValueManager + 51236 - XSSF set colour support for black/white to match getter + 51196 - Initial support for Spreadsheet Chart API + Add support for OOXML Agile Encryption + 51160 - Initial version of SXSSF, a low memory foortprint API to produce xlsx files + 51171 - Improved performance of opening large .xls files + 51172 - Add XWPF support for GIF pictures + NPOIFS Mini Streams now support extending the underlying big block stream to fit more data + 51148 - XWPFDocument now properly tracks paragraphs and tables when adding/removing them + 51153 - Correct sizing of LbsDataSubRecord with unused padding fields + 51143 - NameCommentRecord correction for writing non ASCII strings + 51112 - Correct XWPFTable tracking of new rows + 51113 - Correct XWPFParagraph tracking of inserted runs + 51111 - Correct XWPFParagraph tracking of new runs + 51115 - Handle DataFormatter escaping of "." in the same way as "-" and "/" + 51100 - Fix IOUtils issue for NPOIFS reading from an InputStream where every block is full + 50956 - Correct XSSF cell style cloning between workbooks + Add get/setForceFormulaRecalculation for XSSF, and promote the methods to the common usermodel Sheet + Tweak the logic for sizing the HSSFCells array on a HSSFRow to reduce memory over allocation in many use cases + 49765 - Support for adding a picture to a XSSFRun + Rename/Move xssf.model.Table to xssf.usermodel.XSSFTable as it now has usermodel-like features + 51061 - Correct target URI for new XSSF Tables + Initial support for XSSF Charts. Provides easy access to the underlying CTChart object via the Sheet Drawing, but no high level interface onto the chart contents as yet. + 50884 - XSSF and HSSF freeze panes now behave the same + Support for adding a table to a XSSFSheet + Improve HSMF MAPIMessage access to the HTML and RTF versions of the message body (where available) + Add new method to HSMF of MAPIMessage.has7BitEncodingStrings() to make it easier to decide when encoding guessing is needed + OutlookTextExtractor now requests 7 bit encoding guessing + Improve HSMF encoding guessing for 7 bit fields in MAPIMessage + Allow HSMF access to the HTML body contents in MAPIMessage + + + Implement the load method on MemoryPackagePart + 50967 - Support for continued ExtSSTRecords + 48968 - Support for HOUR, MINUTE and SECOND date formulas + Added NPOIFS constructors to most POIDocument classes and their extractors, and more widely deprecated the Document(DirectoryNode, POIFSFileSystem) constructor in favour of the more general Document(DirectoryNode) one + Fixed NPOIFS handling of new and empty Document Nodes + Fixed NPOIFS access to Document Nodes not in the top level directory + 50841 - Improved SpreadSheet DataFormatter to handle scientific notation, invalid dates and format spacers + 49381 - Correct createFreezePane in XSSF, so that the left row/column matches the documentation + HSSF + 49253 - When setting repeating rows and columns for XSSF, don't break the print settings if they were already there + 49219 - ExternalNameRecord support for DDE Link entries without an operation + 50846 - More XSSFColor theme improvements, this time for Cell Borders + 50939 - ChartEndObjectRecord is supposed to have 6 bytes at the end, but handle it not + HMEF - New component which supports TNEF (Transport Neutral Encoding Format), aka winmail.dat + 50313 - support for getting HWPFDocument fields + 50912 - fixed setting named styles to HSSFCells + 50779 - fixed RecordFormatException when reading unicode strings with photenic data + 50718 - More helpful error message when you try to create a CellReference with #REF! + 50784 - XSSFColors return by XSSFFont now have theme information applied to them + 50846 - Improve how XSSFColor inherits from Themes + 50847 - XSSFFont now accepts the full range of Charsets from FontChartset + 50786 - Speed up calls to HSSFColor.getIndexHash() by returning a cached, unmodifiable Map. HSSFColor.getModifiableIndexHash() provides access to the old (slow but modifiable) functionality + 47100 - Change related formulas and named ranges when XSSFWorkbook.setSheetName is called + + + 50610 - Ant tasks for running POI against a workbook + 32903 - Correct XBAT chaining explanation in /poifs/fileformat.html + 50829 - Support for getting the tables associated with a XSSFSheet + 50299 - More XSSFColor updates for ARGB vs RGB + 50581 - Use stax:stax-api instead of org.apache.geronimo.specs:geronimo-stax-api_1.0_spec + 50786 - Fix XSSFColor to fetch the RGB values of old-style indexed colours + 50299 - Fix XSSFColor fetching of white and black background themes + 50795 - Avoid NPE from xmlbeans when moving XSSF Comments from one cell to another + 46664 - When creating HSSF Print Areas, ensure the named range is reference based not value based + 50756 - When formatting numbers based on their Cell Style, treat GENERAL the same as the more typical General + fixed HSSFWorkbook.createCellStyle to throw exception if the maximum number of cell styles was exceeded + 50539 - Better fix for html-style br tags (invalid XML) inside XSSF documents + 49928 - allow overridden built-in formats in HSSFCellStyle + 50607 - Added implementation for CLEAN(), CHAR() and ADDRESS() + 50587 - Improved documentation on user-defined functions + Inside ExtractorFactory, support finding embedded OOXML documents and providing extractors for them + Partial HDGF LZW compression support + 50244 - Support for continued NameRecords + 50416 - Correct shifting of the first or last row in a sheet by multiple rows + 50440 - Support evaluating formulas with newlines in them, which XSSF may have (but HSSF may not) + Added inline string support to XSSF EventModel + 50246 - Properly position GutsRecord when reading HSSF workbooks + 48539 - Added implementation for MROUND(), VAR() and VARP() + 50446 - Code cleanup and optimizations to keep some IDE quiet + 50437 - Support passing ranges to NPV() + 50409 - Added implementation for IRR() + 47405 - Improved performance of RowRecordsAggregate.getStartRowNumberForBlock / getEndRowNumberForBlock + 50315 - Avoid crashing Excel when sorting XSSFSheet autofilter + 50076 - Allow access from XSSFReader to sheet comments and headers/footers + 50076 - Refactor XSSFEventBasedExcelExtractor to make it easier for you to have control over outputting the cell contents + 50258 - avoid corruption of XSSFWorkbook after applying XSSFRichTextRun#applyFont + 50154 - Allow white spaces and unicode in OPC relationship targets + 50113 - Remove cell from Calculation Chain after setting cell type to blank + 49966 - Ensure that XSSFRow#removeCell cleares calculation chain entries + 50096 - Fixed evaluation of cell references with column index greater than 255 + 49761 - Tolerate Double.NaN when reading .xls files + 50211 - Use cached formula result when auto-sizing formula cells + 50118 - OLE2 does allow a directory with an empty name, so support this in POIFS + 50119 - avoid NPE when XSSFReader comes across chart sheets + + + 50075 - avoid NPE in ListLevel.getNumberText() when numberText is null + 50067 - marked commons-logging and log4j as optional dependencies in POI poms + 49928 - allow overridden built-in formats in XSSFCellStyle + 49919 - support for BorderCode in HWPF + 49908 - support for processing of symbols in HWPF + 50022 - support for retrieving pictures from HSSF workbooks + 50020 - Avoid IllegalStateException when creating Data validation in sheet with macro + 50033 - Improved rounding in MOD + Generate SHA1 hashes of distribution files, alongside existing MD5 ones + + + 48325 - If a HSSF header or footer lacks left/right/centre information, assume it is a centre one + 49966 - Correctly remove calcChain entries for XSSF cells that stop holding formulas + 47582 - XSSFCellStyle support for creating a style in one workbook based on a style from a different one + 49931 - Avoid concurrency problems when re-ordering multiple HSSF header records for a PageSettingsBlock + 49765 - Fix XWPFDocument.addPicture so that it correctly sets up relationships + 48018 - Improve HWPF handling of lists in documents read and then saved, by preserving order better + 49820 - Fix HWPF paragraph levels, so that outline levels can be properly fetched + 47271 - Avoid infinite loops on broken HWPF documents with a corrupt CHP style with a parent of itself + 49936 - Handle HWPF documents with problematic HeaderStories better + 49933 - Support sections in Word 6 and Word 95 files (HWPFOldDocument) + 49941 - Correctly handle space preservation of XSSFRichTextRuns when applying fonts to parts of the string + Correct XWPFRun detection of bold/italic in a paragraph with multiple runs of different styles + Link XWPFPicture to XWPFRun, so that embedded pictures can be access from where they live in the text stream + Improve handling of Hyperlinks inside XWPFParagraph objects through XWPFHyperlinkRun + Make XWPFParagraph make more use of XWPFRun, and less on internal StringBuffers + Add a getBodyElements() method to XWPF IBody, to make access to embedded paragraphs and tables easier + More XSLFRelation entries for common .pptx file parts + 49872 - avoid exception in XSSFFormulaEvaluator.evaluateInCell when evaluating shared formulas + 49895 - avoid corruption of XSSFWorkbook after removing all merged cells from sheet + 49907 - fixed inconsistent behaviour between HSSF and XSSF when creating consecutive names + Add getMimeType() method to HWPF Picture, alongside existing file extension + Add code for reading Ole10Native data + Add getMimeType() method to HSSF/XSSF PictureData, alongside existing file extension + 49887 - allow sheet names longer than 31 chars in XSSF, enforce name uniqueness on the first 31 chars + 49878 - improved API for hiding sheets + 49875 - fixed XSSFWorkbook.createSheet to throw exception if sheet name begins or ends with a single quote (') + 49873 - fixed XSSFFormulaEvaluator to support blank cells + 49850 - added a getter for _iStartAt in ListFormatOverrideLevel + 49761 - change cell type to error when setting Double.NaN or Infinities + 49833 - ensure that CTNumPr is included in poi-ooxml-schemas.jar + 49841 - fixed LEFT and RIGHT to return #VALUE! when called with a negative operand + 49783 - fixed evaluation of XSSF workbooks containing formulas with reference errors (#REF!) + 49751 - fixed fetching names of user defined styles in HSSFCellStyle.getUserStyleName() + 48900 - support for protecting a XSSF workbook + 49725 - fixed FormulaParser to correctly process defined names with underscore + 48526 - added implementation for RANDBETWEEN() + 49725 - avoid exception in OperandResolver.parseDouble when input is minus ("-") + 49723 - fixed OperandResolver to correctly handle inputs with leading decimal place + initial support for Excel autofilter + + + 47990 - Support for .msg attachments within a MAPIMessage .msg + Improve handling and warnings when closing OPCPackage objects + 49702 - Correct XSSFWorkbook.getNumCellStyles to check the right styles list + 49690 - Add WorkbookUtil, which provies a way of generating valid sheet names + 49694 - Use DataFormatter when autosizing columns, to better match the real display width of formatted cells + 49441 - Allow overriding and guessing of HSMF non-unicode string encodings + 49689 - Allow the setting of user style names on newly created HSSF cell styles + Make it easier to tell which content types each POIXMLTextExtractor handles + 49649 - Added clone support for UserSView* and Feat* families of records + 49653 - Support for escaped unicode characters in Shared String Table + 49579 - prevent ArrayIndexOutOfBoundException in UnknowEscherRecord + 49593 - preserve leading and trailing white spaces in XWPFRun + 49455 - Insert the content of fldSimple fields into the XWPFWordTextExtractor output + 49640 - Fixed parsing formulas containing defined names beginning with an underscore + 49538 - Added implementation for POISSON() + 49524 - Support for setting cell text to be vertically rotated, via style.setRotation(0xff) + 49609 - Case insensitive matching of OOXML part names + 49581 - Ability to add, modify and remove series from HSSF Charts + 49185 - Support for HSSFNames where the comment is stored in a NameCommentRecord + 49599 - correct writing of noterecord author text when switching between ascii and unicode + hwpf: improve reading of auto-saved ("complex") documents + paragraph level as well as whole-file text extraction for word 6/95 files through hwpf + text extraction support for older word 6 and word 95 files via hwpf + 49508 - allow the addition of paragraphs to xwpf table cells + 49446 - don't consider 17.16.23 field codes as properly part of the paragraph's text + xslfslideshow shouldn't break on .thmx (theme) files. support for them is still very limited though + + + 49432 - lazy caching of xssfcomment ctcomment objects by reference, to make repeated comment searching faster + better handling of outlook messages in hsmf when there's no recipient email address + when formatting numbers with dataformatter, handle brackets following colours + 48574 - further xwpf support for tables, paragraphs, including enhanced support for adding new ones + 48245 - tweak hwpf table cell detection to work across more files + 48996 - initial support for external name references in hssf formula evaluation + 46664 - fix up tab ids when adding new sheets, so that print areas don't end up invalid + 45269 - improve replacetext on hwpf ranges + 47815 - correct documentation on what happens when you request a string from a non-string formula cell + 49386 - avoid npe when extracting ooxml file properties which are dates + 49377 - only call decimalformat.setroundingmode on java 1.6 - it's needed to match excel's rendering of numbers + 49378 - correct 1.6ism + parse the hsmf headers chunk if present, and use it to find dates in text extraction if needed + 48494 - detect and support time formats like hh:mm;hh:mm + 48494 - have excelextractor make use of hssfdataformatter, so that numbers and dates come out closer to how excel would render them + 48494 - have eventbasedexcelextractor make use of hssfdataformatter, so that numbers and dates come out closer to how excel would render them + 49096 - add clone support to chart begin and end records, to allow cloning of more chart containing sheets + list attachment names in the output of outlooktextextractor (to get attachment contents, use extractorfactory as normal) + 48872 - allow dateformatter.formatrawcellcontents to handle 1904 as well as 1900 dates + 48872 - handle mmmmm and elapsed time formatting rules in dataformatter + 48872 - handle zero formatting rules, and better color detection in dataformatter + 48872 - support for more kinds of formatting in dataformatter + 43161 - fixed construction of the dib picture header + 49311 - initial support for reading aes-encrypted/write-protected ooxml files + 48718 - make the creation of multiple, un-modified fonts in a row in xssf match the old hssf behaviour + 44916 - allow access to the hssfpatriarch from hssfsheet once created + 48779 - allow you to get straight from a cellstyle to a color, irrespective of if the color is indexed or inline-defined + 48924 - allow access of the hwpf dateandtime underlying date values + 48926 - initial support for the hwpf revision marks authors list + 49160 - ensure that ctdigsigblob is included in poi-ooxml jar + 49189 - detect w:tab and w:cr entries in xwpf paragraphs, even when the xsd is silly and maps them to ctempty + 49273 - correct handling for font character sets with indicies greater than 127 + 49334 - track the valuerangerecords of charts in hssfchart, to allow the basic axis operations + 49242 - track the linkdatarecords of charts in hssfchart + improved performance of xssfworkbook.write + 48846 - avoid npe when finding cell comments + 49325 - ensure that ctphoneticpr is included in poi-ooxml jar + 49191 - fixed tests failing in non-english locales + 48432 - support for xssf themes + 49244 - support for data validation for ooxml format + 49066 - worksheet/cell formatting, with view and html converter + 49020 - workaround excel outputting invalid xml in button definitions by not closing br tags + 49050 - improve performance of abstractescherholderrecord when there are lots of continue records + 49194 - correct text size limit for ooxml .xlsx files + 49254 - fix cellutils.setfont to use the correct type internally + 49139 - properly support 4k big block size in poifs + 48936 - avoid writing malformed cdata blocks in sharedstrings.xml + 49026 - added implementation for text() + 49025 - added implementation for trunc() + 49147 - properly close internal inputstream in extractorfactory#createextractor(file) + 49138 - fixed locale-sensitive formatters in packagepropertiespart + 49153 - ensure that ctvectorvariant is included in poi-ooxml-schemas.jar + 49146 - added accessors to coreproperties.keywords + 48916 - propagate parent to parent-aware records decoded from escher + 48485 - add extra paper size constans to printsetup, such as a3, b4 and b5 + make poifs.filesystem.directorynode preserve the original ordering of its files, which hsmf needs to be able to correctly match up chunks + support evaluation of indirect defined names in indirect + 43670 - improve hdgf chunkv11 separator detection, and short string detection, to solve the "negative length of chunkheader" problem + 48617 - optionally allow the overriding of the locale used by dataformatter to control how the default number and date formats should look + new event based xssf text extractor (xssfeventbasedexcelextractor) + extractorfactory can now be told to prefer event based extractors (current excel only) on a per-thread or overall basis + 48544 - avoid failures in xlsx2csv when shared string table is missing + 48571 - properly close all io streams created in opcpackage + 48572 - always copy all declared inner classes and interfaces when generating poi-ooxml-schemas + low level record support for the extrst (phonetic text) part of unicode strings. no usermodel access to it as yet though. + record.unicodestring has moved to record.common.unicodestring, to live with the other record-part classes, as it isn't a full record. + avoid creating temporary files when opening opc packages from input stream + improved how hsmf handles multiple recipients + add publishertextextractor support to extractorfactory + add xslf support for text extraction from tables + support attachments as embeded documents within the new outlooktextextractor + add a text extractor (outlooktextextractor) to hsmf for simpler extraction of text from .msg files + some improvements to hsmf parsing of .msg files + initialise the link type of hssfhyperlink, so that gettype() on it works + 48425 - improved performance of dateutil.iscelldateformatted() + 47215 - fixed interfaceendrecord to tolerate unexpected record contents + 48415 - improved javadoc on hsspicture.resize() + added ant target to install artifacts in local repository + 48026 - fixed pagesettingsblock to allow multiple headerfooterrecord records + 48202 - fixed cellrangeutil.mergecellranges to work for adjacent cell regions + 48339 - fixed externalnamerecord to properly distinguish dde data from ole data items + 47920 - allow editing workbooks embedded into powerpoint files + 48343 - added implementation of subtotal function + switch to compiling the ooxml schemas for java 1.5 + + + 48332 - fixed xssfsheet autosizecolumn() to tolerate empty richtextstring + 48332 - fixed columninforecord to tolerate missing reserved field + 47701 - fixed recordformatexception when reading list subrecords (lbsdatasubrecord) + memory usage optimization in xssf - avoid creating parentless xml beans + 47188 - avoid corruption of workbook when adding cell comments + 48106 - improved work with cell comments in xssf + add support for creating summaryinformation and documentsummaryinformation properties + on poidocuments that don't have them, via poidocument.createinformationproperties() + 48180 - be more forgiving of short chart records, which skip some unused fields + 48274 - fix erronious wrapping of byte colours in hssfpalette.findsimilarcolor + 48269 - fix fetching of error codes from xssf formula cells + 48229 - fixed javadoc for hssfsheet.setcolumnwidth and xssfsheet setcolumnwidth + 47757 - fixed xlsx2csv to avoid exception when processing cells with multiple "t" elements + 48195 - short-circuit evaluation of if() and choose() + 48161 - support for text extraction from ppt master slides + 47970 - added a method to set arabic mode in hssfsheet + 48134 - release system resources when using picture.resize() + 48087 - avoid npe in xssfchartsheet when calling methods of the superclass + 48038 - handle reading hwpf stylesheets from non zero offsets + when running the "compile-ooxml-xsds" ant task, also generate the source jar for the ooxml schemas + 45672 - improve handling by missingrecordawarehssflistener of records that cover multiple cells (mulblankrecord and mulrkrecord) + 48096 - relaxed validation check in recalcidrecord + 48085 - improved error checking in blockallocationtablereader to trap unreasonable field values + 47924 - fixed logic for matching cells and comments in hssfcell.getcellcomment() + 47942 - added implementation of protection features to xlsx and docx files + 48070 - preserve leading and trailing white spaces in xssfrichtextstring + 48044 - added implementation for countblank function + 48036 - added intersectioneval to allow evaluation of the intersection formula operator + 47999 - avoid un-needed call to the jvm garbage collector when working on ooxml opc packages + 47922 - added example hsmf application that converts a .msg file to text and extracts attachments + 47903 - added ant target to compile scratchpad examples + 47839 - improved api for ooxml custom properties + 47862 - fixed xssfsheet.setcolumnwidth to handle columns included in a column span + 47804 - fixed xssfsheet.setcolumnhidden to handle columns included in a column span + 47889 - fixed xssfcell.getstringcellvalue() to properly handle cached formula results + + + 47747 - fixed logic for locating shared formula records + 47809 - improved work with user-defined functions + 47581 - fixed xssfsheet.setcolumnwidth to produce xml compatible with mac excel 2008 + 47734 - removed unnecessary svn:executable flag from files in svn trunk + 47543 - added javadoc how to avoid excel crash when creating too many hssfrichtextstring cells + 47813 - fixed problems with xssfworkbook.removesheetat when workbook contains chart + 47737 - adjust sheet indices of named ranges when deleting sheets + 47770 - built-in positive formats don't need starting '(' + 47771 - added method setfunction(boolean) for defined names + 47768 - implementation of excel "days360" and "npv" functions + 47751 - do not allow hssf's cell text longer than 32,767 characters + 47757 - added an example demonstrating how to convert an xlsx workbook to csv + 44770 - fixed ppt parser to tolerate comment2000 containers with missing comment text + 47773 - fix for extraction paragraphs and sections from headers/footers with xwpfwordextractor + 47727 - support for extraction of header / footer images in hwpf + moved all test data to a top-level directory + 47721 - Added implementation for INDIRECT() + 45583 - Avoid exception when reading ClipboardData packet in OLE property sets + 47652 - Added support for reading encrypted workbooks + 47604 - Implementation of an XML to XLSX Importer using Custom XML Mapping + 47620 - Avoid FormulaParseException in XSSFWorkbook.setRepeatingRowsAndColumns when removing repeated rows and columns + 47606 - Fixed XSSFCell to correctly parse column indexes greater than 702 (ZZ) + 47598 - Improved formula evaluator number comparison + 47571 - Fixed XWPFWordExtractor to extract inserted/deleted text + 47548 - Fixed RecordFactoryInputStream to properly read continued DrawingRecords + 46419 - Fixed compatibility issue with OpenOffice 3.0 + 47559 - Fixed compatibility issue with Excel 2008 Mac sp2. Please see + the HSSF+XSSF project page for more information. + 47540 - Fix for saving custom and extended OOXML properties + 47535 - Fixed WordExtractor to tolerate files with empty footnote block + 47517 - Fixed ExtractorFactory to support .xltx and .dotx files + 45556 - Support for extraction of footnotes from docx files + 45555 - Support for extraction of endnotes from docx files + 47520 - Initial support for custom XML mappings in XSSF + 47460 - Fixed NPE when retrieving core properties from a newly created workbook + 47498 - Fixed HyperlinkRecord to properly handle URL monikers + 47504 - Fixed XSSFWorkbook to read files with hyperlinks to document locations + 47479 - Fix BoolErrRecord to tolerate incorrect format written by OOO + 47448 - Allow HSSFEventFactory to handle non-zero padding at the end of the workbook stream + 47456 - Support for getting OLE object data in PowerPointExtractor + 47411 - Explicitly set the 1900 date system when creating XSSF workbooks + 47400 - Support for text extraction of footnotes, endnotes and comments in HWPF + 47415 - Fixed PageSettingsBlock to allow multiple PLS records + 47412 - Fixed concurrency issue with EscherProperties.initProps() + 47143 - Fixed OOM in HSSFWorkbook#getAllPictures when reading .xls files containing metafiles + Added implementation for ISNA() + 46793 - fixed SimpleShape#getLineWidth to handle default line width + 47356 - removed unused private fields in HWPF BorderCode + 47355 - Improved HWPF TableCell to expose TableCellDescriptor + 46610 - Improved HWPF to better handle unicode + 47261 - Fixed SlideShow#removeSlide to remove references to Notes + 47375 - Fixed HSSFHyperlink to correctly set inter-sheet and file links + 47384 - Fixed ExternalNameRecord to handle unicode names + 47372 - Fixed locale-sensitive unit tests to pass when running on non-US locale + + + 47363 - Fixed HSSFSheet to allow addition of data validations after sheet protection + 47294 - Fixed XSSFWorkbook#setRepeatingRowsAndColumns to tolerate sheet names with quotes + 47309 - Fixed logic in HSSFCell.getCellComment to handle sheets with more than 65536 comments + 46776 - Added clone() method to MulBlankRecord to fix crash in Sheet.cloneSheet() + 47244 - Fixed HSSFSheet to handle missing header / footer records + 47312 - Fixed formula parser to properly reject cell references with a '0' row component + 47199 - Fixed PageSettingsBlock/Sheet to tolerate margin records after other non-PSB records + 47069 - Fixed HSSFSheet#getFirstRowNum and HSSFSheet#getLastRowNum to return correct values after removal of all rows + 47278 - Fixed XSSFCell to avoid generating xsi:nil entries in shared string table + 47206 - Fixed XSSFCell to properly read inline strings + 47250 - Fixed FontRecord to expect unicode flags even when name length is zero + 47198 - Fixed formula evaluator comparison of -0.0 and 0.0 + 47229 - Fixed ExternalNameRecord to handle DDE links + 46287 - Control of header and footer extraction in ExcelExtractor / XSSFExcelExtractor + 46554 - New ant target "jar-examples" + 46161 - Support in XSSF for setGroupColumnCollapsed and setGroupRowCollapsed + 46806 - Allow columns greater than 255 and rows greater than 0x100000 in XSSF formulas + 41711 - Base class for "old version" exceptions, and new HSLF detection + use of old versions exception + 47179 - Fix string encoding issues with HSMF chunks on non-windows platforms + 47183 - Attachment support for HSMF + 47154 - Handle the cell format @ as the same as General + 47048 - Fixed evaluation of defined names with the 'complex' flag set + 46953 - More tweaks to PageSettingsBlock parsing logic in Sheet constructor + 47089 - Fixed XSSFWorkbook.createSheet to properly increment sheetId + 46568 - Fixed XSLFPowerPointExtractor to properly process line breaks + 39056 - Fixed POIFSFileSystem to set CLSID of root when constructing instances from InputStream + 47054 - Fixed cloneStyleFrom to avoid exception when cloning styles of the same family + 46186 - Fixed Sheet to read GutsRecord in the Sheet(RecordStream rs) + 46714 - Automatically call sheet.setAlternativeExpression when sheet.setRowSumsBelow is called + 46279 - Allow 255 arguments for excel functions in XSSF + 47028 - Fixed XSSFCell to preserve cell style when cell value is set to blank + 47026 - Avoid NPE in XSSFCell.setCellType() when workbook does not have SST + 46987 - Allow RecordFactory to handle non-zero padding at the end of the workbook stream + 47034 - Fix reading the name of a NameRecord when the name is very long + 47001 - Fixed WriteAccessRecord and LinkTable to handle unusual format written by Google Docs + 46973 - Fixed defined names to behave better when refersToFormula is unset + 46832 - Allow merged regions with columns greater than 255 or rows bigger than 65536 in XSSF + 46951 - Fixed formula parser to better handle range operators and whole row/column refs. + 46948 - Fixed evaluation of range operator to allow for area-ref operands + 46918 - Fixed ExtendedPivotTableViewFieldsRecord(SXVDEX) to allow shorter format + 46898 - Fixed formula evaluator to not cache intermediate circular-reference error results + 46917 - Fixed PageItemRecord(SXPI) to allow multiple field infos + 46904 - Fix POIFS issue with duplicate block 0 references on very old BIFF5/BIFF7 files + 46840 - PageSettingsBlock should include HEADERFOOTER record + 46885 - update cell type when setting cached formula result in XSSFCell + added modifiers for anchor type to XSSFClientAnchor + 46772 - support built-in data formats in XSSFDataFormat + 46719 - fixed XSSFSheet.shiftRows to correctly preserve row heights + 46715 - preserve custom column widths across re-serialization of XSSFWorkbook + 46703 - added setDisplayZeros / isDisplayZeros to common interface org.apache.poi.ss.usermodel.Sheet + 46708 - added getMergedRegion(int) to common interface org.apache.poi.ss.usermodel.Sheet + fixed Sheet.autoSizeColumn() to use cached formula values when processing formula cells + Fixed formula parser to handle names with backslashes + 46660 - added Workbook getHidden() and setHidden(boolean) + 46693 - Fixed bugs serialization bugs in records: CHARTFORMAT, SHTPROPS, SXVD and SXVDEX + 46627 - Fixed offset of added images if Pictures stream contains pictures with zero length + + + 46536 - When shifting rows, update formulas on that sheet to point to the new location of those rows + 46663 - Fixed XSSFSheet.shiftRows to properly update references of the shifted cells + 46535 - Remove reference from calculation chain when a formula is deleted + 46654 - HSSFRow/RowRecord to properly update cell boundary indexes + 46643 - Fixed formula parser to encode range operator with tMemFunc + 46647 - Fixed COUNTIF NE operator and other special cases involving type conversion + 46635 - Added a method to remove slides + 40520 - Fixed HSSFFont.applyFont() to properly apply font to overlapping regions + 46545 - Fixed ObjRecord to ignore excessive padding written by previous POI versions + 46613 - Fixed evaluator to perform case insensitive string comparisons + 46544 - command line interface for hssf ExcelExtractor + 46547 - Allow addition of conditional formatting after data validation + 46548 - Page Settings Block fixes - continued PLS records and PSB in sheet sub-streams + 46523 - added implementation for SUMIF function + Support for reading HSSF column styles + Hook up POIXMLTextExtractor.getMetadataTextExtractor() to the already written POIXMLPropertiesTextExtractor + 46472 - Avoid NPE in HPSFPropertiesExtractor when no properties exist + 46479 - fixed bugs related to cached formula values and HSSFFormulaEvaluator.evaluateInCell() + 45031 - added implementation for CHOOSE() function + 46361 - resolve licensing issues around the HDGF resource file, chunks_parse_cmds.tbl + 46410 - added implementation for TIME() function + 46320 - added HSSFPictureData.getFormat() + 46445 - fixed HSSFSheet.shiftRow to move hyperlinks + fixed formula parser to correctly resolve sheet-level names + 46433 - support for shared formulas in XSSF + 46299 - support for carriage return and line break in XWPFRun + 46300 - support for line spacing in XWPFParagraph + 46308 - initial support for creation of XWPFTable + Added getters to parent objects: HSSFSheet.getWorkbook(), HSSFRow.getSheet() and HSSFCell.getRow() + 46385 - (also patch 46362) fix serialization of StyleRecord with unicode name + 46368 - Fix HSSFRichTextRun and strings longer than 32768 characters + Support sheet-level names + Fixed XSSFCell to properly handle cell references with column numbers up to XFD + 44914 - Fixed warning message "WARN. Unread n bytes of record 0xNN" + 46156 - Improved number to text conversion to be closer to that of Excel + 46312 - Fixed ValueRecordsAggregate to handle removal of new empty row + 46269 - Improved error message when attempting to read BIFF2 file + 46206 - Fixed Sheet to tolerate missing DIMENSION records + 46301 - added pivot table records: SXDI, SXVDEX, SXPI, SXIDSTM, SXVIEW, SXVD, SXVS, et al + 46280 - Fixed RowRecordsAggregate etc to properly skip PivotTable records + + + 46213 - Fixed FormulaRecordAggregate to gracefully ignore extra StringRecords + 46174 - Fixed HSSFName to handle general formulas (not just area references) + 46189 - added chart records: CHARTFRTINFO, STARTBLOCK, ENDBLOCK, STARTOBJECT, ENDOBJECT, and CATLAB + 46199 - More tweaks to EmbeddedObjectRefSubRecord + Changes to formula evaluation allowing for reduced memory usage + 45290 - Support odd files where the POIFS header block comes after the data blocks, and is on the data blocks list + 46184 - More odd escaped date formats + Include the sheet number in the output of XLS2CSVmra + 46043 - correctly write out HPSF properties with HWPF + 45973 - added CreationHelper.createFormulaEvaluator(), implemeted both for HSSF and XSSF + 46182 - fixed Slideshow.readPictures() to skip pictures with invalid headers + 46137 - Handle odd files with a ContinueRecord after EOFRecord + Fixed problem with linking shared formulas when ranges overlap + 45784 - More fixes to SeriesTextRecord + 46033 - fixed TableCell to correctly set text type + 46122 - fixed Picture.draw to skip rendering if picture data was not found + 15716 - memory usage optimisation - converted Ptg arrays into Formula objects + 46065 - added implementation for VALUE function + 45966 - added implementation for FIND function + 45778 - fixed ObjRecord to read ftLbsData properly + 46053 - fixed evaluation cache dependency analysis when changing blank cells + + + 45518 - Fix up ColumnHelper to output valid col tags, by making 1 based and 0 based bits clearer, and using the right ones + 45676 - Handle very long cells in the XSSF EventUserModel example + Initial ExtractorFactory support for building TextExtractors for embeded documents + + + Support stripping XSSF header and footer fields (eg page number) out of header and footer text if required + Add POIXMLPropertiesTextExtractor, which provides to the OOXML file formats a similar function to HPSF's HPSFPropertiesExtractor + 45539 - Improve XWPFWordExtractor to extract headers and footers + Improve how XWPF handles paragraph text + Support in XWPF handles headers and footers + 45592 - Improve XWPF text extraction to include tables always, and picture text where possible + 45545 - Improve XSLF usermodel support, and include XSLF comments in extracted text + 45540 - Fix XSSF header and footer support, and include headers and footers in the output of XSSFExcelExtractor + 45431 - Support for .xlsm files, sufficient for simple files to be loaded by excel without warning + New class org.apache.poi.hssf.record.RecordFormatException, which DDF uses instead of the HSSF version, and the HSSF version inherits from + 45431 - Partial support for .xlm files. Not quite enough for excel to load them though + 45430 - Correct named range sheet reporting when no local sheet id is given in the xml + + + 45018 - Support for fetching embeded documents from within an OOXML file + Port support for setting a policy on missing / blank cells when fetching, to XSSF too + Common text extraction factory, which returns the correct POITextExtractor for the supplied data + Text Extraction support for the new OOXML files (.xlsx, .docx and .pptx) + Initial support for processing OOXML Excel files (.xlsx), both directly through XSSF, and also through the new common UserModel + Created a common interface for handling PowerPoint files, irrespective of if they are .ppt or .pptx + Created a common interface for handling Excel files, irrespective of if they are .xls or .xlsx + + + 45866 - allowed for change of unicode compression across Continue records + 45964 - support for link formulas in Text Objects + 43354 - support for evalating formulas with missing args + 45912 - fixed ArrayIndexOutOfBoundsException in EmbeddedObjectRefSubRecord + 45889 - fixed ArrayIndexOutOfBoundsException when constructing HSLF Table with a single row + Initial support for creating hyperlinks in HSLF + 45876 - fixed BoundSheetRecord to allow sheet names longer than 31 chars + 45890 - fixed HSSFSheet.shiftRows to also update conditional formats + 45865 modified Formula Parser/Evaluator to handle cross-worksheet formulas + Optimised the FormulaEvaluator to take cell dependencies into account + 16936 - Initial support for whole-row cell styling + Update hssf.extractor.ExcelExtractor to optionally output blank cells too + Include the sheet name in the output of examples.XLS2CSVmra + 45784 - Support long chart titles in SeriesTextRecords + 45777 - Throw an exception if HSSF Footer or Header is attemped to be set too long, rather than having it break during writing out + 45844 - Addtional diagnostics for HSLF SlideShowRecordDumper + 45829 - HSSFPicture.getImageDimension() failed when DPI of image is zero + 45815 - Bit mask values in StyleTextPropAtom were not preserved across read-write + 45814 - Specify RecordType for slide show Handout (4041) + 45805 - Fixed 16-bit signed/unsigned bug in HSSFSheet.getColWidth etc + 45780 - Fixed HSSFSheet.shiftRows to also update Area refs + 45804 - Update HSMF to handle Outlook 3.0 msg files, which have a different string chunk type + Expose the name of Named Cell Styles via HSSFCellStyle (normally held on the parent style though) + 45978 - Fixed IOOBE in Ref3DPtg.toFormulaString() due eager initialisation of SheetReferences + Made HSSFFormulaEvaluator no longer require initialisation with sheet or row + Extended support for cached results of formula cells + 45639 - Fixed AIOOBE due to bad index logic in ColumnInfoRecordsAggregate + Fixed special cases of INDEX function (single column/single row, errors) + 45761 - Support for Very Hidden excel sheets in HSSF + 45738 - Initial HWPF support for Office Art Shapes + 45720 - Fixed HSSFWorkbook.cloneSheet to correctly clone sheets with drawings + 45728 - Fix for SlideShow.reorderSlide in HSLF + Initial support for embedded movies and controls in HSLF + 45358 - signed/unsigned error when parsing 3-d area refs, performance problem evaluating area refs, and ClassCastExcecption in IF() + Support for HPBF Publisher hyperlinks, including during text extraction + 26321 and 44958 - preserve position of ArrayRecords and TableRecords among cell value records + Impove empty header or footer handling in HWPF HeaderStories + Avoid NPE in hssf.usermodel.HeaderFooter when stripping fields out + Avoid NPE in EscherBSERecord on older escher records + Basic text extractraction support in HPBF + Initial, low level support for Publisher files, in the form of HPBF + 45699 - Fix RowRecordsAggregate to tolerate intervening MERGEDCELLS records + 45698 - Fix LinkTable to tolerate multiple EXTERNSHEET records + 45682 - Fix for cloning of CFRecordsAggregate + Initial support for evaluating external add-in functions like YEARFRAC + 45672 - Fix for MissingRecordAwareHSSFListener to prevent multiple LastCellOfRowDummyRecords when shared formulas are present + 45645 - Fix for HSSFSheet.autoSizeColumn() for widths exceeding Short.MAX_VALUE + 45623 - Support for additional HSSF header and footer fields, including bold and full file path + 45623 - Support stripping HSSF header and footer fields (eg page number) out of header and footer text if required + 45622 - Support stripping HWPF fields (eg macros) out of text, via Range.stripFields(text) + New HPSF based TextExtractor for document metadata, org.apache.poi.hpsf.extractor.HPSFPropertiesExtractor + Properly update the array of Slide's text runs in HSLF when new text shapes are added + 45590 - Fix for Header/footer extraction for .ppt files saved in Office 2007 + Big improvement in how HWPF handles unicode text, and more sanity checking of text ranges within HWPF + Include headers and footers int he extracted text from HWPF's WordExtractor + Added support to HWPF for headers and footers + Improve how HWPF deals with unicode internally. Should avoid some odd behaviour when manipulating unicode text + 45577 - Added implementations for Excel functions NOW and TODAY + 45582 - Fix for workbook streams with extra bytes trailing the EOFRecord + 45537 - Include headers and footers (of slides and notes) in the extracted text from HSLF + 45472 - Fixed incorrect default row height in OpenOffice 2.3 + 44692 - HSSFPicture.resize() stretched image when there was a text next to it + 45543 - Optionally extract comment text with PowerPointExtractor, and initial hslf model support for comments + 45538 - Include excel headers and footers in the output of ExcelExtractor + 44894 - refactor duplicate logic from EventRecordFactory to RecordFactory + Support for Headers / Footers in HSLF + 44953 - Extensive fixes for data validation + 45519 - Fixed to keep datavalidation records together + Support for creating new HSLF CurrentUserAtoms + 45466 - Partial support for removing excel comments (won't work for all excel versions yet) + 45437 - Detect encrypted word documents, and throw an EncryptedDocumentException instead of a OOM + 45404 - New class, hssf.usermodel.HSSFDataFormatter, for formatting numbers and dates in the same way that Excel does + 45414 - Don't add too many UncalcedRecords to sheets with charts in them + 45398 - Support detecting date formats containing "am/pm" as date times + 45410 - Removed dependency from contrib on commons beanutils,collections and lang + New helper, HSSFOptimiser, which handles removing duplicated font and style records, to avoid going over the limits in Excel + 45322 - Fixed NPE in HSSFSheet.autoSizeColumn() when cell number format was not found + 45380 - Missing return keyword in ArrayPtg.toFormulaString() + 44958 - Record level support for Data Tables. (No formula parser support though) + 35583 - Include a version class, org.apache.poi.Version, to allow easy introspection of the POI version + Allow the cloning of one HSSFCellStyle onto another, including cloning styles from one HSSFWorkbook onto another + 45289 - finished support for special comparison operators in COUNTIF + 45126 - Avoid generating multiple NamedRanges with the same name, which Excel dislikes + Fix cell.getRichStringCellValue() for formula cells with string results + 45365 - Handle more excel number formatting rules in FormatTrackingHSSFListener / XLS2CSVmra + 45373 - Improve the performance of HSSFSheet.shiftRows + 45367 - Fixed bug when last row removed from sheet is row zero + 45348 - Tweaks to RVA formula logic + 45354 - Fixed recognition of named ranges within formulas + 45338 - Fix HSSFWorkbook to give you the same HSSFFont every time, and then fix it to find newly added fonts + 45336 - Fix HSSFColor.getTripletHash() + 45334 - Fixed formula parser to handle dots in identifiers + 45252 - Improvement for HWPF Range.replaceText() + 45001 - Further fix for HWPF Range.delete() and unicode characters + 45175 - Support for variable length operands in org.apache.poi.hwpf.sprm.SprmOperation + Avoid spurious missing lines with the MissingRecordAware event code, and odd files that contain RowRecords in the middle of the cell Records. + Support for parsing formulas during EventUserModel processing, via the new EventWorkbookBuilder + + + 30978 - Fixed re-serialization of tRefErr3d and tAreaErr3d + 45234 - Removed incorrect shared formula conversion in CFRuleRecord + 45001 - Improved HWPF Range.replaceText() + 44692 - Fixed HSSFPicture.resize() to properly resize pictures if the underlying columns/rows have modified size + Support custom image renderers in HSLF + Correctly increment the reference count of a blip when a picture is inserted + 45110 - Fixed TextShape.resizeToFitText() to properly resize TextShape + 45091 - Fixed serialization of RefN~ tokens. Simplified Ptg class hierarchy + 45133 - Fixed OBJ Record (5Dh) to pad the sub-record data to a 4-byte boundary + 45145 - Fixed Sheet to always enforce RowRecordsAggregate before ValueRecordsAggregate + 45123 - Fixed SharedFormulaRecord.convertSharedFormulas() to propagate token operand classes + 45087 - Correctly detect date formats like [Black]YYYY as being date based + 45060 - Improved token class transformation during formula parsing + 44840 - Improved handling of HSSFObjectData, especially for entries with data held not in POIFS + 45043 - Support for getting excel cell comments when extracting text + Extend the support for specifying a policy to HSSF on missing / blank cells when fetching, to be able to specify the policy at the HSSFWorkbook level + 45025 - improved FormulaParser parse error messages + 45046 - allowed EXTERNALBOOK(0x01AE) to be optional in the LinkTable + 45066 - fixed sheet encoding size mismatch problems + 45003 - Support embeded HDGF visio documents + 45001 - Partial fix for HWPF Range.insertBefore() and Range.delete() with unicode characters + 44977 - Support for AM/PM in excel date formats + Support for specifying a policy to HSSF on missing / blank cells when fetching + 44937 - Partial support for extracting Escher images from HWPF files + 44824 - Avoid an infinite loop when reading some HWPF pictures + 44898 - Correctly handle short last blocks in POIFS + + + 44306 - fixed reading/writing of AttrPtg(type=choose) and method toFormulaString() for CHOOSE formulas + 24207 - added HSSFName.isDeleted() to check if the name points to cell that no longer exists + 40414 - fixed selected/active sheet after removing sheet from workbook + 44523 - fixed workbook sheet selection and focus + 45000 - Fixed NPE in ListLevel when numberText is null + 44985 - Properly update TextSpecInfoAtom when the parent text is changed + 41187 - fixed HSSFSheet to properly read xls files without ROW records + 44950 - fixed HSSFFormulaEvaluator.evaluateInCell() and Area3DEval.getValue() also added validation for number of elements in AreaEvals + 42570 - fixed LabelRecord to use empty string instead of null when the length is zero. + 42564 - fixed ArrayPtg to use ConstantValueParser. Fixed a few other ArrayPtg encoding issues. + Follow-on from 28754 - StringPtg.toFormulaString() should escape double quotes + 44929 - Improved error handling in HSSFWorkbook when attempting to read a BIFF5 file + 44675 - Parameter operand classes (function metadata) required to encode SUM() etc properly. Added parse validation for number of parameters + 44921 - allow Ptg.writeBytes() to be called on relative ref Ptgs (RefN* and AreaN*) + 44914 - Fix/suppress warning message "WARN. Unread n bytes of record 0xNN" + 44892 - made HSSFWorkbook.getSheet(String) case insensitive + 44886] - Correctly process PICT metafile in EscherMetafileBlip + 44893 - Take into account indentation in HSSFSheet.autoSizeColumn + + + 44857 - Avoid OOM on unknown escher records when EscherMetafileBlip is incorrect + HSLF: Support for getting embedded sounds from slide show + HSLF: Initial support for rendering slides into images + HSLF: Support for getting OLE object data from slide show + HSLF: Implemented more methods in PPGraphics2D + HSLF: Added Freeform shape which can contain both lines and Bezier curves + 41071 - Improved text extraction in HSLF + 30311 - Conditional Formatting - improved API, added HSSFSheetConditionalFormatting + Update the formula parser code to use a HSSFWorkbook, rather than the low level model.Workbook, to make things cleaner and make supporting XSSF formulas in future much easier + Fix the logger used by POIFSFileSystem, so that commons-logging isn't required when not used + Update HSLFSlideShow and HSSFWorkbook to take advantage of POIFS updates, and allow reading embeded documents + Improve how POIFS works with directory entries, and update HWPFDocument to support reading an embeded word document + Initial support for getting and changing chart and series titles + Implement a proxy HSSFListener which tracks the format records, and lets you lookup the format string for a given cell. Convert the xls to csv example to use it + 44792 - fixed encode/decode problems in ExternalNameRecord and CRNRecord. + 43670, 44501 - Fix how HDGF deals with trailing data in the list of chunk headers + 30311 - More work on Conditional Formatting + refactored all junits' usage of HSSF.testdata.path to one place + 44739 - Small fixes for conditional formatting (regions with max row/col index) + 44694 - HPSF: Support for property sets without sections + Implement Sheet.removeShape(Shape shape) in HSLF + Various fixes: Recognising var-arg built-in functions #44675, ExternalNameRecord serialisation bug #44695, PMT() bug #44691 + 30311 - More work on Conditional Formatting + Move the Formula Evaluator code out of scratchpad + Move the missing record aware eventusermodel code out of scratchpad + 44652 / 44603 - Improved handling of Pictures in Word Documents + 44636 - Fix formula parsing of RefVPtg, which was causing #VALUE to be shown on subsequent edits + 44627 - Improve the thread safety of POILogFactory + 30311 - Initial support for Conditional Formatting + 44609 - Handle leading spaces in formulas, such as '= 4' + 44608 - Support for PercentPtg in the formula evaluator + 44606 - Support calculated string values for evaluated formulas + Add accessors to horizontal and vertical alignment in HSSFTextbox + 44593 - Improved handling of short DVRecords + 28627 / 44580 - Fix Range.delete() in HWPF + 44539 - Support for area references in formulas of rows >= 32768 + 44536 - Improved support for detecting read-only recommended files + 43901 - Correctly update the internal last cell number when adding and removing cells (previously sometimes off-by-one) + 44504 - Added initial support for recognising external functions like YEARFRAC and ISEVEN (using NameXPtg), via LinkTable support + 44504 - Improvements to FormulaParser - operators, precedence, error literals, quotes in string literals, range checking on IntPtg, formulas with extra un-parsed stuff at the end, improved parse error handling + 44504 - Fixed number conversion inconsistencies in many functions, and improved RefEval + 44504 - Added initial support for recognising external functions like YEARFRAC and ISEVEN (using NameXPtg), via LinkTable support + 44504 - Improvements to FormulaParser - operators, precedence, error literals, quotes in string literals, range checking on IntPtg, formulas with extra un-parsed stuff at the end, improved parse error handling + 44504 - Fixed number conversion inconsistencies in many functions, and improved RefEval + 44508 - Fix formula evaluation with evaluateInCell on boolean formulas + 44510 - Fix how DVALRecord works with dropdowns + 44495 - Handle named cell ranges in formulas that have lower case parts + 44491 - Don't have the new-style "HPSF properties are always available" affect the old-style use of HPSF alongside HSSF + 44471 - Crystal Reports generates files with short StyleRecords, which isn't allowed in the spec. Work around this + 44495 - Handle named cell ranges in formulas that have lower case parts + 44491 - Don't have the new-style "HPSF properties are always available" affect the old-style use of HPSF alongside HSSF + 44471 - Crystal Reports generates files with short StyleRecords, which isn't allowed in the spec. Work around this + 44450 - Support for Lookup, HLookup and VLookup functions + 44449 - Avoid getting confused when two sheets have shared formulas for the same areas, and when the shared formula is set incorrectly + 44366 - InputStreams passed to POIFSFileSystem are now automatically closed. A warning is generated for people who might've relied on them not being closed before, and a wrapper to restore the old behaviour is supplied + 44371 - Support for the Offset function + 38921 - Have HSSFPalette.findSimilar() work properly + 44456 - Fix the contrib SViewer / SViewerPanel to not fail on sheets with missing rows + 44403 - Further support for unusual, but valid, arguments to the Mid function + 44410 - Support for whole-column ranges, such as C:C, in formula strings and the formula evaluator + 44421 - Update Match function to properly support Area references + 44417 - Improved handling of references for the need to quote the sheet name for some formulas, but not when fetching a sheet by name + 44413 - Fix for circular references in INDEX, OFFSET, VLOOKUP formulas, where a cell is actually allowed to reference itself + 44403 - Fix for Mid function handling its arguments wrong + 44364 - Support for Match, NA and SumProduct functions, as well as initial function error support + 44375 - Cope with a broken dictionary in Document Summary Information stream. RuntimeExceptions that occured when trying to read bogus data are now caught. Dictionary entries up to but not including the bogus one are preserved, the rest is ignored. + 38641 - Handle timezones better with cell.setCellValue(Calendar), so now 20:00-03:00, 20:00+00:00 and 20:00+03:00 will all be recorded as 20:00, and not 17:00 / 20:00 / 23:00 (pass a Date not a Calendar for old behaviour) + 44373 - Have HSSFDateUtil.isADateFormat recognize more formats as being dates + 37923 - Support for Excel hyperlinks + Implement hashCode() and equals(obj) on HSSFFont and HSSFCellStyle + 44345 - Implement CountA, CountIf, Index, Rows and Columns functions + 44336 - Properly escape sheet names as required when figuring out the text of formulas + 44326 - Improvements to how SystemOutLogger and CommonsLogger log messages with exceptions, and avoid an infinite loop with certain log messages with exceptions + Support for a completed Record based "pull" stream, via org.apache.poi.hssf.eventusermodel.HSSFRecordStream, to complement the existing "push" Event User Model listener stuff + + + 44297 - IntPtg must operate with unsigned short. Reading signed short results in incorrect formula calculation + 44296 - Fix for reading slide background images + 44293 - Avoid swapping AreaPtgs from relative to absolute + 44292 - Correctly process the last paragraph in a word file + 44254 - Avoid some unread byte warnings, and properly understand DVALRecord + Add another formula evaluation method, evaluateFormulaCell(cell), which will re-calculate the value for a formula, without affecting the formula itself. + 41726 - Fix how we handle signed cell offsets in relative areas and references + 44233 - Support for getting and setting a flag on the sheet, which tells excel to re-calculate all formulas on it at next reload + 44201 - Enable cloning of sheets with data validation rules + 44200 - Enable cloning of sheets with notes + 43008 - Add a moveCell method to HSSFRow, and deprecate setCellNum(), which didn't update things properly + 43058 - Support setting row grouping on files from CR IX, which lack GutsRecords + 31795 - Support cloning of sheets with certain drawing objects on them + 43902 - Don't consider merged regions when auto-sizing columns + 42464 - Avoid "Expected ExpPtg to be converted from Shared to Non-Shared Formula" on large, formula heavy worksheets + 42033 - Add support for named ranges with unicode names + 34023 - When shifting rows, update formulas on that sheet to point to the new location of those rows + Support getting all the cells referenced by an AreaReference, not just the corner ones + 43510 - Add support for named ranges in formulas, including non-contiguous named ranges + 43937 - Add support for hiding and un-hiding sheets, and checking their current hidden status + 44167 - Fix for non-contiguous named ranges + 44070 - Fix for shifting comments when shifting rows + + + Support for tables in HSLF + 43781 - Fix for extracting text from TextBoxes HSLF in + Improve JavaDocs relating to hssf font and fill colourings + 44095, 44097, 44099 - [PATCH] Support for Mid, Replace and Substitute excel functions + 44055 - [PATCH] Support for getting the from field from HSMF messages + 43551 - [PATCH] Support for 1904 date windowing in HSSF (previously only supported 1900 date windowing) + 41064 - [PATCH] Support for String continue records + 27511 - [PATCH] Support for data validation, via DVRecord and DVALRecord + + + 43877 - Fix for handling mixed OBJ and CONTINUE records + 39512 - Fix for handling mixed OBJ and CONTINUE records + 43837 - [PATCH] Support for unicode NameRecords + 43807 - Throw an IllegalArgumentException if asked to create a merged region with invalid columns or rows, rather than writing out a corrupt file + 43837 - [PATCH] Support for unicode NameRecords + 43721 - [PATCH] Support for Chart Title Format records + 42794 - [PATCH] Fix for BOF records from things like Access + 43648 - Fix for IntPtg and short vs int + 43751 - [PATCH] - Fix for handling rotated text in HSSFSheet.autoSizeColumn + Include an Excel text extractor, and put all existing text extractors under a common superclass + Improvements to the LZW compression engine used by HDGF + HSSFPicture.resize() - a handy method to reset a picture to its original width and height + Add a getSheetIndex(HSSFSheet) method to HSSFWorkbook, and allow a HSSFSheet to get at its parent HSSFWorkbook + Move POIDocument out of Scratchpad, and update HSSFWorkbook to use it + 43399 - [PATCH] - Fix for Cell References for rows > 32678 + 43410 - [PATCH] - Improved Formula Parser support for numbers and ranges + When writing HSLF files out, optionally preserve all OLE2 nodes (default is just the HSLF related nodes) + 43323 - [PATCH] - Support for adding Pictures to ShapeGroups in HSLF. + 43222 - [PATCH] - Support for getting OLE object data from HSSFWorkbook. + 43247 - [PATCH] - Support for getting OLE object data from slideshows. + 43125 - [PATCH] - Support for reading EMF, WMF and PICT images via HSSFWorkbook.getAllPictures() + 43088 - [PATCH] - Fix for reading files with long cell comments and text boxes + 42844 - [PATCH] - Fix for the EventUserModel and records that aren't immediately followed by their ContinueRecords + 43055 - [PATCH] - Fix for saving Crystal Reports xls files when preserving nodes + 43116 - [PATCH] - Fix for Escher layer handling of embeded OLE2 documents + 43108 - [PATCH] - Where permissions deny fetching System Properties, use sensible defaults + 43093 - [PATCH] - Fix formula evaluator support for Area3D references to other sheets + Improvements to HSSFDateUtils.isADateFormat, and have HSSFDateUtil.isCellDateFormatted use this + 42999 - [PATCH] - Fix for HSSFPatriarch positioning problems + Support for write-protecting a HSSF workbook + Support for querying, setting and un-setting protection on sheets in a HSSF workbook + Initial HSMF (outlook) support + Tidy up the javadocs + + + + Administrative updates to the Maven POMs, and the release artificat build process + 23951 - [PATCH] Fix for HSSF setSheetOrder and tab names + 42524 - [PATCH] Better HSLF support for problem shape groups + 42520 - [PATCH] Better HSLF support for corrupt picture records + Initial support for a "missing record aware" HSSF event model + Additional HSLF support for Title and Slide Master Sheets + 42474 - [PATCH] Improved HSLF note to slide matching, and a NPE + 42481 - [PATCH] Tweak some HSLF exceptions, to make it clearer what you're catching + 42667 - [PATCH] Fix for HSLF writing of files with tables + Improved way of detecting HSSF cells that contain dates, isADateFormat + Initial, read-only support for Visio documents, as HDGF + + + + 39977 - [PATCH] Fix POM for Maven users + 38976 - [PATCH] Add createPicture to HSSFShapeGroup + Detect Office 2007 XML documents, and throw a meaningful exception + Additional HSLF support for PowerPoint + Initial support for HWPF image extraction + + + + Additional HSLF support for PowerPoint + + + + HSSF Formula support + Additional HSLF support for PowerPoint + 39389 - [PATCH] Extended Ascii support for WingDings + + + + Bugzilla Bug 29976 [PATCH] HSSF hyperlink formula size problem + Image writing support + HSLF - Initial PowerPoint Support. Includes: Support for text extraction across the whole file; Support for getting individual slides, and their notes, and extracting text from those; Initial support for changing (but not adding) text + + + + Outlining support + 27574 - [PATCH] HSSFDateUtil.getExcelDate() is one hour off when DST changes + 26465 - [PATCH] wrong lastrow entry + 28203 - [PATCH] Unable to open read-write excel file including forms + + + + Add support for the Escher file format + 27005 java.lang.IndexOutOfBoundsException during Workbook.cloneSheet() + + + + No changes + + + + Bug 25695 - HSSFCell.getStringCellValue() on cell which has string formula will return swap bye unicode characters. + Updated website for upcoming release + Formula Parser fixes with tests, by Peter M Murray Bug 25457 + Fixed cloning merge regions + The cloned reference for merged cells did not create a new collection, so deletes cascaded to the original. + Fix to 24519 call to getCustomPalette() from a newly created workbook now works + Fix supplied for bug 24397 where some compilation got ambiguous classes. Explicitly imports the classes. Patch supplied by Jean-Pierre Paris. + + + + 12561 (Min) HSSFWorkbook throws Exceptions + 12730 (Nor) values dont get copied to another sheet. + 13224 (Maj) Exception thrown when cell has =Names call + 13796 (Nor) Error Reading Formula Record (optimized if, external link) + 13921 (Nor) Sheet name cannot exceed 31 characters and cannot contain : + 14330 (Nor) Error reading FormulaRecord + 14460 (Nor) Name in Formula - ArrayOutOfBoundsException + 15228 (Cri) [Urgent] ArrayIndexoutofbounds Exception. POI - Version 1.8 + 16488 (Maj) Unable to open written spreadsheet in Excel, but can in Open + 16559 (Nor) testCustomPalette.xls crashes Excel 97 + 16560 (Nor) testBoolErr.xls crashes Excel '97 + 17374 (Min) HSSFFont - BOLDWEIGHT_NORMAL + 18800 (Maj) The sheet made by HSSFWorkbook#cloneSheet() doesn't work cor + 18846 (Min) [PATCH][RFE]Refactor the transformation between byte array a + 19599 (Min) java.lang.IllegalArgumentException + 19961 (Nor) [PATCH] Sheet.getColumnWidth() returns wrong value + 21066 (Blo) Can not modify a blank spreadsheet + 21444 (Enh) [PATCH] Macro functions + 21447 (Nor) [RFE]String Formula Cells + 21674 (Enh) [PATCH] Documentation changes for @(Greater|Less|Not)EqualPt + 21863 (Enh) [PATCH] build.xml fixes + 22195 (Nor) [RFE] [PATCH] Support for Storage Class ID + 22742 (Cri) Failed to create HSSFWorkbook! + 22922 (Cri) HSSFSheet.shiftRows() throws java.lang.IndexOutOfBoundsExcep + 22963 (Nor) org.apache.poi.hpsf.SummaryInformation.getEditTime() should + 24149 (Maj) Error passing inputstream to POIFSFileSystem + 21722 (Nor) [PATCH] Add a ProtectRecord to Sheets and give control over + 9576 (Nor) [PATCH] DBCELL, INDEX EXTSST (was Acess 97 import) + 13478 (Blo) [PATCH] [RFE] POIFS, RawDataBlock: Missing workaround for lo + 14824 (Nor) Unable to modify empty sheets + 12843 (Cri) [PATCH] Make POI handle chinese better + 15353 (Nor) [RFE] creating a cell with a hyperlink + 15375 (Blo) Post 1.5.1 POI causes spreadsheet to become unopenable. + + + + HPSF is now able to read properties which are given in the property set stream but which don't have a value ("variant" type VT_EMPTY). The getXXX() methods of the PropertySet class return null if their return type is a reference (like a string) or 0 if the return type is numeric. Details about the return types and about how to distinguish between a property value of zero and a property value that is not present can be found in the API documentation. + Gridlines can now be turned on and off + NamePTG refactoring/fixes + minor fixes to ExternSheet and formula strings + Sheet comparisons now ignore case + + + + A nasty concurrency problem has been fixed. Any users working in a multithreaded environment should seriously consider upgrading to this release. + The EXTSST record has been implemented. This record is used by excel for optimized reading of strings. + When rows are shifted, the merged regions now move with them. If a row contains 2 merged cells, the resulting shifted row should have those cells merged as well. + There were some issues when removing merged + regions (specifically, removing all of them and then adding some more) and have been resolved. + When a sheet contained shared formulas (when a formula is + dragged across greater than 6 cells), the clone would fail. We now support cloning of + sheets that contain this Excel optimization. + Support added for reading formulas with UnaryPlus and UnaryMinus operators. + + + Patch applied for deep cloning of worksheets was provided + Patch applied to allow sheet reordering + Added additional print area setting methods using row/column numbers + HDF: Negative Array size fix + Added argument pointers to support the IF formula + Formulas: Added special character support for string literals, specifically for SUMIF formula support and addresses a bug as well + BlockingInputStream committed to help ensure reads + Fixed problem with NaN values differing from the investigated value from file reads in FormulaRecords + Patch for getColumnWidth in HSSF + Patch for dealing with mult-level numbered lists in HDF + Due to named reference work, several named-ranged bugs were closed + Patch applied to prevent sheet corruption after a template modification + Shared Formulas now Supported + Added GreaterEqual, LessEqual and NotEqual to Formula Parser + Added GreaterThan and LessThan functionality to formulas + Patches for i10n + POI Build System Updated + font names can now be null + + + Support for zoom level + Freeze and split pane support + Row and column headers on printouts + + + Custom Data Format Support + Enhanced Unicode Support for Russian and Japanese + Enhanced formula support including read-only for + "optimized if" statements. + Support for cloning objects + Fixes for header/footer + Spanish Documentation translations + Support for preserving VBA macros + + + Removed runtime dependency on commons logging. + Formula support + + + Removed depedency on commons logging. Now define poi.logging system property to enable logging to standard out. + Fixed SST string handling so that spreadsheets with rich text or extended text will be read correctly. + + + New project build. + New project documentation system based on Cocoon. + Package rename + Various bug fixes + Early stages of HSF development (not ready for development) + Initial low level record support for charting (not complete) + + + Changes not recorded. + + + Created new event model + Optimizations made to HSSF including aggregate records for + values, rows, etc. + predictive sizing, offset based writing (instead of lots of + array copies) + minor re-factoring and bug fixes. + + + Changes not recorded. + + + Changes not recorded. + + + Minor documentation updates. + + + Added DataFormat helper class and exposed set and get format + on HSSFCellStyle + Fixed column width apis (unit wise) and various javadoc on + the subject + Fix for Dimensions record (again)... (one of these days I'll + write a unit test for this ;-p). + Some optimization on sheet creation. + + + Changes not recorded. + + + Added MulBlank, Blank, ColInfo + Added log4j facility and removed all sys.out type logging + Added support for adding font's, styles and corresponding + high level api for styling cells + added support for changing row height, cell width and default + row height/cell width. + Added fixes for internationalization (UTF-16 should work now + from HSSFCell.setStringValue, etc when the encoding is set) + added support for adding/removing and naming sheets. + + + Bugfix release. We were throwing an exception when reading + RKRecord objects. + + + Got continuation records to work (read/write) + Added various pre-support for formulas + Massive API reorganization, repackaging. + BiffViewer class added for validating HSSF & POI and/or + HSSF Output. + Better API support for modification. + + + Added encoding flag to high and low level api to use utf-16 + when needed (HSSFCell.setEncoding()) + added read only support for Label records (which are + reinterpreted as LabelSST when written) + Broken continuation record implementation (oops) + BiffViewer class added for validating HSSF & POI and/or + HSSF Output. + + + Support for read/write and modify. + Read only support for MulRK records (converted to Number when + writing) + + + + Changes not recorded. + + + Changes not recorded. + + + Changes not recorded. + + + Changes not recorded. + + + First ever public release + + + + + + + + + + + Finish HDF + + + Finish Charts + + + Finish Formulas. + + + + + + Expose functionality in low level records in higher level API + + + Implement more record types. + + + Add more dummy checks (for when API user's do things they + "can't" do). This will involve exploring the various + upper limits on the things Excel can handle. + + + Add support for embedded graphics and other objects. + + + Create new adapter object for handling MulBlank, MulRk, Rk + records. + + + Add a way to copy sheets. + + + + + + diff --git a/src/documentation/content/xdocs/subversion.xml b/src/documentation/content/xdocs/subversion.xml new file mode 100644 index 0000000000..72d11017ca --- /dev/null +++ b/src/documentation/content/xdocs/subversion.xml @@ -0,0 +1,121 @@ + + + + + +
+ Apache POI - Source Code Repository + + + +
+ + +
Download the Source +

+ Most users of the source code probably don't need to have day to + day access to the source code as it changes. Most users will want + to make use of our source release + packages, which contain the complete source tree for each binary + release, suitable for browsing or debugging. These source releases + are available from our + download page. +

+

+ The Apache POI sourcecode is also available as source artifacts + in the Maven Central repository, which may be helpful for those + users who make use of POI and wish to inspect the source (eg when + debugging in an IDE). +

+
+
Access the Version Controlled Source Code +

+ For general information on connecting to the ASF Subversion, + repositories, see the + version control page. +

+

Subversion is an open-source version control system. It has been contributed to the Apache Software Foundation and is + now available here. +

+

+ The root url of the ASF Subversion repository is + http://svn.apache.org/repos/asf/ + for non-committers and + https://svn.apache.org/repos/asf/ + for committers. +

+ +

NOTE: When checking out a subproject using + subversion, ensure that you are checking out a tag, a branch or trunk + (the main-line) and not all tags and branches, to avoid filling up + your hard-disk and wasting bandwidth. +

+ +
    +
  • For read only access to the Apache POI svn, please use + http://svn.apache.org/repos/asf/poi/trunk/
    • +
  • For committers (write) access to the Apache POI svn, please use + https://svn.apache.org/repos/asf/poi/trunk/
    • +
  • To browse the svn repository in your web browser, please us + ViewSVN
    • +
+ +

If you are not a Committer, but you want to submit patches + or even request commit privileges, please see our + Guidelines for more + information.

+
+
Git access to POI sources +

+ The master source repository for Apache POI is the Subversion + one listed above. To support those users and developers who prefer + to use the Git tooling, read-only access to the POI source tree is + also available via Git. The Git mirrors normally track SVN to + within a few minutes. +

+

+ The official read-only Git repository for Apache POI is available + from git.apache.org/ . + The Git Clone URL is: git://git.apache.org/poi.git + and Http Clone URL: http://git.apache.org/poi.git . + Please see the Git at + Apache page for more details on the service. +

+

+ In addition to the git.apache.org/ + repository, changes are also mirrored in near-realtime to GitHub. + The GitHub repository is available at + https://github.com/apache/poi . + Please note that the GitHub repository is read-only, and all + contributions should continue to be sent via Bugzilla for tracking. + (Git patches are fine though). Please see the + contribution guidelines for more + information on getting involved in the project.

+
+ +
+ + Copyright (c) @year@ The Apache Software Foundation. All rights reserved. +
+ Apache POI, POI, Apache, the Apache feather logo, and the Apache + POI project logo are trademarks of The Apache Software Foundation. + +
+ diff --git a/src/documentation/content/xdocs/tabs.xml b/src/documentation/content/xdocs/tabs.xml new file mode 100644 index 0000000000..ca4c5330e6 --- /dev/null +++ b/src/documentation/content/xdocs/tabs.xml @@ -0,0 +1,40 @@ + + + + + + + + + + + + + diff --git a/src/documentation/content/xdocs/text-extraction.xml b/src/documentation/content/xdocs/text-extraction.xml new file mode 100644 index 0000000000..6caadf97ed --- /dev/null +++ b/src/documentation/content/xdocs/text-extraction.xml @@ -0,0 +1,186 @@ + + + + + +
+ Apache POI - Text Extraction + + + +
+ + +
Overview +

For a number of years now, Apache POI has provided basic + text extraction for all the project supported file formats. In + addition, as well as the (plain) text, these provides access to + the metadata associated with a given file, such as title and + author.

+

For more advanced text extraction needs, including Rich Text + extraction (such as formatting and styling), along with XML and + HTML output, Apache POI works closely with + Apache Tika to deliver + POI-powered Tika Parsers for all the project supported file formats.

+

If you are after turn-key text extraction, including the latest + support, styles etc, you are strongly advised to make use of + Apache Tika, which builds + on top of POI to provide Text and Metadata extraction. If you wish + to have something very simple and stand-alone, or you wish to make + heavy modificiations, then the POI provided text extractors documented + below might be a better fit for your needs.

+
+ +
Common functionality +

All of the POI text extractors extend from + org.apache.poi.POITextExtractor. This provides a common + method across all extractors, getText(). For many cases, the text + returned will be all you need. However, many extractors do provide + more targetted text extraction methods, so you may wish to use + these in some cases.

+

All POIFS / OLE 2 based text extractors also extend from + org.apache.poi.POIOLE2TextExtractor. This additionally + provides common methods to get at the HPFS + document metadata.

+

All OOXML based text extractors (available in POI 3.5 and later) + also extend from + org.apache.poi.POIOOXMLTextExtractor. This additionally + provides common methods to get at the OOXML metadata.

+
+ +
Text Extractor Factory +

As part of the addition of OOXML support in Apache POI 3.5, there + is a common class to select the appropriate POI text extractor for + you. org.apache.poi.extractor.ExtractorFactory provides a + similar function to WorkbookFactory. You simply pass it an + InputStream, a File, a POIFSFileSystem or a OOXML Package. It + figures out the correct text extractor for you, and returns it.

+

For complete detection and text extractor auto-selection, users + are strongly encouraged to investigate + Apache Tika.

+
+ +
Excel +

For .xls files, there is + org.apache.poi.hssf.extractor.ExcelExtractor, which will + return text, optionally with formulas instead of their contents. + Those using POI 3.5 can also use + org.apache.poi.xssf.extractor.XSSFExcelExtractor, to perform + a similar task for .xlsx files.

+

In addition, there is a second text extractor for .xls files, + org.apache.poi.hssf.extractor.EventBasedExcelExtractor. This + is based on the streaming EventUserModel code, and will generally + deliver a lower memory footprint for extraction. However, it will + have problems correctly outputting more complex formulas, as it + works with records as they pass, and so doesn't have access to all + parts of complex and shared formulas.

+
+ +
Word +

For .doc files from Word 97 - Word 2003, in scratchpad there is + org.apache.poi.hwpf.extractor.WordExtractor, which will + return text for your document.

+

Those using POI 3.7 can also extract simple textual content from + older Word 6 and Word 95 files, using the scratchpad class + org.apache.poi.hwpf.extractor.Word6Extractor.

+

Since POI 3.5, it is possible to use + org.apache.poi.xwpf.extractor.XPFFWordExtractor, to perform + text extraction for .docx files.

+
+ +
PowerPoint +

For .ppt files, in scratchpad there is + org.apache.poi.hslf.extractor.PowerPointExtractor, which + will return text for your slideshow, optionally restricted to just + slides text or notes text. Those using POI 3.5 can also use + org.apache.poi.xslf.extractor.XSLFPowerPointExtractor, to + perform a similar task for .pptx files.

+
+ +
Publisher +

For .pub files, in scratchpad there is + org.apache.poi.hpbf.extractor.PublisherExtractor, which + will return text for your file.

+
+ +
Visio +

For .vsd files, in scratchpad there is + org.apache.poi.hdgf.extractor.VisioTextExtractor, which + will return text for your file.

+
+ +
Embedded Objects +

Extractors already exist for Excel, Word, PowerPoint and Visio; + if one of these objects is embedded into a worksheet, the ExtractorFactory class can be used to recover an extractor for it. +

+ +FileInputStream fis = new FileInputStream(inputFile); +POIFSFileSystem fileSystem = new POIFSFileSystem(fis); +// Firstly, get an extractor for the Workbook +POIOLE2TextExtractor oleTextExtractor = + ExtractorFactory.createExtractor(fileSystem); +// Then a List of extractors for any embedded Excel, Word, PowerPoint +// or Visio objects embedded into it. +POITextExtractor[] embeddedExtractors = + ExtractorFactory.getEmbededDocsTextExtractors(oleTextExtractor); +for (POITextExtractor textExtractor : embeddedExtractors) { + // If the embedded object was an Excel spreadsheet. + if (textExtractor instanceof ExcelExtractor) { + ExcelExtractor excelExtractor = (ExcelExtractor) textExtractor; + System.out.println(excelExtractor.getText()); + } + // A Word Document + else if (textExtractor instanceof WordExtractor) { + WordExtractor wordExtractor = (WordExtractor) textExtractor; + String[] paragraphText = wordExtractor.getParagraphText(); + for (String paragraph : paragraphText) { + System.out.println(paragraph); + } + // Display the document's header and footer text + System.out.println("Footer text: " + wordExtractor.getFooterText()); + System.out.println("Header text: " + wordExtractor.getHeaderText()); + } + // PowerPoint Presentation. + else if (textExtractor instanceof PowerPointExtractor) { + PowerPointExtractor powerPointExtractor = + (PowerPointExtractor) textExtractor; + System.out.println("Text: " + powerPointExtractor.getText()); + System.out.println("Notes: " + powerPointExtractor.getNotes()); + } + // Visio Drawing + else if (textExtractor instanceof VisioTextExtractor) { + VisioTextExtractor visioTextExtractor = + (VisioTextExtractor) textExtractor; + System.out.println("Text: " + visioTextExtractor.getText()); + } +} + +
+ + +
+ + Copyright (c) @year@ The Apache Software Foundation. All rights reserved. +
+ Apache POI, POI, Apache, the Apache feather logo, and the Apache + POI project logo are trademarks of The Apache Software Foundation. + +
+ diff --git a/src/documentation/content/xdocs/todo.xml b/src/documentation/content/xdocs/todo.xml new file mode 100644 index 0000000000..2ec7f44bde --- /dev/null +++ b/src/documentation/content/xdocs/todo.xml @@ -0,0 +1,70 @@ + + + + + +Things To Do for Poi + + + + + + + + + + + + + + + Finish HWPF + + + Finish Charts + + + Evaluate and bugfix performance code in HEAD + + + + + + + Implement more record types. + + + Add more dummy checks (for when API user's do things they + "can't" do). This will involve exploring the various + upper limits on the things Excel can handle. + + + Add support for embedded graphics and other objects. + + + Create new adapter object for handling MulBlank, MulRk, Rk + records. + + + Improve formulas (Shared Formulas, Unkown PTG's) + + + + diff --git a/src/documentation/content/xdocs/trans/book.xml b/src/documentation/content/xdocs/trans/book.xml new file mode 100644 index 0000000000..86ae3a94ad --- /dev/null +++ b/src/documentation/content/xdocs/trans/book.xml @@ -0,0 +1,39 @@ + + + + + + + + + + + + + + + + + + + diff --git a/src/documentation/content/xdocs/trans/de/book.xml b/src/documentation/content/xdocs/trans/de/book.xml new file mode 100644 index 0000000000..0356d949d6 --- /dev/null +++ b/src/documentation/content/xdocs/trans/de/book.xml @@ -0,0 +1,88 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/src/documentation/content/xdocs/trans/de/index.xml b/src/documentation/content/xdocs/trans/de/index.xml new file mode 100644 index 0000000000..6345c406f6 --- /dev/null +++ b/src/documentation/content/xdocs/trans/de/index.xml @@ -0,0 +1,229 @@ + + + + + +
+ Willkommen bei POI + + + + + + +
+ + +
Nachrichten +
Übersetzungen +

+ Das POI-Übersetzungsprojekt hat begonnen. + Den Anfang machen spanisch, + japanisch + und deutsch. Andere Sprachen sind herzlich willkommen. + Machen Sie mit! +

+
+
Logo-Wettbewerb +

+ Die Wahl für das POI-Logo ist beendet. Danke für Ihre Stimmen. +

+ + + +
+
+
Zweck +

+ Das POI-Projekt besteht aus Java-APIs zum Erstellen und + Bearbeiten von Dateiformaten, die auf dem Microsoft-Dateiformat »OLE-2 + Compound Document« beruhen. Dateien in diesem Format sind unter + anderem die meisten Microsoft-Office-Dateien, wie zum + Beispiel Excel- und Word-Dateien. +

+

+ Grundsätzlich versuchen wir, möglichst viel mit anderen Projekten + zusammenzuarbeiten, um die gewünschten Funktionalitäten zur Verfügung + zu stellen. Einige Beispiele: Für + Cocoon + werden bald Generatoren und Serializer zur Verfügung stehen. Wir + arbeiten mit + Open Office.org + zusammen, um das Excel-Dateiformat zu + dokumentieren. + Für Lucene + werden bald Filtermodule zur Verfügung stehen. Wir stellen anderen + Projekten Teile des POI-Projektes zur Verfügung, damit diese + die POI-Funktionalitäten nutzen können. +

+
Warum und wann sollte man POI nutzen? +

+ Wir werden diese Frage komponentenweise beantworten. POI besteht aus + einer Reihe von Komponenten, die jeweils unterschiedliche Probleme + angehen. Das Kürzel »POI« steht für das gesamte Projekt. +

+

+ Mit POIFS können Sie Dateien oder Dokumente, die im + OLE 2 Compound Document Format geschrieben wurden, mit Java + einlesen. Solche Dateien werden üblicherweise mit der + MFC-Klassenbibliothek erzeugt. + Außerdem können sie POIFS nutzen, um Dateien im OLE 2 Compound + Document Format zu schreiben. Damit können sie zum Beispiel + den Datenaustausch mit der Windows-Plattform sicherstellen. + Wir können guten Gewissens behaupten, daß POIFS die + vollständigste Implementierung dieses Dateiformates ist. +

+

+ Mit HSSF können sie Excel-Dateien in Java lesen und + schreiben. Sie können auch Excel-Tabellen lesen und + modifizieren. Allerdings ist die Schreibfunktionalität im Moment am + ausgereiftesten. +

+
+ +
Wofür steht POI ? +

+ POI bedeutet »Poor Obfuscation Implementation« (Schlechte, + verschleiernde Implementierung). + Warum geben wir unserem Projekt einen so abschätzigen Namen? + Nun, das Microsoft OLE 2 Compound Document Format ist einfach + schlecht durchdacht. Von seiner Grundidee her ist es ein + Dateiarchiv mit einer Struktur, die dem alten DOS-FAT-Dateisystem + ähnelt. Die Redmonder haben kein bereits vorhandenes Archivformat + wie tar, gzip, zip oder arc genutzt, sondern stattdessen ein + eigenes Archivformat erfunden, + das keinerlei Standardverschlüsselung oder -komprimierung + bietet, das schlecht erweiterbar ist, und das zur + Fragmentierung neigt. +

+

POI ist außerdem eine Spezialität der hawaiianischen Küche. Sie wird + in Merriam Webster's + Dictionary beschrieben als: »Ein hawaiianisches Gericht aus + Taro-Wurzeln, die durch Stampfen, Kochen und Kneten zu einer Paste + geformt und oft noch ein wenig gegoren wird.« Dies ist witzigerweise + eine treffende Beschreibung des Dateiformats.

+

+ POI ist also eine Abkürzung. Wenn Sie Abkürzungen nicht mögen, + dann denken sie einfach bei POI an das hawaiianischen Gericht. + Je nachdem, ob Sie Abkürzungen mögen oder nicht, nutzen sie + einfach POI oder Poi, wenn sie dieses Projekt meinen. +

+
+
+ + +
Komponenten +
Überblick +

+ POI besteht aus mehreren Komponenten, die jeweils unterschiedliche + Aufgaben angehen. Beispielsweise dient die Komponente HSSF dazu, + Excel-Dateien zu schreiben und zu lesen. Es folgt eine Liste aller + Komponenten des POI-Projektes mit einer sehr kurzen Zusammenfassung + ihres Zweckes. +

+
+
POIFS (POI Filesystem) +

+ POIFS ist der älteste und stabilste Teil des Projektes. POIFS + ist unsere Portierung des OLE 2 Compound Document Formats + in reinem Java. Es unterstützt Lesen und Schreiben. Alle + anderen Komponenten basieren auf POIFS. Mehr Informationen + gibt es auf der POIFS-Seite. +

+
+
HSSF +

+ HSSF ist unsere Portierung des Microsoft Excel 97(-2002) + Dateiformats in reinem Java. Es unterstützt Lesen und + Schreiben. Mehr Informationen gibt es auf der + HSSF-Seite. +

+
+
HWPF +

+ HWPF ist unsere Portierung des Microsoft Word 97 Datei-Formats + in reinem Java. Es unterstützt Lesen und Schreiben. Mehr + Informationen gibt es auf der + HWPF-Seite. + Diese Komponente ist noch nicht sehr weit fortgeschritten. Wir suchen + Entwickler, die mitmachen. +

+
+
HPSF +

+ HPSF ist unsere Portierung des OLE 2 Property Formats. + Property Sets nehmen die Metadaten eines + Dokuments auf, wie Titel, Autor und Datum. Sie + lassen sich aber auch für applikationsspezifische Aufgaben + nutzen. Mehr Informationen gibt es auf der + HPSF-Seite. +

+
+
+
Mitmachen +

+ Sie möchten bei diesem Projekt mitmachen? Hervorragend! + Wir brauchen immer begeisterte, fleißige und talentierte Leute, die + uns bei den verschiedenen Aufgaben des Projektes helfen. An erster + Stelle stehen Hinweise auf Fehler und Vorschläge für neue + Funktionen. Ebenso wichtig ist die Dokumentation.

+

Egal, ob sie Kritik oder Vorschläge haben, + oder ob Sie Beiträge in Form von Code oder Dokumentation liefern + möchten, immer werden Sie bei uns ein offenes Ohr + finden. Und nicht zuletzt brauchen wir Java-Programmierer, die + sich durch die zahlreichen Ecken und Kanten der Microsoft-Dateiformate + hindurchwühlen und uns dabei helfen, diese Formate auf die + Java-Plattform zu portieren. +

+

+ Wenn Sie motiviert sind und Zeit haben, tragen Sie sich + in unsere Mailing-Listen ein, und machen sie mit! Bei der Einarbeitung + helfen wir Ihnen gerne. +

+
+ +
+ + Copyright (c) @year@ The Apache Software Foundation All rights reserved. +
+ Apache POI, POI, Apache, the Apache feather logo, and the Apache + POI project logo are trademarks of The Apache Software Foundation. + +
+ + + diff --git a/src/documentation/content/xdocs/trans/es/3rdparty.xml b/src/documentation/content/xdocs/trans/es/3rdparty.xml new file mode 100644 index 0000000000..82d3f173d0 --- /dev/null +++ b/src/documentation/content/xdocs/trans/es/3rdparty.xml @@ -0,0 +1,87 @@ + + + + + +
+ Jakarta POI - Contribuciones de Terceras Partes + + + + +
+ + + +
Cómo Contribuir +

+ Vea Cómo contribuir a Poi. +

+ +
+ +
Componentes Contribuidos +

+ No es que estos tengan, necesariamente, suficiente calidad como para ser incluidos + en el núcleo de la distribución, pero han sido probados bajo + varios entornos clave , se proporcionan bajo la misma licencia que Poi, y se + incluyen en la distribución de POI bajo el directorio + contrib/. +

+ +

+ ¡Ninguno Todavía! - aunque pude esperarse que algunos de los enlaces + listados a continuación lleguen eventualmente a migrarse al nivel de "componentes contribuidos", + y posteriormente incluso a la mismísima distribución principal. +

+
+ +
Cola de Parches (Patch Queue) +

Entregas de modificaciones (Submissions of modifications) + a POI que esperan revisión. Cualquiera puede realizar comentarios sobre ellas en la lista + de desarrollo - ¡se necesitan revisores del código! + Su utilización cae bajo su responsabilidad - aunque POI no puede garantizarlo, + estos parches no han sido revisados, cuando menos aceptados. +

+
+ +
Otras Extensiones +

Las otras extensiones listadas aquí tampoco están respaldadas + por el proyecto POI - se proporcionan sólo por comodidad. Pueden funcionar o no, + pueden ser de código abierto o no, etc. +

+ +

Para añadir un enlace a esta tabla, ver Cómo contribuir + a POI.

+ + + + + + + + + + +
Nombre y EnlaceTipoDescripciónEstadoLicenciaContacto
+ +
+ + diff --git a/src/documentation/content/xdocs/trans/es/book.xml b/src/documentation/content/xdocs/trans/es/book.xml new file mode 100644 index 0000000000..0e9bedd9d1 --- /dev/null +++ b/src/documentation/content/xdocs/trans/es/book.xml @@ -0,0 +1,86 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/src/documentation/content/xdocs/trans/es/casestudies.xml b/src/documentation/content/xdocs/trans/es/casestudies.xml new file mode 100644 index 0000000000..11a6e2bf1b --- /dev/null +++ b/src/documentation/content/xdocs/trans/es/casestudies.xml @@ -0,0 +1,190 @@ + + + + + +
+ Jakarta POI - Estudio de Casos + + + + + +
+ + +
+ Introducción +

+ Mucha gente está utilizando POI para distintos propósitos. Como con cualquier + nueva API o tecnologia, la primera pregunta que la gente pregunta normalmente + no es "cómo puedo" sino "Quién más está haciendo lo que yo estoy a punto de + hacer?" Esto es comprensible con el abismal porcentage de éxito en el negocio + del software. Estos Casos pretenden ayudar a crear + confianza y comprensión. +

+
+
+ Enviando un Estudio de un Caso +

+ Estamos buscando activamente estudios de casos para esta página (después de todo + acaba de comenzarse). Andrew C. Oliver (acoliver at apache dot org) ha + accedido a entregar unas cuantas Camisetas con el logotipo de POI para + los primeros y mejores envíos. Para enviar un estudio de un caso, puedes + + enviar un parche para esta página o enviarlo por correo electrónico + a la lista de correo + (con [PATCH] como prefijo en el asunto, por favor). +

+
+
+ Estudios de Casos +
Sunshine Systems +

+ Sunshine Systems desarrolló una + solución de informes basada en POI para un paquete software de optimización de precios + que se usa en grandes cadenas de venta. +

+

La solución permitió a los planificadores y gestores de la mercancía mercancía pedir + unos informes de soporte a la decisión e informes de cambios de precios utilizando un + navegador estándar. Los usuarios pueden especificar el tipo de informe, las opciones, así + como criterios de filtros como la división de la compañía + o departamento. La generación de informes se llevó a cabo en el + servidor de aplicaciones multi-hilo + y fue capaz de soportar muchas peticiones de informe simultáneas. +

+

La aplicación de informes recogía información del negocio de la base + de datos Oracle de la aplicación de optimización de precios. + Los datos se agregaban y resumían basándose en el tipo específico + de informe y los criterios de filtro pedidos por el usuario. El + informe final se generaba como una hoja de cálculo de Microsoft Excel utilizando + el API de POI HSSF y se almacenaba en el + servidor de base de datos de informes para ese usuario específico como un BLOB. + Los informes pueden ser vistos + fácilmente y bien integrados utilizando el mismo navegador. +

+

A los vendedores les gusto la solución porque así tenían acceso instantáneo + a datos del negocio críticios + a través de una interfaz basada en navegador extremadamente fácil de usar. + No necesitaban entrenar a su amplia comunidad de usuarios en las complejidades de la + aplicación de optimización. Lo que es más, los informes se generaban en un formato de + hoja de cálculo Excel, + que todo el mundo conocía y que también permitía análisis + de datos adicionales utilizando + características estándares de Excel. +

+

Rob Stevenson (rstevenson at sunshinesys dot com) +

+
+
+ Banco de Lituania +

+ El + Banco de Lituania + genera informes de datos estadísticos financieros en formato Excel + utilizando el API + HSSF del proyecto + Jakarta POI + El sistema está basado en Oracle JServer y utiliza + un procedimiento almacenado Java que utilizando el API HSSF + responde en formato XLS. - Arian Lashkov (alaskov at lbank.lt) +

+
+ + + + + + + + + + + + + + + + + +
+ Edwards And Kelcey Technology +

+ Edwards and Kelcey Technology (http://www.ekcorp.com/) desarrolló + un Sistema de Mantenimiento y Gestión de Instalaciones + para la industria de las Telecomunicaciones. + basado en Turbine y Velocity. + Originalmente la factura se hacía con una sencilla + hoja CVS que era entonces + marcada por cada cuenta y particularizada para cada cliente. + Como el crecimiento ha sido consistente con la aplicación, las necesidades de + facturas que no necesitasen ser retocadas a mano aumentaron. POI proporcionó la + solución a este problema, integrandose fácil y transparentemente en el sistema. + Se utilizó POI HSSF para crear las facturas directamente desde el servidor + en formato Excel 97 + y ahora sirve más de 150 facturas diferentes cada mes. +

+

+ Cameron Riley (crileyNO@ SPAMekmail.com) +

+
+
+ ClickFind +

+ ClickFind Inc. utilizó el API + HSSF del proyecto POI para proporcionar a sus clientes + de investigación médica la capacidad de exportar a Excel desde su servicio + web de recolección de datos electrónicos Data Collector 3.0. La asistencia del equipo de POI + permitió que ClickFind proporcionara a sus clientes un formato de datos que requiere menos + conocimentos técnicos que el formato XML utilizado por la aplicación Data Collector. + Esto era importante para ClickFind ya que muchos de sus clientes actuales y potenciales + estaban utilizando Excel en sus operaciones del día-a-día + así como en procedimientos establecidos para el manejo de sus datos clínicos + generados. - Jared Walker (jared.walker at clickfind.com) +

+
+
+ IKAN Software NV +

Además de Gestión del Cambio y Modelado de Base de Datos, IKAN Software NV + (http://www.ikan.be/) desarrolla y da soporte a su propia herramienta ETL + (Extrae/Transforma/Carga ó Extract/Transform/Load).

+ +

El último producto de IKAN en este dominio se llama ETL4ALL + (http://www.ikan.be/etl4all/). ETL4ALL es una herramienta de código abierto + que permite la transferencia de datos desde y hacia virtualmente cualquier + orígen de datos. Los usuarios pueden combinar y examinar datos almacenados en + base de datos relacionales, bases de datos XML, PDF, ficheros, EDI, CSV, etc. +

+ +

Es evidente que los ficheros de Microsoft Excel también estan soportados. + POI se ha utilizado para implementar con éxito este soporte en ETL4ALL.

+
+ +
+ +
+ + Copyright (c) @year@ The Apache Software Foundation All rights reserved. +
+ Apache POI, POI, Apache, the Apache feather logo, and the Apache + POI project logo are trademarks of The Apache Software Foundation. + +
+ diff --git a/src/documentation/content/xdocs/trans/es/changes.xml b/src/documentation/content/xdocs/trans/es/changes.xml new file mode 100644 index 0000000000..b7c903fd23 --- /dev/null +++ b/src/documentation/content/xdocs/trans/es/changes.xml @@ -0,0 +1,152 @@ + + + + + + + Historial de Cambios + + + + + + + + + + + Parche aplicado para el clonado en profundidad de hojas. + Parche aplicado para permitir la reordenación de la hoja + Se añaden métodos adicionales para definir el área de impresión utilizando números de fila/columna + HWPF: arreglado un error de tamaño negativo del Array + Se añaden punteros a argumento para soportar la fórmula IF + Formulas: Se añade soporte de caracteres especiales para cadenas literales, específicamente para soporte de fórmulas SUMIF y tratar un error tambien + BlockingInputStream subido para ayudar a asegurar las lecturas + Se arregló un problema con valores NaN (No es Número) que diferían del valor investigado de lectura en ficheros de FormulaRecords + Parche para getColumnWidth en HSSF + Parche para tratar con listas multi-nivel numeradas en HWPF + Debido a los trabajos en las referencias con nombre, varios errores de nombres de rango se cerraron + Parche aplicado para prevenir la corrupción de la hoja tras la modificación de una plantilla (template) + Soporte para fórmulas compartidas + Añadidos GreaterEqual, LessEqual y NotEqual al Evaluador de Fórmulas (Parser) + Añadida la funcionalidad GreaterThan y LessThan a las fórmulas + Parches para i10n + POI Build System Actualizado + nombres de fuentes pueden ser nulos + + + Soporte para el nivel de ampliación (zoom) + Soporte para el congelado y división del panel + Cabeceras de fila y columna en impresiones + + + Soporte para Formato de Datos Personalizado (Custom) + Soporte Unicode Mejorado para Ruso y Japonés + Soporte para Fórmulas Mejorado, incluyendo + sólo-lectura para sentencias tipo "optimizado si" (optimized if). + Soporte para la clonación de objetos + Arreglos en la cabecera/pie + Traducciones de la documentación al Español + Soporte para preservar macros VBA + + + Se quita la dependencia en tiempo de ejecución del registro + (logging) de "commons". + Soporte para fórmulas + + + Se quita la dependencia del registro de "commons". Ahora hay que definir la propiedad del sistema poi.loggin para permitir + que los registros (logs) vayan a la salida estándar. + Se arregla la gestión de la cadena SST para que las hojas de cálculo con texto rico (rich text) o texto + extendido se lean correctamente. + + + Nueva versión (build) del proyecto. + Nuevo sistema de documentación del proyecto basada en Cocoon. + Cambio de nombre del paquete + Varios errores (bugs) corregidos + Etapas preliminares del desarrollo de HFS (no esta listo para el desarrollo) + Soporte inicial de registros de bajo nivel para gráficas (no está completo) + + + + Se crea un nuevo modelo de eventos + Se optimiza HSSF, incluyendo registros (records) para + valores, filas, etc. + predicción de tamaño, escritura basada en desplazamiento (en lugar de + multitud de copias de arrays) + un poco de re-factoring (¿re-factorización? mejor no) y corrección de errores. + + + Actualizaciones menores a la documentación. + + + Se añade la clase de ayuda DataFormat y se expone el formato set y get en + HSSFCellStyle + Correcciones a las apis de anchura de columna (en cuanto a las unidades) y + varios comentarios javadoc al respecto + Corrección para el registro de "Dimensions" (de nuevo)... (uno de estos días + escribiré una prueba unitaria (unit test) para esto ;-p). + Alguna optimización en la creación de páginas. + + + Mejoras no registradas + + + Se añaden MulBlank, Blank, ColInfo + Se añade facilidad log4j y se quitan las anotaciones (logs) del tipo sys.out + Se añade soporte para la adición de fuentes, estilos y el api de alto + nivel correspondiente para dar estilo a las celdas + Se añade soporte para cambiar el alto de una fila, el ancho de una celda, y + sus valores por defecto. + Correcciones para internacionalización (UTF-16 debería funcionar ahora + desde HSSFCell.setStringValue, etc cuando se define la codificación) + Soporte para la adición / eliminación y cambio de nombre de hojas. + + + Distribución de corrección de errores. + Lanzamos una excepción cuando leemos objetos de tipo RKRecord. + + + Registros de continuación ya funcionan (lectura/escritura) + Se añade soporte previo para fórmulas + Reorganización del API masiva, re-enpaquetado. + Se añade la clase BiffViewer para validar HSSF & POI y/o la + salida de HSSF. + Se mejora el soporte a la modificación del API. + + + Se añade una bandera de codificación para que las apis de alto + y bajo nivel utilicen utf-16 cuando sea necesario (HSSFCell.setEncoding()) + Se añade soporte de sólo lectura a registros de Etiqueta + (que son reinterpretados como LabelSST cuando se escriben) + Se rompe la implementación del registro de continuación (oops) + Se añade la clase BiffViewer + para validar HSSF & POI y/o la + salida de HSSF. + + + Soporte para lectura/escritura y modificación. + Soporte de sólo lectura para registros de tipo MulRK + (convertidos a Number cuando se escriben) + + + + diff --git a/src/documentation/content/xdocs/trans/es/faq.xml b/src/documentation/content/xdocs/trans/es/faq.xml new file mode 100644 index 0000000000..33076a51e4 --- /dev/null +++ b/src/documentation/content/xdocs/trans/es/faq.xml @@ -0,0 +1,226 @@ + + + + + + + + or qula lectura de una hoja de cculo simple lleva tanto tiempo? + + +

+ Probablemente hayas habilitado el registro (logging). Dicho registro es + una herramienta il para la bqueda de errores (debug). Tenerlo habilitado + reducirel rendimiento en un factor de al menos 100. El registro es il para + comprender por quPOI no puede leer alg fichero o para el propio desarrollo + de POI. + Los errores importantes se lanzan como excepciones, lo cual significa que + probablemente no necesites el registro (log). +

+ + + + + ues el "eventmodel" (modelo de evento) de HSSF? + + +

El paquete "eventmodel" de HSSF es un nuevo API para la lectura m eficiente de ficheros + XML. Requiere mayor conocimiento por parte del usuario, pero reduce el consumo de memoria a + una dima parte. Estbasado en el modelo de eventos AWT en combinaci con SAX. Si necesita + acceso de so-lectura a un fichero XML determinado, esta es la mejor manera de hacerlo.

+ + + + + + or quno puedo leer el documento que creutilizando Star Office 5.1? + + +

Star Office 5.1 escribe algunos registros utilizando el viejo estdar BIFF. + Esto provoca algunos problemas con POI que so soporta BIFF8.

+ + + + + or qurecibo una excepci cada vez que intento leer mi hoja de cculo? + + +

Es posible que su hoja de cculo contenga alguna caractertica que no est + soportada actualmente por HSSF. Por ejemplo - hojas de cculo que contengan + celdas con formato RTF (rich text) no est soportadas actualmente.

+ + + + + oporta HSSF hojas de cculo protegidas? + + +

Al proteger una hoja de cculo, ta se cifra. No tocaremos el cifrado, porque no + tenemos el suficiente conocimiento legal y no estamos seguros de las implicaciones que + conllevar el intentar implementar esto. Si desea intentarlo, es libre de hacerlo y + de adirlo como un mulo enchufable (plugin). Sin embargo, no lo guardaremos aqu

+ + + + + o se sabe si un campo contiene una fecha con HSSF? + + +

Excel almacena las fechas como neros. Asla ica manera para determinar + si una celda estrealmente almacenada como una fecha consiste en mirar su formato. + Hay un modo de ayuda (helper) en HSSFDateUtil (desde la distribuci 1.7.0-dev) + que lo comprueba. Gracias a Jason Hoffman por proporcionar la soluci.

+ + +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; + } + + + + + + + Estoy intentando ver un fichero XLS enviado como flujo (stream) desde un servlet y tengo + complicaciones. u es el problema? + + +

+ El problema normalmente se manifiesta como un mont de caracteres basura + en la pantalla. El problema persiste incluso aunque hayas configurado el tipo mime + correcto. +

+

+ La respuesta breve es: no dependas de IE para mostrar un fichero binario. + Escribe un documento adjunto como es debido si lo envs a trav de un servlet. + Toda versi de IE tiene diferentes fallos (bugs) en este sentido. +

+

+ El problema en la mayor de las versiones de IE reside en que no utiliza el tipo mime + de la respuesta HTTP para determinar el tipo de fichero; en su lugar utiliza la extensi + del fichero en la petici. Aspodr adir un .xls a su cadena de petici. + Por ejemplo: http://yourserver.com/myServelet.xls?param1=xx. Esto se consigue + filmente a trav del mapeo de URL en cualquier contenedor servlet. A veces una + petici como + http://yourserver.com/myServelet?param1=xx&dummy=file.xls + tambi funciona. +

+

+ Para garantizar la correcta apertura del fichero en Excel desde IE, escribe + tu fichero a un fichero temporal bajo su raiz web desde tu servlet. Env entonces + una respuesta http al navegador para que haga una redirecci en el lado del cliente + a tu fichero temporal. (Si haces una redirecci en el lado del servidor utilizando + RequestDispatcher, tendr que adir .xls a la petici como se ha mendionado m + arriba) +

+

+ Date cuenta de que cuando pides un documento que se abre con un manejador externo, + IE a veces realiza dos peticiones al servidor web. Asque si tu proceso generador + es pesado, tiene sentido escribir a un fichero temporal, para que peticiones + mtiples utilicen el fichero estico. +

+

+ Nada de esto pertenece a Excel. El mismo problema ocurre cuando intentas general + cualquier fichero binario dinicamente a un cliente IE. Por ejemplo, si generas + ficheros pdf utilizando + FOP, + te encontrar con los mismos problemas. +

+ + + + + + Quiero dar formato a una celda (Data format of a cell) de una hoja excel como + ###,###,###.#### o ###,###,###.0000. s posible hacer esto con POI? + + +

+ HSSF no soporta todav formatos de datos personalizados, sin embargo, + deber ser una facilidad razonablemente sencilla de adir y aceptaremos + gustosos contribuciones en este ea. +

+

+ Estos son los formatos incluidos que soporta: +

+

+ http://jakarta.apache.org/poi/javadocs/javasrc/org/apache/poi/hssf/usermodel/HSSFDataFormat_java.html#HSSFDataFormat +

+ + + + + o ado un borde alrededor de una celda unida (merged)? + + +

+ Ade celdas vacs alrededor de donde las celdas hubieran estado normalmente y + configura los bordes individualmente para cada celda. + Probablemente mejoraremos HSSF en el futuro para facilitar este proceso. +

+ + + + + Intentescribir valores en celdas ascomo cambiar el nombre de la hoja Excel + en mi lengua nativa, pero no pude hacerlo. :( + + +

+ Por defecto HSSF utiliza valores de celdas y nombres de hoja en unicode comprimido, + asi que para soportar la localizaci debers utilizar Unicode. + Para hacerlo debers configurarlo manualmente: +

+ + + // + // para el nombre de la hoja + // + HSSFWorkbook wb = new HSSFWorkbook(); + HSSFSheet s = wb.createSheet(); + wb.setSheetName( 0, "SomeUnicodeName", HSSFWorkbook.ENCODING_UTF_16 ); + + + // + // para el valor de la celda + // + HSSFRow r = s.createRow( 0 ); + HSSFCell c = r.createCell( (short)0 ); + c.setCellType( HSSFCell.CELL_TYPE_STRING ); + c.setEncoding( HSSFCell.ENCODING_UTF_16 ); + c.setCellValue( "\u0422\u0435\u0441\u0442\u043E\u0432\u0430\u044F" ); + + +

+ Asegate de que haces la llamada a setEncoding() antes de llamar a setCellValue(), + si no, lo que le pases no serinterpretado correctamente. +

+ + + diff --git a/src/documentation/content/xdocs/trans/es/historyandfuture.xml b/src/documentation/content/xdocs/trans/es/historyandfuture.xml new file mode 100644 index 0000000000..495da3f246 --- /dev/null +++ b/src/documentation/content/xdocs/trans/es/historyandfuture.xml @@ -0,0 +1,172 @@ + + + + + +
+ Historia del Proyecto + + + + +
+ + + + +
Breve Historia del Proyecto + +

+ El proyecto POI se gesttiempo atr, cerca de abril de 2001, + cuando Andrew Oliver obtuvo un contrato de corta duraci para realizar + informes Excel basados en Java. Ya hab realizado este proyecto unas + cuantas veces antes, y sab exactamente dde buscar las herramientas + que necesitar. + Iricamente, el API que sol utilizar se hab disparado en precio + desde unos $300 ($US) hasta unos $10K ($US). Calculque a dos personas + les llevar unos seis meses el portar Excel asque le recomendal + cliente que pagase los $10K. +

+ +

+ Cerca de junio de 2001, Andrew empeza pensar lo genial que ser + tener una herramienta Java de cigo abierto para hacer esto y, + mientras tuvo algo de tiempo libre, comenzel proyecto y aprendis + cosas sobre el Formato de Documento Compuesto OLE2. Tras chocarse + con varios obstulos insalvables, se dio cuenta de que necesitar ayuda. + Publicun mensaje en su Grupo de Usuarios Java local (JUG) y + preguntsi alguien estaba interesado. Tuvo mucha suerte y el + programador Java de mayor talento que hab conocido nunca, + Marc Johnson, se unial proyecto. A Marc le llevunas pocas + iteraciones el obtener algo con lo que estaban contentos. +

+ +

+ Mientras Marc trabajaba en eso, Andrew portXLS a Java, basdose + en la biblioteca de Marc. Varios usuarios escribieron peticiones + para poder leer XLS (no so escribirlo como hab sido planeado + originalmente) y un usuario ten peticiones especiales para + un uso diferente de POIFS. Antes de que pasara mucho tiempo, + el alcance del proyecto se hab triplicado. POI 1.0 se distribuys + un mes m tarde de lo planeado, pero con muchas m caracterticas. + Marc escribiridamente el marco del serializador y el + Serializador HSSF en tiempo rord y Andrew generm documentaci + y trabajen hacer que la gente conociera este proyecto. +

+ +

+ Poco antes de la distribuci, POI tuvo la fortuna de entrar + en contacto con Nicola -Ken- Barrozzi quien proporcionejemplos + para el Serializador HSSF y ayuda descrubir sus desafortunados + fallos (que fueron arreglados de inmediato). Recientemente, Ken + portla mayor de la documentaci del proyecto POI a XML + partiendo de los documentos HTML cutres que Andrew hab escrito + con Star Office. +

+ +

+ M o menos al mismo tiempo de la primera distribuci, Glen Stampoultzis + se unial proyecto. A Glen le molestaba la actitud impertinente de Andrew + en lo que adir capacidades gricas a HSSF se refer. Glen se molests + tanto que decidicoger un martillo y hacerlo mismo. Glen ya se ha + convertido en parte integral de la comunidad de desarrollo de POI; sus + contribuciones a HSSF ya han comenzado a producir olas. +

+ +

+ En algíì momento decidimos finalmente remitir el proyecto a + El Proyecto Cocoon + de Apache, so para descubrir que el proyecto hab + crecido encajando perfectamente con Cocoon hac tiempo. + Lo que es m, Andrew comenza ojear otros proyectos a los que + le gustar que se adiera la funcionalidad de POI. Asque + se decididonar los Serializadores y Generadores a Cocoon, otros + componentes de integraci con POI a otros proyectos, y los APIs + de POI pasarn a formar parte de Jakarta. Fue un camino con + baches, ¡ðero parece que todo salibien puesto que ahora est + leyendo esto! +

+ +
+ +
¿Èacia dde va POI? +

+ Primero abordaremos esto desde el punto de vista del proyecto: + Bueno, les hicimos la oferta a Microsoft y Actuate (de co + ... en su mayor parte) de que dejarmos el proyecto y nos + retirarmos si simplemente nos firmaban a cada uno un cheque + con muchos ceros. Todav estoy esperando una llamada o correo + electrico, asque de momento asumo que no nos van a pagar + para quitarnos de en medio. +

+

+ Despu, tenemos algo de trabajo que hacer aquen Jakarta + para terminar de integrar POI en la comunidad. Lo que es m, + todav estamos realizando la transici del Serializador a + Cocoon. +

+

+ HSSF, durante el ciclo 2.0, sufrirvarias optimizaciones. + Tambi adiremos nuevas caracterticas como una implementaci + completa de Fmulas y formatos de texto personalizados. Esperamos + ser capaces de generar ficheros m peques adiendo soporte de + escritura para registros RK, MulRK y MulBlank. A d de hoy, la + lectura en HSSF no es muy eficiente. Esto se debe sobre todo a que + para escribir o modificar, uno necesita ser capaz de actualizar + punteros del flujo de subida (upstream pointers) a datos del flujo + de bajada. Para hacer esto hay que tener todo lo que haya en + medio en memoria. En vez de eso, un Generador permitir que se + procesaran eventos SAX. (Esto se basaren las estructuras de + bajo nivel). Una de las mejores cosas sobre esto es que asno so + tendremos una manera m eficiente de leer el fichero, tambi + tendremos una magnica forma de utilizar hojas de cculo como + fuentes de datos XML. +

+

+ El Serializador HSSF, se separarm aíì en un marco genico + para la creaci de serializadores para otras plataformas y + en la implementaci especica del serializador HSSF. (Esto ya + es cierto en gran medida). Tambi adiremos soporte para + caracterticas ya soportadas por HSSF (estilos, fuentes, formatos + de texto). Esperamos adir soporte para fmulas durante este ciclo. +

+

+ Estamos empezando a expandir nuestro alcance de nuevo. Si pudimos + hacer todo esto para ficheros XLS, ¿ñuhay de ficheros Doc o PPT? + Pensamos que nuestro siguiente componente (HWPF) + deber seguir el mismo patr. Esperamos + que se nos una sangre nueva al equipo y que nos permita abordar + esto con mayor celeridad (en parte porque POIFS ya estterminado). + ¡Ðero a lo mejor lo que m necesitamos es a ti! +

+
+ + +
+ + Copyright (c) @year@ The Apache Software Foundation All rights reserved. +
+ Apache POI, POI, Apache, the Apache feather logo, and the Apache + POI project logo are trademarks of The Apache Software Foundation. + +
+ + + diff --git a/src/documentation/content/xdocs/trans/es/hssf/book.xml b/src/documentation/content/xdocs/trans/es/hssf/book.xml new file mode 100644 index 0000000000..0fe3c5f993 --- /dev/null +++ b/src/documentation/content/xdocs/trans/es/hssf/book.xml @@ -0,0 +1,45 @@ + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/src/documentation/content/xdocs/trans/es/hssf/diagram1.xml b/src/documentation/content/xdocs/trans/es/hssf/diagram1.xml new file mode 100644 index 0000000000..fb3d00c215 --- /dev/null +++ b/src/documentation/content/xdocs/trans/es/hssf/diagram1.xml @@ -0,0 +1,40 @@ + + + + + +
+ Jakarta POI - HSSF + Vista General + + + + +
+ + +
+ Diagrama de Clases del Usermodel por Matthew Young +

+ usermodel +

+
+ + diff --git a/src/documentation/content/xdocs/trans/es/hssf/diagrams.xml b/src/documentation/content/xdocs/trans/es/hssf/diagrams.xml new file mode 100644 index 0000000000..f32b4613ec --- /dev/null +++ b/src/documentation/content/xdocs/trans/es/hssf/diagrams.xml @@ -0,0 +1,50 @@ + + + + + +
+ Jakarta POI - HSSF + Vista General + + + + +
+ + +
Vista General +

+ Se espera usar esta sección para diagramas (UML/etc) que ayudan a + explicar HSSF. +

+
    +
  • + Diagrama de Clases del UserModel - + por Matthew Young (myoung at westernasset dot com) +
    • +
+

+ Tiene más? Agrega un nuevo "bug" al archivo de bugs con la + palabra [DOCUMENTATION] antes de la descripción y un link al file en algun webserver. Si no tiene su propio webserver, mandaselo por email a (acoliver at apache dot org) siempre y cuando el tamaño del archivo es menor a 5 Mb. Diagramas deben estar en algun formato compatible, por lo menos, con Linux y Windows. Se prefieren diagramas que se pueden cambiar o modificar pero entendemos que hay pocos programas para crear UML que están a buen precio. Y no, no TIENEN que ser UML... solo tienen que ser utiles. +

+
+ + diff --git a/src/documentation/content/xdocs/trans/es/hssf/formula.xml b/src/documentation/content/xdocs/trans/es/hssf/formula.xml new file mode 100644 index 0000000000..4de9b8dbe4 --- /dev/null +++ b/src/documentation/content/xdocs/trans/es/hssf/formula.xml @@ -0,0 +1,108 @@ + + + + + +
+ Jakarta POI - Formula Support + + + +
+ +
Introduction +

+ This document describes the current state of formula support in POI. + The information in this document applies to the 2.0-dev version of POI (i.e. CVS HEAD). + Since this area is a work in progress, this document will be updated with new features as and + when they are added. +

+ +
+
The basics +

+ In org.apache.poi.hssf.usermodel.HSSFCell + setCellFormula("formulaString") is used to add a formula to sheet and + getCellFormula() is used to retrieve the string representation of a formula. +

+

+ We aim to support the complete excel grammer for formulas. Thus, the string that you pass in + to the setCellFormula call should be what you expect to type into excel. Also, note + that you should NOT add a "=" to the front of the string. +

+
+
Supported Features +
    +
  • Cell References
    • +
  • String, integer and floating point literals
    • +
  • Area references
    • +
  • Relative or absolute references
    • +
  • Arithmetic Operators
    • +
  • Sheet Functions
    • +
+
+
Partially supported +
    +
  • + The formula parser now has the ability to parse formulas containing strings. However + formulas that return a string value are not yet supported. +
    • +
  • Formula tokens in Excel are stored in one of three possible classes : + Reference, Value and Array. Based on the location of a token, its class can change + in complicated and undocumented ways. While we have support for most cases, we + are not sure if we have covered all bases (since there is no documentation for this area.) + We would therefore like you to report any + occurence of #VALUE! in a cell upon opening a POI generated workbook in excel. (Check that + typing the formula into Excel directly gives a valid result.) +
    • + +
+
+
Not yet supported +
    +
  • Array formulas
    • +
  • Formulas with logical operations (IF)
    • +
  • Sheet References in formulas
    • +
  • Everything else :)
    • +
+
+ +
Internals +

+ Formulas in Excel are stored as sequences of tokens in Reverse Polish Notation order. The + open office XLS spec is the best + documentation you will find for the format. +

+ +

+ The tokens used by excel are modelled as individual *Ptg classes in the + org.apache.poi.hssf.record.formula package. +

+

+ The task of parsing a formula string into an array of RPN ordered tokens is done by the + org.apache.poi.hssf.record.formula.FormulaParser class. This class implements a hand + written recursive descent parser. +

+

Check out the javadocs for details. +

+
+ + + diff --git a/src/documentation/content/xdocs/trans/es/hssf/hacking-hssf.xml b/src/documentation/content/xdocs/trans/es/hssf/hacking-hssf.xml new file mode 100644 index 0000000000..d63411c21a --- /dev/null +++ b/src/documentation/content/xdocs/trans/es/hssf/hacking-hssf.xml @@ -0,0 +1,90 @@ + + + + + +
+ Jakarta POI - Hacking HSSF + + + + +
+ +
Where Can I Find Documentation on Feature X +

+ You might find the + 'Excel 97 Developer's Kit' (out of print, Microsoft Press, no + restrictive covenants, available on Amazon.com) helpful for + understanding the file format. +

+

+ Also useful is the open office XLS spec. We + are collaborating with the maintainer of the spec so if you think you can add something to their + document just send through your changes. +

+
+
Help, I Can't Find Feature X Documented Anywhere +
    +
  1. + Look at OpenOffice.org or Gnumeric sources if its implemented there. +
    2. +
  2. + Use org.apache.poi.hssf.dev.BiffViewer to view the structure of the + file. Experiment by adding one criteria entry at a time. See what it + does to the structure, infer behavior and structure from it. Using the + unix diff command (or get cygwin from www.cygwin.com for windows) you + can figure out a lot very quickly. Unimplemented records show up as + 'UNKNOWN' and prints a hex dump. +
    3. +
+
+
Low-level Record Generation +

+ Low level records can be time consuming to created. We created a record + generator to help generate some of the simpler tasks. +

+

+ We use XML + descriptors to generate the Java code (which sure beats the heck out of + the PERL scripts originally used ;-) for low level records. The + generator is kinda alpha-ish right now and could use some enhancement, + so you may find that to be about 1/2 of the work. Notice this is in + org.apache.poi.hssf.record.definitions. +

+
+
Important Notice +

One thing to note: If you are making a large code contribution we need to ensure + any participants in this process have never + signed a "Non Disclosure Agreement" with Microsoft, and have not + received any information covered by such an agreement. If they have + they'll not be able to participate in the POI project. For large contributions we + may ask you to sign an agreement.

+
+
What Can I Work On? +

Check our todo list or simply look for missing functionality. Start small + and work your way up.

+
+
What Else Should I Know? +

Make sure you read the contributing section + as it contains more generation information about contributing to POI in general.

+
+ + diff --git a/src/documentation/content/xdocs/trans/es/hssf/how-to.xml b/src/documentation/content/xdocs/trans/es/hssf/how-to.xml new file mode 100644 index 0000000000..43c594e4f6 --- /dev/null +++ b/src/documentation/content/xdocs/trans/es/hssf/how-to.xml @@ -0,0 +1,516 @@ + + + + + +
+ Jakarta POI - The New Halloween Document + + + + + +
+ +
How to use the HSSF prototype API + +
Capabilities +

This release of the how-to outlines functionality for the CVS HEAD. + Those looking for information on previous releases should + look in the documentation distributed with that release.

+

+ This release allows numeric and string cell values to be written to + or read from an XLS file as well as reading and writing dates. Also + in this release is row and column sizing, cell styling (bold, + italics, borders,etc), and support for built-in data formats. New + to this release is an event-based API for reading XLS files. + It differs greatly from the read/write API + and is intended for intermediate developers who need a smaller + memory footprint. It will also serve as the basis for the HSSF + Generator.

+
+
General Use +
User API +
Writing a new one + +

The high level API (package: org.apache.poi.hssf.usermodel) + is what most people should use. Usage is very simple. +

+

Workbooks are created by creating an instance of + org.apache.poi.hssf.usermodel.HSSFWorkbook. +

+

Sheets are created by calling createSheet() from an existing + instance of HSSFWorkbook, the created sheet is automatically added in + sequence to the workbook. Sheets do not in themselves have a sheet + name (the tab at the bottom); you set + the name associated with a sheet by calling + HSSFWorkbook.setSheetName(sheetindex,"SheetName",encoding). + The name may be in 8bit format (HSSFWorkbook.ENCODING_COMPRESSED_UNICODE) + or Unicode (HSSFWorkbook.ENCODING_UTF_16). Default encoding is 8bit per char. +

+

Rows are created by calling createRow(rowNumber) from an existing + instance of HSSFSheet. Only rows that have cell values should be + added to the sheet. To set the row's height, you just call + setRowHeight(height) on the row object. The height must be given in + twips, or 1/20th of a point. If you prefer, there is also a + setRowHeightInPoints method. +

+

Cells are created by calling createCell(column, type) from an + existing HSSFRow. Only cells that have values should be added to the + row. Cells should have their cell type set to either + HSSFCell.CELL_TYPE_NUMERIC or HSSFCell.CELL_TYPE_STRING depending on + whether they contain a numeric or textual value. Cells must also have + a value set. Set the value by calling setCellValue with either a + String or double as a parameter. Individual cells do not have a + width; you must call setColumnWidth(colindex, width) (use units of + 1/256th of a character) on the HSSFSheet object. (You can't do it on + an individual basis in the GUI either).

+

Cells are styled with HSSFCellStyle objects which in turn contain + a reference to an HSSFFont object. These are created via the + HSSFWorkbook object by calling createCellStyle() and createFont(). + Once you create the object you must set its parameters (colors, + borders, etc). To set a font for an HSSFCellStyle call + setFont(fontobj). +

+

Once you have generated your workbook, you can write it out by + calling write(outputStream) from your instance of Workbook, passing + it an OutputStream (for instance, a FileOutputStream or + ServletOutputStream). You must close the OutputStream yourself. HSSF + does not close it for you. +

+

Here is some example code (excerpted and adapted from + org.apache.poi.hssf.dev.HSSF test class):

+ +
+
Reading or modifying an existing file + +

Reading in a file is equally simple. To read in a file, create a +new instance of org.apache.poi.poifs.Filesystem, passing in an open InputStream, such as a FileInputStream +for your XLS, to the constructor. Construct a new instance of +org.apache.poi.hssf.usermodel.HSSFWorkbook passing the +Filesystem instance to the constructor. From there you have access to +all of the high level model objects through their assessor methods +(workbook.getSheet(sheetNum), sheet.getRow(rownum), etc). +

+

Modifying the file you have read in is simple. You retrieve the +object via an assessor method, remove it via a parent object's remove +method (sheet.removeRow(hssfrow)) and create objects just as you +would if creating a new xls. When you are done modifying cells just +call workbook.write(outputstream) just as you did above.

+

An example of this can be seen in +org.apache.poi.hssf.dev.HSSF.

+
+
+
Event API + +

The event API is brand new. It is intended for intermediate + developers who are willing to learn a little bit of the low level API + structures. Its relatively simple to use, but requires a basic + understanding of the parts of an Excel file (or willingness to + learn). The advantage provided is that you can read an XLS with a + relatively small memory footprint. +

+

To use this API you construct an instance of + org.apache.poi.hssf.eventmodel.HSSFRequest. Register a class you + create that supports the + org.apache.poi.hssf.eventmodel.HSSFListener interface using the + HSSFRequest.addListener(yourlistener, recordsid). The recordsid + should be a static reference number (such as BOFRecord.sid) contained + in the classes in org.apache.poi.hssf.record. The trick is you + have to know what these records are. Alternatively you can call + HSSFRequest.addListenerForAllRecords(mylistener). In order to learn + about these records you can either read all of the javadoc in the + org.apache.poi.hssf.record package or you can just hack up a + copy of org.apache.poi.hssf.dev.EFHSSF and adapt it to your + needs. TODO: better documentation on records.

+

Once you've registered your listeners in the HSSFRequest object + you can construct an instance of + org.apache.poi.poifs.filesystem.FileSystem (see POIFS howto) and + pass it your XLS file inputstream. You can either pass this, along + with the request you constructed, to an instance of HSSFEventFactory + via the HSSFEventFactory.processWorkbookEvents(request, Filesystem) + method, or you can get an instance of DocumentInputStream from + Filesystem.createDocumentInputStream("Workbook") and pass + it to HSSFEventFactory.processEvents(request, inputStream). Once you + make this call, the listeners that you constructed receive calls to + their processRecord(Record) methods with each Record they are + registered to listen for until the file has been completely read. +

+

A code excerpt from org.apache.poi.hssf.dev.EFHSSF (which is + in CVS or the source distribution) is reprinted below with excessive + comments:

+ +
+
Low Level APIs + +

The low level API is not much to look at. It consists of lots of +"Records" in the org.apache.poi.hssf.record.* package, +and set of helper classes in org.apache.poi.hssf.model.*. The +record classes are consistent with the low level binary structures +inside a BIFF8 file (which is embedded in a POIFS file system). You +probably need the book: "Microsoft Excel 97 Developer's Kit" +from Microsoft Press in order to understand how these fit together +(out of print but easily obtainable from Amazon's used books). In +order to gain a good understanding of how to use the low level APIs +should view the source in org.apache.poi.hssf.usermodel.* and +the classes in org.apache.poi.hssf.model.*. You should read the +documentation for the POIFS libraries as well.

+
+
HSSF Class/Test Application + +

The HSSF application is nothing more than a test for the high +level API (and indirectly the low level support). The main body of +its code is repeated above. To run it: +

+
    +
  • download the poi-alpha build and untar it (tar xvzf + tarball.tar.gz) +
    • +
  • set up your classpath as follows: + export HSSFDIR={wherever you put HSSF's jar files} +export LOG4JDIR={wherever you put LOG4J's jar files} +export CLASSPATH=$CLASSPATH:$HSSFDIR/hssf.jar:$HSSFDIR/poi-poifs.jar:$HSSFDIR/poi-util.jar:$LOG4JDIR/jog4j.jar +
  • type: + java org.apache.poi.hssf.dev.HSSF ~/myxls.xls write
    • +
+

+

This should generate a test sheet in your home directory called "myxls.xls".

+
    +
  • Type: + java org.apache.poi.hssf.dev.HSSF ~/input.xls output.xls +
    +
    +This is the read/write/modify test. It reads in the spreadsheet, modifies a cell, and writes it back out. +Failing this test is not necessarily a bad thing. If HSSF tries to modify a non-existant sheet then this will +most likely fail. No big deal.
    • +
+
+
Logging facility +

POI can dynamically select it's logging implementation. POI trys to + create a logger using the System property named "org.apache.poi.util.POILogger". + Out of the box this can be set to one of three values: +

+
    +
  • org.apache.poi.util.CommonsLogger
    • +
  • org.apache.poi.util.NullLogger
    • +
  • org.apache.poi.util.SystemOutLogger
    • +
+

+ If the property is not defined or points to an invalid classthen the NullLogger is used. +

+

+ Refer to the commons logging package level javadoc for more information concerning how to + configure commons logging. +

+
+
HSSF Developer's Tools + +

HSSF has a number of tools useful for developers to debug/develop +stuff using HSSF (and more generally XLS files). We've already +discussed the app for testing HSSF read/write/modify capabilities; +now we'll talk a bit about BiffViewer. Early on in the development of +HSSF, it was decided that knowing what was in a record, what was +wrong with it, etc. was virtually impossible with the available +tools. So we developed BiffViewer. You can find it at +org.apache.poi.hssf.dev.BiffViewer. It performs two basic +functions and a derivative. +

+

The first is "biffview". To do this you run it (assumes +you have everything setup in your classpath and that you know what +you're doing enough to be thinking about this) with an xls file as a +parameter. It will give you a listing of all understood records with +their data and a list of not-yet-understood records with no data +(because it doesn't know how to interpret them). This listing is +useful for several things. First, you can look at the values and SEE +what is wrong in quasi-English. Second, you can send the output to a +file and compare it. +

+

The second function is "big freakin dump", just pass a +file and a second argument matching "bfd" exactly. This +will just make a big hexdump of the file. +

+

Lastly, there is "mixed" mode which does the same as +regular biffview, only it includes hex dumps of certain records +intertwined. To use that just pass a file with a second argument +matching "on" exactly.

+

In the next release cycle we'll also have something called a +FormulaViewer. The class is already there, but its not very useful +yet. When it does something, we'll document it.

+ +
+
What's Next? + +

This release contains code that supports "internationalization" +or more accurately non-US/UK languages; however, it has not been +tested with the new API changes (please help us with this). We've +shifted focus a bit for this release in recognition of the +international support we've gotten. We're going to focus on western +European languages for our first beta. We're more than happy to +accept help in supporting non-Western European languages if someone +who knows what they're doing in this area is willing to pitch in! +(There is next to no documentation on what is necessary to support +such a move and its really hard to support a language when you don't even +know the alphabet).

+

This release of HSSF does not yet support Formulas. I've been +focusing on the requests I've gotten in. That being said, if we get +more user feedback on what is most useful first we'll aim for that. +As a general principal, HSSF's goal is to support HSSF-Serializer +(meaning an emphasis on write). We would like to hear from you! How +are you using HSSF/POIFS? How would you like to use it? What features +are most important first? +

+
+ +
+ +
+ + diff --git a/src/documentation/content/xdocs/trans/es/hssf/index.xml b/src/documentation/content/xdocs/trans/es/hssf/index.xml new file mode 100644 index 0000000000..95016a69f8 --- /dev/null +++ b/src/documentation/content/xdocs/trans/es/hssf/index.xml @@ -0,0 +1,65 @@ + + + + + +
+ Jakarta POI - HSSF + Overview + + + + +
+ + +
Overview + +

HSSF is the POI Project's pure Java implementation of the Excel '97(-2002) file format.

+

HSSF provides a way to read spreadsheets create, modify, read and write XLS spreadsheets + It provides: +

+
    +
  • low level structures for those with special needs
    • +
  • an eventmodel api for efficient read-only access
    • +
  • a full usermodel api for creating, reading and modifying XLS files
    • +
+

+ Truth be told there is probably a better way to generate your spreadsheet + generation (yet you'll still be using HSSF indirectly). At the time of + this writing we're in the process of moving the HSSF Serializer over to + the Apache Cocoon + Project. With Cocoon you can serialize any XML datasource (of + which might be a ESQL page outputting in SQL for instance) by simply + applying the stylesheet and designating the serializer. +

+

+ If you're merely reading spreadsheet data, then use the eventmodel api + in the org.apache.poi.hssf.eventmodel package. +

+

+ If you're modifying spreadsheet data then use the usermodel api. You + can also generate spreadsheets this way, but using Cocoon (which will do + it this way indirectly) is the best way...we promise. +

+ +
+ + diff --git a/src/documentation/content/xdocs/trans/es/hssf/limitations.xml b/src/documentation/content/xdocs/trans/es/hssf/limitations.xml new file mode 100644 index 0000000000..304add20d0 --- /dev/null +++ b/src/documentation/content/xdocs/trans/es/hssf/limitations.xml @@ -0,0 +1,73 @@ + + + + + +
+ Jakarta POI - Limitations + + + +
+ +
Version 1.5 limitations +

+ The intent of this document is to outline some of the known limitations of the + POI HSSF API's. It is not intended to be complete list of every bug or missing + feature of HSSF, rather it's purpose is to provide a broad feel for some of the + functionality that is missing or broken. +

+
    +
  • + Charts

    + You can not currently create charts. This is planned for the 2.0 release. You can + however create a chart in Excel, modify the chart data values using HSSF and write + a new spreadsheet out. This is possible because POI attempts to keep existing records + intact as far as possible.

    +
    • +
  • + Rich Text

    + HSSF does not support rich text cells. Rich text cells are + cells that have multiple fonts and styles in the once cell. Any attempt to read + a spreadsheet that has rich text cells will throw an exception. This feature may + be supported in the future but it is not currently planned. Patches are welcome.

    +
    • +
  • + Outlines

    + It is not yet possible to create outlines. Reading a spreadsheet with outlines + may work correctly but has not been tested. Write support for outlines may + be added in the future but it is not currently planned. Patches are welcome.

    +
    • +
  • + Macros

    + Macros can not be created. The are currently no plans to support macros. Reading + workbooks containing macros is supported but attempting to write those workbooks + will fail. This is because macros are stored as extra file sytems within the + compound document, and these are not currently kept when the file is rewritten.

    +
    • +
  • + Pivot Tables

    + Generating pivot tables is not supported. Reading spreadsheets containing pivot tables + has not been tested. +
    • +
+
+ + diff --git a/src/documentation/content/xdocs/trans/es/hssf/quick-guide.xml b/src/documentation/content/xdocs/trans/es/hssf/quick-guide.xml new file mode 100644 index 0000000000..9392ac3ad8 --- /dev/null +++ b/src/documentation/content/xdocs/trans/es/hssf/quick-guide.xml @@ -0,0 +1,422 @@ + + + + + +
+ Jakarta POI - Busy Developers' Guide to HSSF Features + + + +
+ +
Busy Developers' Guide to Features +

+ Want to use HSSF read and write spreadsheets in a hurry? This guide is for you. If you're after + more in-depth coverage of the HSSF user-API please consult the HOWTO + guide as it contains actual descriptions of how to use this stuff. +

+
Index of Features +
    +
  • How to create a new workbook
    • +
  • How to create a sheet
    • +
  • How to create cells
    • +
  • How to create date cells
    • +
  • Working with different types of cells
    • +
  • Aligning cells
    • +
  • Working with borders
    • +
  • Fills and color
    • +
  • Merging cells
    • +
  • Working with fonts
    • +
  • Reading and writing
    • +
  • Use newlines in cells.
    • +
  • Create user defined data formats.
    • +
  • Set print area for a sheet.
    • +
  • Set page numbers on the footer of a sheet.
    • +
+
+
Features + +
New Workbook + + HSSFWorkbook wb = new HSSFWorkbook(); + FileOutputStream fileOut = new FileOutputStream("workbook.xls"); + wb.write(fileOut); + fileOut.close(); + +
+ +
New Sheet + + HSSFWorkbook wb = new HSSFWorkbook(); + HSSFSheet sheet1 = wb.createSheet("new sheet"); + HSSFSheet sheet2 = wb.createSheet("second sheet"); + FileOutputStream fileOut = new FileOutputStream("workbook.xls"); + wb.write(fileOut); + fileOut.close(); + +
+ +
Creating Cells + + HSSFWorkbook wb = new HSSFWorkbook(); + HSSFSheet sheet = wb.createSheet("new sheet"); + + // Create a row and put some cells in it. Rows are 0 based. + HSSFRow row = sheet.createRow((short)0); + // Create a cell and put a value in it. + HSSFCell cell = row.createCell((short)0); + cell.setCellValue(1); + + // Or do it on one line. + row.createCell((short)1).setCellValue(1.2); + row.createCell((short)2).setCellValue("This is a string"); + row.createCell((short)3).setCellValue(true); + + // Write the output to a file + FileOutputStream fileOut = new FileOutputStream("workbook.xls"); + wb.write(fileOut); + fileOut.close(); + +
+ +
Creating Date Cells + + HSSFWorkbook wb = new HSSFWorkbook(); + HSSFSheet sheet = wb.createSheet("new sheet"); + + // Create a row and put some cells in it. Rows are 0 based. + HSSFRow row = sheet.createRow((short)0); + + // Create a cell and put a date value in it. The first cell is not styled + // as a date. + HSSFCell cell = row.createCell((short)0); + cell.setCellValue(new Date()); + + // we style the second cell as a date (and time). It is important to + // create a new cell style from the workbook otherwise you can end up + // modifying the built in style and effecting not only this cell but other cells. + HSSFCellStyle cellStyle = wb.createCellStyle(); + cellStyle.setDataFormat(HSSFDataFormat.getBuiltinFormat("m/d/yy h:mm")); + cell = row.createCell((short)1); + cell.setCellValue(new Date()); + cell.setCellStyle(cellStyle); + + // Write the output to a file + FileOutputStream fileOut = new FileOutputStream("workbook.xls"); + wb.write(fileOut); + fileOut.close(); + +
+ +
Working with different types of cells + + HSSFWorkbook wb = new HSSFWorkbook(); + HSSFSheet sheet = wb.createSheet("new sheet"); + HSSFRow row = sheet.createRow((short)2); + row.createCell((short) 0).setCellValue(1.1); + row.createCell((short) 1).setCellValue(new Date()); + row.createCell((short) 2).setCellValue("a string"); + row.createCell((short) 3).setCellValue(true); + row.createCell((short) 4).setCellType(HSSFCell.CELL_TYPE_ERROR); + + // Write the output to a file + FileOutputStream fileOut = new FileOutputStream("workbook.xls"); + wb.write(fileOut); + fileOut.close(); + +
+ +
Demonstrates various alignment options + + public static void main(String[] args) + throws IOException + { + HSSFWorkbook wb = new HSSFWorkbook(); + HSSFSheet sheet = wb.createSheet("new sheet"); + HSSFRow row = sheet.createRow((short) 2); + createCell(wb, row, (short) 0, HSSFCellStyle.ALIGN_CENTER); + createCell(wb, row, (short) 1, HSSFCellStyle.ALIGN_CENTER_SELECTION); + createCell(wb, row, (short) 2, HSSFCellStyle.ALIGN_FILL); + createCell(wb, row, (short) 3, HSSFCellStyle.ALIGN_GENERAL); + createCell(wb, row, (short) 4, HSSFCellStyle.ALIGN_JUSTIFY); + createCell(wb, row, (short) 5, HSSFCellStyle.ALIGN_LEFT); + createCell(wb, row, (short) 6, HSSFCellStyle.ALIGN_RIGHT); + + // Write the output to a file + FileOutputStream fileOut = new FileOutputStream("workbook.xls"); + wb.write(fileOut); + fileOut.close(); + + } + + /** + * Creates a cell and aligns it a certain way. + * + * @param wb the workbook + * @param row the row to create the cell in + * @param column the column number to create the cell in + * @param align the alignment for the cell. + */ + private static void createCell(HSSFWorkbook wb, HSSFRow row, short column, short align) + { + HSSFCell cell = row.createCell(column); + cell.setCellValue("Align It"); + HSSFCellStyle cellStyle = wb.createCellStyle(); + cellStyle.setAlignment(align); + cell.setCellStyle(cellStyle); + } + +
+ +
Working with borders + + HSSFWorkbook wb = new HSSFWorkbook(); + HSSFSheet sheet = wb.createSheet("new sheet"); + + // Create a row and put some cells in it. Rows are 0 based. + HSSFRow row = sheet.createRow((short) 1); + + // Create a cell and put a value in it. + HSSFCell cell = row.createCell((short) 1); + cell.setCellValue(4); + + // Style the cell with borders all around. + HSSFCellStyle style = wb.createCellStyle(); + style.setBorderBottom(HSSFCellStyle.BORDER_THIN); + style.setBottomBorderColor(HSSFColor.BLACK.index); + style.setBorderLeft(HSSFCellStyle.BORDER_THIN); + style.setLeftBorderColor(HSSFColor.GREEN.index); + style.setBorderRight(HSSFCellStyle.BORDER_THIN); + style.setRightBorderColor(HSSFColor.BLUE.index); + style.setBorderTop(HSSFCellStyle.BORDER_MEDIUM_DASHED); + style.setTopBorderColor(HSSFColor.BLACK.index); + cell.setCellStyle(style); + + // Write the output to a file + FileOutputStream fileOut = new FileOutputStream("workbook.xls"); + wb.write(fileOut); + fileOut.close(); + +
+ +
Fills and colors + + HSSFWorkbook wb = new HSSFWorkbook(); + HSSFSheet sheet = wb.createSheet("new sheet"); + + // Create a row and put some cells in it. Rows are 0 based. + HSSFRow row = sheet.createRow((short) 1); + + // 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); + cell = row.createCell((short) 2); + cell.setCellValue("X"); + cell.setCellStyle(style); + + // Write the output to a file + FileOutputStream fileOut = new FileOutputStream("workbook.xls"); + wb.write(fileOut); + fileOut.close(); + +
+ +
Merging cells + + HSSFWorkbook wb = new HSSFWorkbook(); + HSSFSheet sheet = wb.createSheet("new sheet"); + + HSSFRow row = sheet.createRow((short) 1); + HSSFCell cell = row.createCell((short) 1); + cell.setCellValue("This is a test of merging"); + + sheet.addMergedRegion(new Region(1,(short)1,1,(short)2)); + + // Write the output to a file + FileOutputStream fileOut = new FileOutputStream("workbook.xls"); + wb.write(fileOut); + fileOut.close(); + +
+ +
Working with fonts + + HSSFWorkbook wb = new HSSFWorkbook(); + HSSFSheet sheet = wb.createSheet("new sheet"); + + // Create a row and put some cells in it. Rows are 0 based. + HSSFRow row = sheet.createRow((short) 1); + + // Create a new font and alter it. + HSSFFont font = wb.createFont(); + font.setFontHeightInPoints((short)24); + font.setFontName("Courier New"); + font.setItalic(true); + font.setStrikeout(true); + + // Fonts are set into a style so create a new one to use. + HSSFCellStyle style = wb.createCellStyle(); + style.setFont(font); + + // Create a cell and put a value in it. + HSSFCell cell = row.createCell((short) 1); + cell.setCellValue("This is a test of fonts"); + cell.setCellStyle(style); + + // Write the output to a file + FileOutputStream fileOut = new FileOutputStream("workbook.xls"); + wb.write(fileOut); + fileOut.close(); + +
+ +
Reading and Rewriting Workbooks + + POIFSFileSystem fs = + new POIFSFileSystem(new FileInputStream("workbook.xls")); + HSSFWorkbook wb = new HSSFWorkbook(fs); + HSSFSheet sheet = wb.getSheetAt(0); + HSSFRow row = sheet.getRow(2); + HSSFCell cell = row.getCell((short)3); + if (cell == null) + cell = row.createCell((short)3); + cell.setCellType(HSSFCell.CELL_TYPE_STRING); + cell.setCellValue("a test"); + + // Write the output to a file + FileOutputStream fileOut = new FileOutputStream("workbook.xls"); + wb.write(fileOut); + fileOut.close(); + +
+ +
Using newlines in cells + + HSSFWorkbook wb = new HSSFWorkbook(); + HSSFSheet s = wb.createSheet(); + HSSFRow r = null; + HSSFCell c = null; + HSSFCellStyle cs = wb.createCellStyle(); + HSSFFont f = wb.createFont(); + HSSFFont f2 = wb.createFont(); + + cs = wb.createCellStyle(); + + cs.setFont( f2 ); + //Word Wrap MUST be turned on + cs.setWrapText( true ); + + r = s.createRow( (short) 2 ); + r.setHeight( (short) 0x349 ); + c = r.createCell( (short) 2 ); + c.setCellType( HSSFCell.CELL_TYPE_STRING ); + c.setCellValue( "Use \n with word wrap on to create a new line" ); + c.setCellStyle( cs ); + s.setColumnWidth( (short) 2, (short) ( ( 50 * 8 ) / ( (double) 1 / 20 ) ) ); + + FileOutputStream fileOut = new FileOutputStream( "workbook.xls" ); + wb.write( fileOut ); + fileOut.close(); +
+ +
Data Formats + + HSSFWorkbook wb = new HSSFWorkbook(); + HSSFSheet sheet = wb.createSheet("format sheet"); + HSSFCellStyle style; + HSSFDataFormat format = wb.createDataFormat(); + HSSFRow row; + HSSFCell cell; + short rowNum = 0; + short colNum = 0; + + row = sheet.createRow(rowNum++); + cell = row.createCell(colNum); + cell.setCellValue(11111.25); + style = wb.createCellStyle(); + style.setDataFormat(format.getFormat("0.0")); + cell.setCellStyle(style); + + row = sheet.createRow(rowNum++); + cell = row.createCell(colNum); + cell.setCellValue(11111.25); + style = wb.createCellStyle(); + style.setDataFormat(format.getFormat("#,##0.0000")); + cell.setCellStyle(style); + + FileOutputStream fileOut = new FileOutputStream("workbook.xls"); + wb.write(fileOut); + fileOut.close(); + +
+ +
Set Print Area to One Page + + HSSFWorkbook wb = new HSSFWorkbook(); + HSSFSheet sheet = wb.createSheet("format sheet"); + HSSFPrintSetup ps = sheet.getPrintSetup() + + sheet.setAutobreaks(true) + + ps.setFitHeight((short)1); + ps.setFitWidth((short)1); + + + // Create various cells and rows for spreadsheet. + + FileOutputStream fileOut = new FileOutputStream("workbook.xls"); + wb.write(fileOut); + fileOut.close(); + +
+ +
Set Page Numbers on Footer + + HSSFWorkbook wb = new HSSFWorkbook(); + HSSFSheet sheet = wb.createSheet("format sheet"); + HSSFFooter footer = sheet.getFooter() + + footer.setRight( "Page " + HSSFFooter.page() + " of " + HSSFFooter.numPages() ); + + + + // Create various cells and rows for spreadsheet. + + FileOutputStream fileOut = new FileOutputStream("workbook.xls"); + wb.write(fileOut); + fileOut.close(); + +
+ + +
+
+ + diff --git a/src/documentation/content/xdocs/trans/es/hssf/record-generator.xml b/src/documentation/content/xdocs/trans/es/hssf/record-generator.xml new file mode 100644 index 0000000000..b52d17eb25 --- /dev/null +++ b/src/documentation/content/xdocs/trans/es/hssf/record-generator.xml @@ -0,0 +1,132 @@ + + + + + +
+ Jakarta POI - Record Generator HOWTO + + + + +
+ +
How to Use the Record Generator + +
History +

+ The record generator was born from frustration with translating + the Excel records to Java classes. Doing this manually is a time + consuming process. It's also very easy to make mistakes. +

+

+ A utility was needed to take the defintition of what a + record looked like and do all the boring stuff. Thus the + record generator was born. +

+
+ +
Capabilities +

+ The record generator takes XML as input and produced the following + output: +

+
    +
  • A Java file capabile of decoding and encoding the record.
    • +
  • A test class with provides a fill-in-the-blanks implementation of a test case + for ensuring the record operates as designed.
    • +
+
+
Usage +

+ The record generator is invoked as an Ant target (generate-records). It goes + through looking for all files in src/records/defintitions ending with _record.xml. + It then creates two files; the Java record definition and the Java test case template. +

+

+ The records themselves have the following general layout: +

+ + The frame record indicates whether there is a border + around the displayed text of a chart. + Glen Stampoultzis (glens at apache.org) + + + + + + + + + + + + ]]> +

+ Currently the type can be of type int, float or string. The 'int' + type covers bytes, shorts and integers which is selected using a + size of 1, 2 or 4. An additional type called varword is used to + represent a array of word values where the first short is the length + of the array. The string type generation is only partially + implemented. If choosing string you must select a size of 'var'. +

+

+ The Java records are regenerated each time the record generator is + run, however the test stubs are only created if the test stub does + not already exist. What this means is that you may change test + stubs but not the generated records. +

+
+
How it Works +

+ The record generation works by taking an XML file and styling it + using XLST. Given that XSLT is a little limited in some ways it was + necessary to add a little Java code to the mix. +

+

+ See record.xsl, record_test.xsl, FieldIterator.java, + RecordUtil.java, RecordGenerator.java +

+
+
Limitations +

+ The record generator does not handle all possible record types and + is not ment to. Sometimes it's going to make more sense to generate + the records manually. The main point of this thing is to make the + easy stuff simple. +

+

+ Currently the record generator is optimized to create Excel records. + It could be adapted to create Word records with a little poking + around. +

+

+ Currently the the XSL file that generates the record calls out to + Java objects. This would have been better done as Javascript inside + the XSL file itself. The Java code for the record generation is + currently quite messy with minimal comments. +

+
+
+ + diff --git a/src/documentation/content/xdocs/trans/es/hssf/use-case.xml b/src/documentation/content/xdocs/trans/es/hssf/use-case.xml new file mode 100644 index 0000000000..76248bf939 --- /dev/null +++ b/src/documentation/content/xdocs/trans/es/hssf/use-case.xml @@ -0,0 +1,200 @@ + + + + + +
+ Jakarta POI - HSSF Use Cases + + + +
+ +
HSSF Use Cases +
Use Case 1: Read existing HSSF + +

Primary Actor: HSSF client

+

Scope: HSSF

+

Level: Summary

+

Stakeholders and Interests:

+
    +
  • HSSF client- wants to read content + of HSSF file
    • +
  • HSSF - understands HSSF file
    • +
  • POIFS - understands underlying POI + file system
    • +
+

Precondition: None

+

Minimal Guarantee: None

+

Main Success Guarantee:

+
    +
  1. HSSF client requests HSSF to read + a HSSF file, providing an InputStream + containing HSSF file in question.
    2. +
  2. HSSF requests POIFS to read the HSSF + file, passing the InputStream + object to POIFS (POIFS use case 1, read existing file system)
    3. +
  3. HSSF reads the "Workbook" + file (use case 4, read workbook entry)
    4. +
+

Extensions:

+

2a. Exceptions +thrown by POIFS will be passed on to the HSSF client.

+
+
Use Case 2: Write HSSF file + +

Primary Actor: HSSF client

+

Scope: HSSF

+

Level: Summary

+

Stakeholders and Interests:

+
    +
  • HSSF client- wants to write file + out.
    • +
  • HSSF - knows how to write file + out.
    • +
  • POIFS - knows how to write file + system out.
    • +
+

Precondition:

+
    +
  • File has been + read (use case 1, read existing HSSF file) and subsequently modified + or file has been created (use case 3, create HSSF file)
    • +
+

Minimal Guarantee: None

+

Main Success Guarantee:

+
    +
  1. HSSF client + provides an OutputStream to + write the file to.
    2. +
  2. HSSF writes + the "Workbook" to its associated POIFS file system (use case + 5, write workbook entry)
    3. +
  3. HSSF + requests POIFS to write its file system out, using the OutputStream + obtained from the HSSF client (POIFS use case 2, write file system).
    4. +
+

Extensions:

+

3a. Exceptions +from POIFS are passed to the HSSF client.

+ +
+
Use Case 3:Create HSSF file + +

Primary Actor: HSSF client

+

Scope: HSSF

+

+Level: Summary

+

Stakeholders and Interests:

+
    +
  • HSSF client- wants to create a new + file.
    • +
  • HSSF - knows how to create a new + file.
    • +
  • POIFS - knows how to creat a new + file system.
    • +
+

Precondition:

+

Minimal Guarantee: None

+

Main Success Guarantee:

+
    +
  1. HSSF requests + POIFS to create a new file system (POIFS use case 3, create new file + system)
    2. +
+

Extensions: +None

+ +
+
Use Case 4: Read workbook entry +

Primary Actor: HSSF

+

Scope: HSSF

+

+Level: Summary

+

Stakeholders and Interests:

+
    +
  • HSSF - knows how to read the + workbook entry
    • +
  • POIFS - knows how to manage the file + system.
    • +
+

Precondition:

+
    +
  • The file + system has been read (use case 1, read existing HSSF file) or has + been created and written to (use case 3, create HSSF file system; + use case 5, write workbook entry).
    • +
+

Minimal +Guarantee: None

+

Main Success Guarantee:

+
    +
  1. + HSSF requests POIFS for the "Workbook" file
    2. +
  2. POIFS returns + an InputStream for the file.
    3. +
  3. HSSF reads + from the InputStream provided by POIFS
    4. +
  4. HSSF closes + the InputStream provided by POIFS
    5. +
+

Extensions:

+

3a. Exceptions +thrown by POIFS will be passed on

+
+
Use Case 5: Write workbook entry + + +

Primary Actor: HSSF

+

Scope: HSSF

+

+Level: Summary

+

Stakeholders and Interests:

+
    +
  • HSSF - knows how to manage the + write the workbook entry.
    • +
  • POIFS - knows how to manage the file + system.
    • +
+

Precondition: +

+
    +
  • Either an existing HSSF file has + been read (use case 1, read existing HSSF file) or an HSSF file has + been created (use case 3, create HSSF file).
    • +
+

Minimal Guarantee: None

+

Main Success Guarantee:

+
    +
  1. HSSF + checks the POIFS file system directory for the "Workbook" + file (POIFS use case 8, read file system directory)
    2. +
  2. If "Workbook" is in the directory, HSSF requests POIFS to + replace it with the new workbook entry (POIFS use case 4, replace file + in file system). Otherwise, HSSF requests POIFS to write the new + workbook file, with the name "Workbook" (POIFS use case 6, + write new file to file system)
    3. +
+

Extensions:None

+
+ +
+ + diff --git a/src/documentation/content/xdocs/trans/es/index.xml b/src/documentation/content/xdocs/trans/es/index.xml new file mode 100644 index 0000000000..67db1c339c --- /dev/null +++ b/src/documentation/content/xdocs/trans/es/index.xml @@ -0,0 +1,132 @@ + + + + + +
+ Jakarta POI - API Java Para Acceder Ficheros con Formato Microsoft + + + + + + +
+ + +
Propósito +

+ El proyecto POI consiste en APIs para manipular varios formatos de ficheros + basados en el formato de Documento Compuesto OLE 2 de Microsoft, utilizando Java puro. En concreto, se pueden + leer y escribir ficheros MS Excel utilizando Java. Pronto se podrá leer y escribir + ficheros Word utilizando Java. POI es su solución Java Excel así como su solución Java Word. + En cualquier caso, tenemos un API completo para portar otros formatos de Documento Compuesto OLE 2 y todo aquel + que quiera participar será bienvenido. +

+

+ Entre los ficheros basados en el formato de Documento Compuesto OLE 2 de Microsoft se incluyen la mayor parte de los + ficheros de Microsoft Office tales como XLS y DOC así como formatos de fichero basados en el API de serialización MFC. +

+

+ Como regla general intentamos colaborar lo más posible con otros proyectos para proporcionar esta + funcionalidad. Algunos ejemplos: Cocoon para + el que hay serializadores para HSSF; + Open Office.org con quienes colaboramos en la documentación del + formato XLS; y Lucene para el que pronto tendremos intérpretes del + formato de fichero. Cuando es práctico, donamos componentes directamente a los proyectos para dotarles de capacidad-POI. +

+
¿Por qué/cuándo utilizar POI? +

+ Abordaremos esto a nivel de componente. POI se refiere al proyecto completo. +

+

+ Así que, ¿por qué debería utilizar POIFS o HSSF? +

+

+ Utilizarías POIFS si tuvieras un documento escrito en el Formato de Documento Compuesto OLE 2, probablemente escrito utilizando + MFC, que necesitaras leer en Java. Alternativamente, utilizarías POI para escribir en el Formato de Documento Compuesto OLE 2 + si necesitaras inter-operar con programas ejecutándose en la plataforma Windows. No nos estamos jactando cuando decimos que + ¡POIFS es la adaptación más completa y correcta de este formato de fichero hasta la fecha! +

+

+ Utilizarías HSSF si necesitaras leer o escribir un fichero Excel utilizando Java (XLS). También se pueden leer y modificar + hojas de cálculo utilizando este API, aunque ahora mismo la escritura está más madura. +

+
+
+ + +
Componentes a Día de Hoy +
Visión General +

Un pensamiento erróneo generalizado es que POI escribe ficheros Excel. POI es el nombre del proyecto. POI contiene varios + componentes, uno de los cuales, HSSF, escribe ficheros Excel. Siguen a continuación los componentes del + proyecto POI completo y un pequeño sumario de su propósito.

+
+
POIFS +

POIFS es la parte más vieja y más estable del proyecto. Es nuestra adaptación del Formato de Documento Compuesto + OLE 2 a Java puro. Soporta funcionalidad de lectura y escritura. Todos nuestros componentes se sirven de él por + definición. Por favor, vea la página del proyecto POIFS [EN] para más información.

+
+
HSSF +

HSSF es nuestra adaptación del formato de fichero de Microsoft Excel 97(-2002) (BIFF8) a Java puro. Soporta lectura y + escritura. Por favor, vea la página del proyecto HSSF [EN] para más información.

+
+
HWPF +

HWPF es nuestra adaptación del formato de fichero de Microsoft Word 97 a Java puro. Soporta lectura y escritura. + Por favor, vea la página del proyecto HWPF [EN] para más información. Este + componente está en la fase inicial de diseño. Ya puede leer y escribir ficheros sencillos. ¡Entra!

+
+
HPSF +

HPSF es nuestra adaptación del formato de conjunto de propiedades OLE 2 a java puro. + Los conjuntos de propiedades se utilizan mayoritariamente para almacenar las propiedades + de un documento (título, autor, fecha de la última modificación etc.), pero también pueden ser + utilizados para propósitos específicos de una aplicación. Actualmente HPSF soporta + sólo funcionalidad de lectura. Por favor, vea + la página del proyecto HPSF [EN] para más + información.

+
+ +
+ +
Contribuyendo +

+ Así que ¿te gustaría contribuir al proyecto? ¡Genial! Necesitamos gente entusiasta, que trabaje duro, que tenga talento para ayudarnos + con el proyecto en varias áreas. ¡La primera es petición de nuevas funciones y aviso de errores! La segunda es documentación - + estaremos a tu entera disposición si tienes alguna crítica o te gustaría contribuir o mejorar de alguna forma la documentación. + ¡Especialmente no nos vendría mal algo de ayuda en documentar el formato de fichero HSSF! ¡Por último, aunque no por ello + menos importante, nos vendría bien algunos programadores Java que mastiquen binario, para que le echen el diente a la convolución que caracteriza + los formatos de fichero de Microsoft y para que nos ayude a adaptar nuevos formatos a una plataforma Java superior! +

+

¡Así que si estás motivado, listo, y tienes tiempo, únete a las listas de correo y estaremos encantados de ayudarte a + empezar en el proyecto! +

+ + +
+ +
+ + Copyright (c) @year@ The Apache Software Foundation All rights reserved. +
+ Apache POI, POI, Apache, the Apache feather logo, and the Apache + POI project logo are trademarks of The Apache Software Foundation. + +
+ diff --git a/src/documentation/content/xdocs/trans/es/news.xml b/src/documentation/content/xdocs/trans/es/news.xml new file mode 100644 index 0000000000..6e333e8f35 --- /dev/null +++ b/src/documentation/content/xdocs/trans/es/news.xml @@ -0,0 +1,232 @@ + + + + + +
+ Jakarta POI - En las Noticias del mundo + + + + + +
+ + +
POI en los medios de comunicación +

+ Estos son artículos/etc. sobre POI publicados en la red. Si ves + alguna noticia sobre POI o algún sitio en el que se le menciona + de manera notable (no en tu propia página en la que pones la palabra + POI para que enlacemos contigo y en la que casualmente hay una foto + de tu mujer e hijos) entonces envía un parche a la lista. En general + dedicaremos el mismo tiempo así que no tengáis reparos en enviar + difamaciones coléricas así como comentarios favorables, técnicos y + objetivos. No mencionaremos mensajes realmente estúpidos (lo sentimos). +

+
+
Inglés +
    +
  • + Discusión sobre el uso de POI en AS/400s +
    • +
  • + Discusión de cuando casi tuvimos POI como el filtro para KOffice si asuntos de política y licencias no lo hubieran condenado al fracaso +
    • +
  • + Discusión Java en O'Reilly Network incluyendo discusión sobre POI - O'Reilly.net +
    • +
  • + Poor Obfuscation Implementation (Implementación Pobre de Ofuscación). - Blog de David M. Johnson +
    • +
  • + + Descarga POI 1.5-dev-rc2 - JSurfer +
    • + +
  • + Google dice que somos los más importantes en nuestra categoría +
    • +
  • + It's POI-fect - Tony Sintes, Javaworld +
    • +
  • + + Nicola anuncia código de serialización POI + - Matthew Langham's Radio Weblog +
    • +
  • + + Descarga Jakarta POI 1.4583 - JavaLobby +
    • +
  • + + El proyecto POI se mueve a Jakarta (OLE 2 CDF/Excel/Word en + java puro) - JavaLobby +
    • +
  • + + Listado de bibliotecas Java para leer y escribir ficheros de imágenes y documentos + - Página de Marco Schmidt (normalmente no anunciaríamos + la página personal de nadie, pero es un listado extensivo de información + que incluye "alternativas a POI" (para aquellos que son muy ricos). ¡Pero, qué + l3ch3s, creo que voy a marcar esta página para mí puesto que tiene enlaces a + direcciones que en conjunto contienen o enlazan con todo el conocimiento de la humanidad!) +
    • +
  • + + Experiencias de un Operador (Måns af Klercker) + - radio.weblogs.com +
    • +
  • + + DATACONV - Herramientas de Conversión de Datos: Office + DATACONV +
    • +
  • + + Página del Desarrollador de Chicago + +
    • +
  • + + POI/Proyecto de Serialización de POI + - Tío, sabes que estás en lo alto cuando le gustas a + O'Reilly. ;-) +
    • +
  • + + Noticias en la Red + - Java World +
    • + +
+
+
Nederlandstalige (Holandés) +
    +
  • + + Een Excel-werkboek maken vanuit Java - Lieven Smits + +
    • +
+
+
Deutsch (Alemán) +
    +
  • Apache POI verffentlicht - entwicker.com +
    • +
  • + + Apache Jakarta-Projekt bringt Word und Excel in die Java-Welt - jsp-develop.de (for the misguided who use JSP ;-) ) +
    • +
  • + + Neues Apache-Projekt bringt Word- und Excel nach Java + - entwickler.com +
    • +
+
+
Español (Spanish) +
    +
  • + + OLE2 desde Java nativo + - javaHispano +
    • +
  • + Discusión sobre Excel y Java incluyendo POI de los foros de Wrox +
    • +
+
+
Francais (Francés) +
    +
  • + + Excel/OLE accessibles + - Da Linux French Page +
    • +
  • + Discusión sobre POI en francés +
    • +
+
+
Nihongo (Japonés) +
    +
  • + 100% PureJava... - Dr. Panda Portal +
    • +
  • + + What's new with java? + - gimlay.org +
    • +
  • Java?Excel????? - appears to show how to use Japanese with POI
    • +
  • Various discussion in Japanese including on POI
    • +
  • Japanese resources on Jakarta projects including POI
    • +
  • Kishida's site -- Weekly Forte Lectures -- includes a snip about POI and Japanese.
    • +
+
+
Russkii Yazyk (Ruso) +
    +
  • + + Probably a translation of the Javalobby announcement of 1.5-final + -- Computer News (What's New) +
    • +
+
+
Hangul (Coreano) +
    +
  • + Various discussion in Korean about Excel output/APIs including POI +
    • +
+
+
Ni idea +

+ ¡Si entiendes alguno de estos idiomas, envía un correo a la lista + diciéndonos en qué idioma está escrito y lo pondremos donde corresponda! +

+
    +
  • + + Si tuviera que adivinar, diría que es Tailandés, pero a lo mejor + alguno de vosotros lo sabe con seguridad. - javacentrix.com +
    • +
+
+ +
+ + Copyright (c) @year@ The Apache Software Foundation All rights reserved. +
+ Apache POI, POI, Apache, the Apache feather logo, and the Apache + POI project logo are trademarks of The Apache Software Foundation. + +
+ diff --git a/src/documentation/content/xdocs/trans/es/overview.xml b/src/documentation/content/xdocs/trans/es/overview.xml new file mode 100644 index 0000000000..fe280a05ba --- /dev/null +++ b/src/documentation/content/xdocs/trans/es/overview.xml @@ -0,0 +1,91 @@ + + + + + +
+ Descripción General + + + + +
+ + +
¿Qué es? +

El proyecto POI es el proyecto principal para el desarrollo de adaptaciones (ports) + en Java puro de los formatos de fichero basados en el Formato de Documento Compuesto OLE 2 + de Microsoft. El Formato de Documento Compuesto OLE 2 lo utilizan los Documentos Office de + Microsoft, así como por los programas que utilizan conjuntos de propiedades MFC para serializar + sus objetos de tipo documento. +

+
+
Sub-Proyectos +

+ Los siguientes son adaptaciones, paquetes o componentes contenidos en el proyecto POI. +

+
POIFS +

+ POIFS [EN] es el conjunto de APIs (Interfaces de Aplicación) + para la lectura y escritura del Formato de Documento Compuesto OLE 2 utilizando (únicamente) Java. +

+
+ +
HSSF +

+ HSSF [EN] es el conjunto de APIs para la lectura y + escritura de hojas de cálculo de Microsoft Excel 97(-XP) utilizando (únicamente) Java. +

+
+ +
HWPF +

+ HWPF [EN] es el conjunto de APIs para la lectura y + escritura de documentos Word 97(-XP) de Microsoft utilizando (únicamente) Java. +

+
+ +
HPSF +

+ HPSF [EN] es el conjunto de APIs para la lectura + de conjuntos de propiedades utilizando (únicamente) Java. +

+
+ +
Utilidades-POI (POI-Utils) +

+ POI-Utils [EN] son artefactos de propósito + general surgidos en el desarrollo de POI que no han sido implementados en ningún otro sitio. + Siempre buscamos donarlos y mantenerlos como parte de una biblioteca general utilizada en + algún otro proyecto. Estas son cosas que necesitamos para completar nuestra misión pero que + generalmente estan fuera de ella. +

+
+
+ +
+ + Copyright (c) @year@ The POI Project All rights reserved. +
+ Apache POI, POI, Apache, the Apache feather logo, and the Apache + POI project logo are trademarks of The Apache Software Foundation. + +
+ diff --git a/src/documentation/content/xdocs/trans/es/patches.xml b/src/documentation/content/xdocs/trans/es/patches.xml new file mode 100644 index 0000000000..acc1ae011b --- /dev/null +++ b/src/documentation/content/xdocs/trans/es/patches.xml @@ -0,0 +1,90 @@ + + + + + +
+ Jakarta POI - Patch Queue + + + + +
+ +
+ Introduction +

+ This is an + informal list - in chronological order - + of some of the noteworthy patches that have been posted + to the + developers 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! +

+

+ Reviewers wanted! - 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. +

+

+ Before submitting a patch, please read the page on + Third-Party + Contributions. The preferred submission method for patches is: +

+
    +
  • Post to POI developers list
    • +
  • Describe the patch, the reason for it and (if necessary) why this is important.
    • +
  • Generate the patch in + diff -u format from CVS +
    • +
  • Also generate a documentation patch or new file, if this is something that should be documented. +
    • +
  • Post as an attachment rather than inline (unless it is trivially small).
    • +
+

Following the above guidelines will facilitate your patch being reviewed + and applied efficiently.

+
+
+ Patch Queue +

+ [Under Construction] Archive links will be added later. + Please do not bother the patch submitters/authors without first reading the + relevant post(s) in the + mailing list archives. +

+

Vapourware will not be listed.

+ + + + + + + + +
idSummaryReviewerResolutionStatus
+

See also additional list of patches to be added in + To Do. +

+
+ + diff --git a/src/documentation/content/xdocs/trans/es/todo.xml b/src/documentation/content/xdocs/trans/es/todo.xml new file mode 100644 index 0000000000..572ced3b95 --- /dev/null +++ b/src/documentation/content/xdocs/trans/es/todo.xml @@ -0,0 +1,70 @@ + + + + + +Jakarta POI - Tareas Pendientes para POI + + + + + + + + + + + + + + + Terminar HWPF + + + Terminar Gráficas (Charts) + + + Evaluar y arreglar el código de rendimiento en HEAD. + + + + + + + Implementar más tipos de registros. + + + Añadir más comprobaciones evidentes (para cuando los usuarios del API + hagan cosas que "no pueden" hacer). Esto conllevará la exploración de varios + límites superiores en las cosas que puede manejar Excel. + + + Añadir soporte para gráficos embebidos y otros objetos. + + + Crear un nuevo objeto adaptador para manejar registros + MulBlank, MulRk, Rk. + + + Mejorar las fórmulas (Fórmulas Compartidas, PTGs Desconocidos). + + + + diff --git a/src/documentation/content/xdocs/trans/es/who.xml b/src/documentation/content/xdocs/trans/es/who.xml new file mode 100644 index 0000000000..fb0c17b1d6 --- /dev/null +++ b/src/documentation/content/xdocs/trans/es/who.xml @@ -0,0 +1,92 @@ + + + + + +
+ Jakarta POI - Quiénes somos + + + +
+ + + +
Jakarta POI - Quiénes somos +

+ El Proyecto POI opera mediante una meritocracia: cuanto más haga uno, + mas responsabilidad tendrá. Esta página lista toda la gente que ha recorrido + el último kilómetro y son Committers. Si quieres involucrarte, + el primer paso sería unirse a las listas de correo. +

+ +

+ Pedimos que por favor no nos envíen correos electrónicos privados pidiendo soporte. + Somos voluntarios no-pagados que ayudan con el proyecto pero que no tenemos + necesariamente el tiempo o las energías para ayudar a la gente a nivel individual. + En su lugar, hemos montado listas de correo que a menudo contienen cientos de + individuos que ayudarán a contestar peticiones detalladas de ayuda. El beneficio de + utilizar listas de correo sobre la comunicación privada reside en que se trata de un + recurso compartido donde otros pueden aprender de errores frecuentes y donde podamos + crecer juntos como una comunidad. +

+ + + + + + + + +
Emeritus Committers +
    +
  • Nicola Ken Barozzi (barozzi at nicolaken dot com)
    • +
+
+ +
Committers +
    +
  • Andrew C. Oliver (acoliver at apache dot org)
    • +
  • Marc Johnson (mjohnson at apache dot org)
    • +
  • Glen Stampoultzis (glens at apache.org)
    • +
  • Rainer Klute (klute at apache dot org)
    • +
  • Ryan Ackley (sackley at apache dot org)
    • +
  • Avik Sengupta (avik at apache dot org)
    • +
  • Shawn Laubach (slaubach at apache dot org)
    • +
  • Danny Mui (dmui at apache dot org)
    • +
  • Jason Height (jheight at apache dot org)
    • +
  • Tetsuya Kitahata (tetsuya at apache dot org)
    • +
+
+
Desarrolladores +
    +
  • Todos los Committers, por supuesto
    • +
  • Agustín Martín (agusmba at terra dot es)
    • +
+
+
Translators +
    +
  • Agustín Martín (agusmba at terra dot es)
    • +
+
+
+ + + diff --git a/src/documentation/content/xdocs/trans/guidelines.xml b/src/documentation/content/xdocs/trans/guidelines.xml new file mode 100644 index 0000000000..3f822733e9 --- /dev/null +++ b/src/documentation/content/xdocs/trans/guidelines.xml @@ -0,0 +1,148 @@ + + + + + +
+ Welcome to POI -- POI Website Translation Guildeline + + + + +
+ + +
Purpose +

This document hopes to serve as a general introduction and helpful set of + guidelines for translating POI documentation into other languages. We hope + to capture both general information here (such as "how do I test my changes") + as well as language specific guidelines and translation conventions.

+
+
Introduction +

+ POI's XML based documentation is built along side the sources. To build poi's documentation + you run "./build.sh docs" (UNIX/cygwin) or "build docs" (Windows) from the jakarta-poi + directory. This will put the documentation under the build/docs directory, you can navigate + there using your browser generally by typing in the path name or File -> Open new web location + (or some similar wording) + and browsing to the "index.html" file. You may also want to run "./build.sh clean docs" or + "build clean docs" so that all documentation previously built is erased before running the build. + The words "clean" and "docs" are called "targets", from here on out we will refer to them as + "targets" in which case you may assume you type "./build.sh" or "build" before them in order to + execute them. +

+

+ To generate all of the documentation such as it would appear on the + POI Website you can execute the "site" target (optionally + preceeded by the "clean" target. See "How to Build" page for more detail (Now, POI build uses Forrest). +

+

+ The source for POI's XML documentation is in src/documentation/content/xdocs. To edit one of these files you can use + a standard text editor. Translated documentation is under src/documentation/content/xdocs/trans/xx, where xx is a + two to three letter country code, in general this should match the internet domain suffix of the country where + that language generally evolved or just be generally recognizable and unique. The directory structure under + build/site/trans/xx should match the structure of build/site (the English edition) minus the + trans directory. +

+

+ The translated documentation should match the content and meaning of the "master" or English documentation. + All documentation should originate in English (this is for simplicity). While documentation written in other + languages is certainly welcome, it must first be translated (perhaps by posting it to the mail list and + requesting it be translated) into English and applied to the master before being applied to a translation. +

+

+ We prefer you donate translations directly to the Apache POI + project rather than hosting them offsite. We will make every effort to accomidate you as we greatly appreciate your + efforts. However, we understand that sites located within a country are the fastest and most searchable. Therefore, + we recommend and welcome folks mirroring the POI site and making the translated page the home page. You can do this + either via an HTML copy with some appropriate software + or the preferred method of executing the POI build directly. You can contact us via the mail list for both push and + pull options. The same scripts which regenerate the POI website every 2 hours, should work for others. These are not + yet in CVS as they are nasty dirty shell scripts ;-). If you mirror us, tell us so we can link you. (This will help google + associate you strongly with the project) +

+

+ Submitting translations is simple, you follow the same + instructions as you would for submitting a code patch. + Remeber to always generate patchs in diff -u format preserving the context relative to the jakarta-poi directory. Also remember + to submit any new files in a directory preserving archive format. Never post these to the list, always use + Bugzilla + and create attachments per the above linked instructions. +

+
+
Credits +

+ Some people feel uncomfortable putting themselves in the <authors> tags at the top of the documentation as they feel that + translation does not give them the right to claim authorship. Please don't feel this way, please add yourself to the authors + tags. It can be assumed that authors on the master documentation are all content creators and any additional authors listed + on the translation that are not on the master document are translators of the documentation. You authored the xx language + version of the document and should freely add yourself there. Additionally, please supply a patch to the + Who We Are page noting you as a developer once you've submitted a few translation patches. You deserve + credit and it helps the project to give you credit. Remember documentation is on par with code contribution. +

+
+
Starting a new translation +

+ To start a translation for a language not already in existance you must create a directory under src/documentation/content/xdocs/trans with a + two or three letter designation of the country where the language originated. (For example es = Spanish, de = German) + Copy the book.xml and index.xml file from src/documentation/content/xdocs directory into the src/documentation/content/xdocs/trans/xx directory. + Change all paths in the book.xml and index.xml to match the relative location of the English version. For example if there is a + link in index.html that references ./poifs/index.html, you'd change that to ../../poifs/index.html (up 2 directories from trans/xx). + Create a link from the book.xml file in the src/documentation/content/trans directory (this is necessary or the build will ignore your + documentation) similar to the other languages. + Run the clean target followed by the docs target. If the build is successful, congratulations! If it fails, you probably got one of + the relative paths incorrect! Go fix it (the first error message generally contains the most useful information). If you need help + post to the poi-dev list and ask for it (send the output from the build). +

+

+ So now you have a directory with a copy of the index from the master documentation...so what? Well now translate book.xml and index.xml. + Try to build again. It probably won't work. Why? The encoding. At the top of every file there is an encoding="UTF-8" (in general). + This encoding will work for many Western European languages, but not for others, or will require some nasty escape sequencing. This is + where trial and error + guess work come in. This Table of encodings may help. There is a + catch. Your encoding should work on a Linux system under Java 1.3.1 and of course with the build in general. If in doubt, ask. + (This is a practical consideration as thats the setup of the machine currently running the nightly/site builds.) +

+
+
Need help? +

+ Andy Oliver is the cofounder of the POI project and one of its most active documentation contributers. Well, Andy used to think he + spoke very clearly until he traveled abroad and discovered his speech was composed almost entirely of coloquialisms. This can make some + of the POI documentation difficult to translate, if in doubt...ask. Its also appropriate to eliminate these from the master documentation + where it makes it clearer. +

+
+
Translation Conventions +

+ In addition to the above practical guidelines we hope to come up with a set of translation guidelines here (or linked from here) for + general use as well as language specific translation guidelines and conventions. We assume that the POI translators will document + them here as they develop. +

+
+ +
+ + Copyright (c) @year@ The Apache Software Foundation All rights reserved. +
+ Apache POI, POI, Apache, the Apache feather logo, and the Apache + POI project logo are trademarks of The Apache Software Foundation. + +
+ diff --git a/src/documentation/content/xdocs/trans/index.xml b/src/documentation/content/xdocs/trans/index.xml new file mode 100644 index 0000000000..7dc9a2f1b7 --- /dev/null +++ b/src/documentation/content/xdocs/trans/index.xml @@ -0,0 +1,68 @@ + + + + + +
+ The Apache POI Documentation Translations + + + +
+ + +
Introduction +

+ The POI project has always had a very international following. In fact even today POI is + more popular in Europe than in the US where the original founders reside. Today POI is + developed by people from all over the world including India, Austrailia, Japan, and Russia. + We recognize and welcome our geographically and culturally diverse users and contributors and + wish to accomidate you as best as we can. +

+

+ Documentation has always been a cornerstone to POI's success. No matter how fluent one is in + a second language, it is always easier to comprehend concepts explained in one's native language, + therefore, we encourage volunteers to come and help us translate the documentation into other + languages. Below is a list of the translations that are currently in progress and their status. +

+
+
Languages + + + + + + + + + + +
xxLanguageStatusOn/OffsiteLink
deGermanJust beginning (help!)Onlink
esSpanishIndex page, some auxiliary pages translatedOnlink
jpJapaneseComplete XML translations and built with FORRESTOfflink
krKoreanConducted by Jakarta-Seoul-Project.Offlink
+
+ +
+ + Copyright (c) @year@ The Apache Software Foundation All rights reserved. +
+ Apache POI, POI, Apache, the Apache feather logo, and the Apache + POI project logo are trademarks of The Apache Software Foundation. + +
+ diff --git a/src/documentation/content/xdocs/utils/book.xml b/src/documentation/content/xdocs/utils/book.xml new file mode 100644 index 0000000000..76f305c53c --- /dev/null +++ b/src/documentation/content/xdocs/utils/book.xml @@ -0,0 +1,37 @@ + + + + + + + + + + + + + + + + + + diff --git a/src/documentation/content/xdocs/utils/index.xml b/src/documentation/content/xdocs/utils/index.xml new file mode 100644 index 0000000000..749b1fdb0c --- /dev/null +++ b/src/documentation/content/xdocs/utils/index.xml @@ -0,0 +1,52 @@ + + + + + +
+ POI Utils + Overview + + + +
+ + +
Overview + +

The POI Utils are classes we're looking to donate elsewhere and include. + These are usually classes that while are required for our mission, + are somehow outside of it. General utilities that could be used in + any project are what we would normally put here. If you see one, and you + think "gee that would be great as part of X project" then let us know. + While we wish to put these in their rightful place, we also don't want to + include a 40mb jar file just to process text strings, so that will + be a consideraton. +

+

+ Currently, we're looking into which subprojects in the Jakarta Commons project + to donate these too. The "POI Utils" package won't go away, as there may + be later classes. The idea is that "go ahead and add it, we'll merge it or + find an alternative later, just keep pounding out that poi!" +

+ +
+ + diff --git a/src/documentation/content/xdocs/utils/logging.xml b/src/documentation/content/xdocs/utils/logging.xml new file mode 100644 index 0000000000..69b80ae834 --- /dev/null +++ b/src/documentation/content/xdocs/utils/logging.xml @@ -0,0 +1,102 @@ + + + + + +
+ POI Utils + Overview + + + + +
+ + +
Logging + +

+ Logging in POI is used only as a debugging mechanism, not a normal runtime + logging system. Logging is ONLY for autopsie type debugging, and should + NEVER be enabled on a production system. Enabling logging will reduce + performance by at least a factor of 100. If you are not developing + POI or trying to debug why POI isn't reading a file correctly, then DO + NOT enable logging. You've been warned. +

+ +

+ Hence, we need to be able to easily disable it entirely and make POI not dependent + on any logging package. +

+ + + POI is not dependent on commons-logging for running, but not for compiling. + + +
Logging Overview +

+ Every class uses a POILogger to log, and gets it using a static method + of the POILogFactory . +

+

+ The POILogFactory uses the NullLogger by default; + it can be instructed to use any other POILogger implementation + by setting the system property org.apache.poi.util.POILogger. +

+ java -Dorg.apache.poi.util.POILogger=the.package.of.MyPoiLoggerImpl ProgramThatUsesPoi + + Still needs testing. + +
+ +
POILogFactory +

+ Each class in POI can get its POILogger by calling a static method + of the POILogFactory . +

+
+ +
POILogger +

+ Each class in POI can log using a POILogger, which is an abstract class. + We decided to make our own logging facade because:

+
    +
  1. we need to log many values and we put many methods in this class to facilitate the + programmer, without having him write string concatenations;
    2. +
  2. we need to be able to use POI without any logger package present.
    3. +
+

There are three implementations available, and you can roll out your own, just + extend org.apache.poi.util.POILogger. +

+
NullLogger +

Discards every logging request.

+
+
SystemOutLogger +

Sends every logging request to System.out.

+
+
CommonsLogger +

Sends every logging request to the Commons Logging package. This can use JDK1.4 logging, + log4j, logkit, and is an actively maintained Jakarta Project.

+
+ +
+
+ + diff --git a/src/documentation/content/xdocs/who.xml b/src/documentation/content/xdocs/who.xml new file mode 100644 index 0000000000..2030a40b03 --- /dev/null +++ b/src/documentation/content/xdocs/who.xml @@ -0,0 +1,103 @@ + + + + + +
+ Apache POI - Who We Are + + + +
+ + + +
Apache POI - Who we are +

+ The Apache POI Project operates on a meritocracy: the more you do, the more + responsibility you will obtain. This page lists all of the people who have + gone the extra mile and are Committers. If you would like to get involved, + the first step is to join the mailing lists. +

+ +

+ We ask that you please do not send us emails privately asking for support. + We are non-paid volunteers who help out with the project and we do not + necessarily have the time or energy to help people on an individual basis. + The mailing lists have many individuals + who will help answer detailed requests for help. The benefit of + using mailing lists over private communication is that they are a shared + resource where others can also learn from common questions. +

+

+ POI Developers count on feedback from the mailing lists. Many developers do take + an active role on the lists. +

+ + + + + + + + +
Project Chair +
    +
  • Yegor Kozlov (yegor at apache dot org)
    • +
+
+
Committers +
    + +
  • Nick Burch (nick at apache dot org)
    • +
  • Amol S Deshmukh (amol at apache dot org)
    • +
  • David Fisher (wave at apache dot org)
    • +
  • Jason Height (jheight at apache dot org)
    • +
  • Marc Johnson (mjohnson at apache dot org)
    • +
  • Rainer Klute (klute at apache dot org)
    • +
  • Yegor Kozlov (yegor at apache dot org)
    • +
  • Shawn Laubach (slaubach at apache dot org)
    • +
  • Josh Micich (josh at apache dot org)
    • +
  • Danny Mui (dmui at apache dot org)
    • +
  • Avik Sengupta (avik at apache dot org)
    • +
  • Dominik Stadler (centic at apache dot org)
    • +
  • Glen Stampoultzis (glens at apache.org)
    • +
  • Jon Svede (jsvede at apache dot org)
    • +
  • Maxim Valyanskiy (maxcom at apache dot org)
    • +
  • Sergey Vladimirov (sergey at apache dot org)
    • +
+
+
Translators +
    +
  • (Please add your name here!!)
    • +
+
+
Emeritus Committers +
    +
  • Andrew C. Oliver (acoliver at gmail dot com)
    • +
  • Nicola Ken Barozzi (barozzi at nicolaken dot com)
    • +
  • Ryan Ackley (sackley at apache dot org)
    • +
  • Tetsuya Kitahata (ai at spa dot nifty dot com)
    • +
+
+
+ + + diff --git a/src/documentation/release-guide.txt b/src/documentation/release-guide.txt new file mode 100644 index 0000000000..683a35907d --- /dev/null +++ b/src/documentation/release-guide.txt @@ -0,0 +1,238 @@ +# 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 Guide + ============================== + + +(I) Prerequisites + + 1. You should read the Apache Release FAQ + 2a. You must have shell access to people.apache.org; and you should + have key-based authentication set up + (e.g. how to. + 2b. You must be a member of the committee group + 3. Release manager must have his public key appended to the KEYS file checked in to SVN and the key published on one of the public key servers. + More info can be found here: http://www.apache.org/dev/release-signing.html + 4. You must have JDK 1.5 + 5. You must have the following utilities installed on your local machine and available in your path: + * ssh + * gnupg + * openssl + For Windows users, install Cygwin and make sure you have the above utilities + 6a. The POI build system requires two components to perform a build + * Ant + * Forrest. + POI 3.0.2 and 3.1 were built using Ant 1.6.2 and Forrest 0.5 + Currently, Forrest needs to be 0.5.1, Ant 1.7+ should be fine + + 6b. To deploy with Maven, you should have the latest stable Maven 2.x. + POI 3.10-beta2 was deployed with Maven 2.2.1. + + 7. Before building, you should run the "rat-check" build task, which + uses Apache Rat + to check the source tree for files lacking license headers. Files + without headers should be either fixed, or added to the exlude list + + 8. Check file permissions are correct in SVN. + There can be files in the SVN tree marked executable (have the + svn:executable property set), but which should not be. Checking them + out will cause the executable bit to be set for them on filesystems + which support it. The flag can be removed in batch using + +$ svn pd 'svn:executable' $(find -name .svn -prune -or -type f ! -name \*.sh \ + -print0 | xargs -0 svn pg 'svn:executable' | cut -d ' ' -f 1) + + +(II) Making release artefacts + 1. Update version id in build.xml +{code:xml} + +{code} + + 2. Update the date in src/documentation/content/xdocs/status.xml with + the expected release date, and create a commented out entry for the + next release. (Must be commented out, as there are no actions + for it yet) + + 3. Pin the documentation explicitly to the current version, rather + than trunk. Run "svn up" to get the current version number, then + edit the svn:externals property on src and add to the definition, eg + + documentation -r1496657 https://svn.apache.org/repos/asf/poi/site/src/documentation + + 4. Tag current version. Include the current revision number in the comment + +{code} +$ TAG=REL_3_8_FINAL +$ TAG=REL_3_12_ALPHA5 +$ svn cp https://svn.apache.org/repos/asf/poi/trunk \ +https://svn.apache.org/repos/asf/poi/tags/$TAG \ +-m "tag r649911 as 3.1-beta1" +{code} + +where $TAG is the release tag, for example, REL_3_1_BETA1 + + 5. On trunk, update "version.id" to be the next version in status.xml, + and remove the version pinning on the documentation external definition. + + 6. Checkout the tagged version +{code} +cd tags +svn checkout https://svn.apache.org/repos/asf/poi/tags/$TAG +{code} + + 7. Merge (if required) + +{code} +cd $TAG +$ svn merge https://svn.apache.org/repos/asf/poi/tags/$TAG \ +https://svn.apache.org/repos/asf/poi/trunk +{code} + + Note that if there's set to be lots of merging, you may be best + to create a branch for the release, then create tags from there + rather than trunk + + 8. Build as if the vote had passed. The build date must be +7 days from current. +{code} +# eg ant -DDSTAMP=20100924 dist +ant -DDSTAMP=YYYYMMDD dist +{code} + +where $TAG is the release tag specified in build.xml in the version.id property, $DATE is the release date (typically +7 days from the actual build date). + + 9. Signing the release artifacts: +{code} +cd build/dist +./multisign.sh +{code} + + 10. Upload to the dev svn dist repo, + https://dist.apache.org/repos/dist/dev/poi/ eg + https://dist.apache.org/repos/dist/dev/poi/3.8-RC3/ + +How to upload: + +{code} +svn co https://dist.apache.org/repos/dist/dev/poi +mkdir 3.8-RC3/ +svn add 3.8-RC3 +{code} + +may need --force as in: +{code} +svn add 3.8-RC3 --force +{code} + +then add .gz and .zip packages along with checksums. + + binaries should be in ./bin, sources in ./src sub-directories + +8c. commit +After commit the files should be accessible at https://dist.apache.org/repos/dist/dev/poi/3.8-RC2/ + + + (III) After the vote: + +In the release area of the dist repo: + https://dist.apache.org/repos/dist/release/poi/release/ (FINAL) + https://dist.apache.org/repos/dist/release/poi/dev/ (Alpha/Beta) +Remove the previous release + +Next, svn move the files from the /dist/dev/ area to the appropriate +/dist/release/ area + +example: +$ svn rm -m "remove the previous release" \ + https://dist.apache.org/repos/dist/release/poi/dev/src + https://dist.apache.org/repos/dist/release/poi/dev/bin + +$ svn mv -m "move staging files to the release area" \ + https://dist.apache.org/repos/dist/dev/poi/bin \ + https://dist.apache.org/repos/dist/dev/poi/src/ \ + https://dist.apache.org/repos/dist/release/poi/dev/ + + +deploy Maven artifacts +{code} +cd build/dist +./mvn-deploy.sh +{code} + +2. Wait for the distributions to appear on your favourite mirror + +3. Edit the website homepage and list the new release there. If a full release, + remove older full releases and all beta releases. If a beta release, keep + the last full release, and replace any other beta releases + +4. Edit the website download page, and list the new release there. This should + reference the checksums, so take care when updating + +5. Build site using a recent version of Java 1.6 or 1.7 (must be after the fix + for TA13-169A). + Commit the site changes to svn, and publish live + +6. test maven +create a simple project and make sure the release artifacts are accessible by maven: + +{code} +$ mvn archetype:create -DgroupId=org.apache.poi.scratchpad -DartifactId=maven-test +cd maven-test +{code} +edit pom.xml and add the release artefacts to the project dependencies: + +{code:xml} + + org.apache.poi + poi + 3.1-beta1 + + + org.apache.poi + poi-scratchpad + 3.1-beta1 + +{code} + +{code} +mvn compile +{code} + +You should see [INFO] BUILD SUCCESSFUL in the end. + +Before the package is fully replicated, you may get a BUILD SUCCESSFUL, but you'll also receive a +warning that the .jar can't be downloaded. Wait until you get BUILD SUCCESSFUL and no warnings. + +7. Don't forget to upload the latest version of the site and javadocs + +8. Send announcements: + - to poi-user and poi-dev lists + - to announcements@apache.org, announcements@jakarta.apache.org + +Note, announcements should be sent from your @apache.org e-mail address. + +9. Add a new project version in Bugzilla + +10. Delete directory that held RC. + +e.g. +{code} +svn delete -m "delete empty RC directory for 3.10-beta2" https://dist.apache.org/repos/dist/dev/poi/3.10-beta2-RC1 +{code} diff --git a/src/documentation/resources/images/ApacheConEu08.jpg b/src/documentation/resources/images/ApacheConEu08.jpg new file mode 100644 index 0000000000..7c330579b6 Binary files /dev/null and b/src/documentation/resources/images/ApacheConEu08.jpg differ diff --git a/src/documentation/resources/images/BlockClassDiagram.gif b/src/documentation/resources/images/BlockClassDiagram.gif new file mode 100644 index 0000000000..2433adc92c Binary files /dev/null and b/src/documentation/resources/images/BlockClassDiagram.gif differ diff --git a/src/documentation/resources/images/POIFSAddDocument.gif b/src/documentation/resources/images/POIFSAddDocument.gif new file mode 100644 index 0000000000..d9b2002824 Binary files /dev/null and b/src/documentation/resources/images/POIFSAddDocument.gif differ diff --git a/src/documentation/resources/images/POIFSClassDiagram.gif b/src/documentation/resources/images/POIFSClassDiagram.gif new file mode 100644 index 0000000000..c4ddfff228 Binary files /dev/null and b/src/documentation/resources/images/POIFSClassDiagram.gif differ diff --git a/src/documentation/resources/images/POIFSInitialization.gif b/src/documentation/resources/images/POIFSInitialization.gif new file mode 100644 index 0000000000..d23bf29226 Binary files /dev/null and b/src/documentation/resources/images/POIFSInitialization.gif differ diff --git a/src/documentation/resources/images/POIFSLifeCycle.gif b/src/documentation/resources/images/POIFSLifeCycle.gif new file mode 100644 index 0000000000..3626dcc1b9 Binary files /dev/null and b/src/documentation/resources/images/POIFSLifeCycle.gif differ diff --git a/src/documentation/resources/images/POIFSPropertyTablePreWrite.gif b/src/documentation/resources/images/POIFSPropertyTablePreWrite.gif new file mode 100644 index 0000000000..801c1d8a14 Binary files /dev/null and b/src/documentation/resources/images/POIFSPropertyTablePreWrite.gif differ diff --git a/src/documentation/resources/images/POIFSRootPropertyPreWrite.gif b/src/documentation/resources/images/POIFSRootPropertyPreWrite.gif new file mode 100644 index 0000000000..3927bcce76 Binary files /dev/null and b/src/documentation/resources/images/POIFSRootPropertyPreWrite.gif differ diff --git a/src/documentation/resources/images/POIFSWriteArchive.gif b/src/documentation/resources/images/POIFSWriteArchive.gif new file mode 100644 index 0000000000..eac7fd7a2e Binary files /dev/null and b/src/documentation/resources/images/POIFSWriteArchive.gif differ diff --git a/src/documentation/resources/images/POIFSWriteFilesystem.gif b/src/documentation/resources/images/POIFSWriteFilesystem.gif new file mode 100644 index 0000000000..d5011a0f72 Binary files /dev/null and b/src/documentation/resources/images/POIFSWriteFilesystem.gif differ diff --git a/src/documentation/resources/images/PropertySet.jpg b/src/documentation/resources/images/PropertySet.jpg new file mode 100644 index 0000000000..c0d1461020 Binary files /dev/null and b/src/documentation/resources/images/PropertySet.jpg differ diff --git a/src/documentation/resources/images/PropertyTableClassDiagram.gif b/src/documentation/resources/images/PropertyTableClassDiagram.gif new file mode 100644 index 0000000000..8a72c51ee5 Binary files /dev/null and b/src/documentation/resources/images/PropertyTableClassDiagram.gif differ diff --git a/src/documentation/resources/images/add.jpg b/src/documentation/resources/images/add.jpg new file mode 100644 index 0000000000..a9a0766921 Binary files /dev/null and b/src/documentation/resources/images/add.jpg differ diff --git a/src/documentation/resources/images/built-with-forrest-button.png b/src/documentation/resources/images/built-with-forrest-button.png new file mode 100644 index 0000000000..4a787abe4d Binary files /dev/null and b/src/documentation/resources/images/built-with-forrest-button.png differ diff --git a/src/documentation/resources/images/businessplan.jpg b/src/documentation/resources/images/businessplan.jpg new file mode 100644 index 0000000000..9bfaf4c7b2 Binary files /dev/null and b/src/documentation/resources/images/businessplan.jpg differ diff --git a/src/documentation/resources/images/calculatePayment.jpg b/src/documentation/resources/images/calculatePayment.jpg new file mode 100644 index 0000000000..221433e93d Binary files /dev/null and b/src/documentation/resources/images/calculatePayment.jpg differ diff --git a/src/documentation/resources/images/calendar.jpg b/src/documentation/resources/images/calendar.jpg new file mode 100644 index 0000000000..4f11878290 Binary files /dev/null and b/src/documentation/resources/images/calendar.jpg differ diff --git a/src/documentation/resources/images/fix.jpg b/src/documentation/resources/images/fix.jpg new file mode 100644 index 0000000000..1d6820b43b Binary files /dev/null and b/src/documentation/resources/images/fix.jpg differ diff --git a/src/documentation/resources/images/group-logo-old.gif b/src/documentation/resources/images/group-logo-old.gif new file mode 100644 index 0000000000..049cf82295 Binary files /dev/null and b/src/documentation/resources/images/group-logo-old.gif differ diff --git a/src/documentation/resources/images/group-logo.jpg b/src/documentation/resources/images/group-logo.jpg new file mode 100644 index 0000000000..7f52e79ba5 Binary files /dev/null and b/src/documentation/resources/images/group-logo.jpg differ diff --git a/src/documentation/resources/images/group-logo.png b/src/documentation/resources/images/group-logo.png new file mode 100644 index 0000000000..980473bb5a Binary files /dev/null and b/src/documentation/resources/images/group-logo.png differ diff --git a/src/documentation/resources/images/hslf_shapes.gif b/src/documentation/resources/images/hslf_shapes.gif new file mode 100644 index 0000000000..ee5eec9f15 Binary files /dev/null and b/src/documentation/resources/images/hslf_shapes.gif differ diff --git a/src/documentation/resources/images/loancalc.jpg b/src/documentation/resources/images/loancalc.jpg new file mode 100644 index 0000000000..fdc62e82dd Binary files /dev/null and b/src/documentation/resources/images/loancalc.jpg differ diff --git a/src/documentation/resources/images/logoAdria1.png b/src/documentation/resources/images/logoAdria1.png new file mode 100644 index 0000000000..16a6f113af Binary files /dev/null and b/src/documentation/resources/images/logoAdria1.png differ diff --git a/src/documentation/resources/images/logoAdria2.png b/src/documentation/resources/images/logoAdria2.png new file mode 100644 index 0000000000..d1ad50bc58 Binary files /dev/null and b/src/documentation/resources/images/logoAdria2.png differ diff --git a/src/documentation/resources/images/logoAdria3.png b/src/documentation/resources/images/logoAdria3.png new file mode 100644 index 0000000000..4247b97bfe Binary files /dev/null and b/src/documentation/resources/images/logoAdria3.png differ diff --git a/src/documentation/resources/images/logoAndrewClements.png b/src/documentation/resources/images/logoAndrewClements.png new file mode 100644 index 0000000000..0bc88e4f0a Binary files /dev/null and b/src/documentation/resources/images/logoAndrewClements.png differ diff --git a/src/documentation/resources/images/logoAndrewClements2.png b/src/documentation/resources/images/logoAndrewClements2.png new file mode 100644 index 0000000000..eaccaf0d9e Binary files /dev/null and b/src/documentation/resources/images/logoAndrewClements2.png differ diff --git a/src/documentation/resources/images/logoDanielFernandez.png b/src/documentation/resources/images/logoDanielFernandez.png new file mode 100644 index 0000000000..1ed7ff9268 Binary files /dev/null and b/src/documentation/resources/images/logoDanielFernandez.png differ diff --git a/src/documentation/resources/images/logoGlenStampoutlzis.png b/src/documentation/resources/images/logoGlenStampoutlzis.png new file mode 100644 index 0000000000..f7707c7f27 Binary files /dev/null and b/src/documentation/resources/images/logoGlenStampoutlzis.png differ diff --git a/src/documentation/resources/images/logoGustafsson1.png b/src/documentation/resources/images/logoGustafsson1.png new file mode 100644 index 0000000000..ff13834ff5 Binary files /dev/null and b/src/documentation/resources/images/logoGustafsson1.png differ diff --git a/src/documentation/resources/images/logoGustafsson2.png b/src/documentation/resources/images/logoGustafsson2.png new file mode 100644 index 0000000000..a3f5c86d24 Binary files /dev/null and b/src/documentation/resources/images/logoGustafsson2.png differ diff --git a/src/documentation/resources/images/logoJanssen1.png b/src/documentation/resources/images/logoJanssen1.png new file mode 100644 index 0000000000..e02fe52f47 Binary files /dev/null and b/src/documentation/resources/images/logoJanssen1.png differ diff --git a/src/documentation/resources/images/logoJanssen2.png b/src/documentation/resources/images/logoJanssen2.png new file mode 100644 index 0000000000..c7b406ed22 Binary files /dev/null and b/src/documentation/resources/images/logoJanssen2.png differ diff --git a/src/documentation/resources/images/logoKarmokar1.png b/src/documentation/resources/images/logoKarmokar1.png new file mode 100644 index 0000000000..232b22e8e5 Binary files /dev/null and b/src/documentation/resources/images/logoKarmokar1.png differ diff --git a/src/documentation/resources/images/logoKarmokar1s.png b/src/documentation/resources/images/logoKarmokar1s.png new file mode 100644 index 0000000000..41742031ce Binary files /dev/null and b/src/documentation/resources/images/logoKarmokar1s.png differ diff --git a/src/documentation/resources/images/logoKarmokar2.png b/src/documentation/resources/images/logoKarmokar2.png new file mode 100644 index 0000000000..7168b70e98 Binary files /dev/null and b/src/documentation/resources/images/logoKarmokar2.png differ diff --git a/src/documentation/resources/images/logoKarmokar2s.png b/src/documentation/resources/images/logoKarmokar2s.png new file mode 100644 index 0000000000..93977b087d Binary files /dev/null and b/src/documentation/resources/images/logoKarmokar2s.png differ diff --git a/src/documentation/resources/images/logoKarmokar3.png b/src/documentation/resources/images/logoKarmokar3.png new file mode 100644 index 0000000000..ef8b14668a Binary files /dev/null and b/src/documentation/resources/images/logoKarmokar3.png differ diff --git a/src/documentation/resources/images/logoKarmokar3s.png b/src/documentation/resources/images/logoKarmokar3s.png new file mode 100644 index 0000000000..e9e86bdfa5 Binary files /dev/null and b/src/documentation/resources/images/logoKarmokar3s.png differ diff --git a/src/documentation/resources/images/logoKarmokar4.png b/src/documentation/resources/images/logoKarmokar4.png new file mode 100644 index 0000000000..90a915a3a9 Binary files /dev/null and b/src/documentation/resources/images/logoKarmokar4.png differ diff --git a/src/documentation/resources/images/logoKarmokar4s.png b/src/documentation/resources/images/logoKarmokar4s.png new file mode 100644 index 0000000000..33391cd963 Binary files /dev/null and b/src/documentation/resources/images/logoKarmokar4s.png differ diff --git a/src/documentation/resources/images/logoKarmokar5.png b/src/documentation/resources/images/logoKarmokar5.png new file mode 100644 index 0000000000..e2d1f3f858 Binary files /dev/null and b/src/documentation/resources/images/logoKarmokar5.png differ diff --git a/src/documentation/resources/images/logoKarmokar5s.png b/src/documentation/resources/images/logoKarmokar5s.png new file mode 100644 index 0000000000..5ea300d16f Binary files /dev/null and b/src/documentation/resources/images/logoKarmokar5s.png differ diff --git a/src/documentation/resources/images/logoKarmokar6.png b/src/documentation/resources/images/logoKarmokar6.png new file mode 100644 index 0000000000..0407c35823 Binary files /dev/null and b/src/documentation/resources/images/logoKarmokar6.png differ diff --git a/src/documentation/resources/images/logoKarmokar6s.png b/src/documentation/resources/images/logoKarmokar6s.png new file mode 100644 index 0000000000..b13fb1890d Binary files /dev/null and b/src/documentation/resources/images/logoKarmokar6s.png differ diff --git a/src/documentation/resources/images/logoLoicLefevre.png b/src/documentation/resources/images/logoLoicLefevre.png new file mode 100644 index 0000000000..520840dff7 Binary files /dev/null and b/src/documentation/resources/images/logoLoicLefevre.png differ diff --git a/src/documentation/resources/images/logoLoicLefevre2.png b/src/documentation/resources/images/logoLoicLefevre2.png new file mode 100644 index 0000000000..ce8efa3113 Binary files /dev/null and b/src/documentation/resources/images/logoLoicLefevre2.png differ diff --git a/src/documentation/resources/images/logoMichaelMosmann.png b/src/documentation/resources/images/logoMichaelMosmann.png new file mode 100644 index 0000000000..08424c7bf8 Binary files /dev/null and b/src/documentation/resources/images/logoMichaelMosmann.png differ diff --git a/src/documentation/resources/images/logoRaPiGmbH1.png b/src/documentation/resources/images/logoRaPiGmbH1.png new file mode 100644 index 0000000000..3bef8bb6e9 Binary files /dev/null and b/src/documentation/resources/images/logoRaPiGmbH1.png differ diff --git a/src/documentation/resources/images/logoRaPiGmbH10.png b/src/documentation/resources/images/logoRaPiGmbH10.png new file mode 100644 index 0000000000..46fd998659 Binary files /dev/null and b/src/documentation/resources/images/logoRaPiGmbH10.png differ diff --git a/src/documentation/resources/images/logoRaPiGmbH11.png b/src/documentation/resources/images/logoRaPiGmbH11.png new file mode 100644 index 0000000000..c92d32688e Binary files /dev/null and b/src/documentation/resources/images/logoRaPiGmbH11.png differ diff --git a/src/documentation/resources/images/logoRaPiGmbH12.png b/src/documentation/resources/images/logoRaPiGmbH12.png new file mode 100644 index 0000000000..c006c7c562 Binary files /dev/null and b/src/documentation/resources/images/logoRaPiGmbH12.png differ diff --git a/src/documentation/resources/images/logoRaPiGmbH2.png b/src/documentation/resources/images/logoRaPiGmbH2.png new file mode 100644 index 0000000000..d842217557 Binary files /dev/null and b/src/documentation/resources/images/logoRaPiGmbH2.png differ diff --git a/src/documentation/resources/images/logoRaPiGmbH5.png b/src/documentation/resources/images/logoRaPiGmbH5.png new file mode 100644 index 0000000000..f96ef9ef91 Binary files /dev/null and b/src/documentation/resources/images/logoRaPiGmbH5.png differ diff --git a/src/documentation/resources/images/logoRaPiGmbH6.png b/src/documentation/resources/images/logoRaPiGmbH6.png new file mode 100644 index 0000000000..53ee5e9eab Binary files /dev/null and b/src/documentation/resources/images/logoRaPiGmbH6.png differ diff --git a/src/documentation/resources/images/logoRaPiGmbH7.png b/src/documentation/resources/images/logoRaPiGmbH7.png new file mode 100644 index 0000000000..498499d9df Binary files /dev/null and b/src/documentation/resources/images/logoRaPiGmbH7.png differ diff --git a/src/documentation/resources/images/logoRaPiGmbH8.png b/src/documentation/resources/images/logoRaPiGmbH8.png new file mode 100644 index 0000000000..7df1b28d6e Binary files /dev/null and b/src/documentation/resources/images/logoRaPiGmbH8.png differ diff --git a/src/documentation/resources/images/logoRaPiGmbH9.png b/src/documentation/resources/images/logoRaPiGmbH9.png new file mode 100644 index 0000000000..7df1b28d6e Binary files /dev/null and b/src/documentation/resources/images/logoRaPiGmbH9.png differ diff --git a/src/documentation/resources/images/logoRandyStanard01.png b/src/documentation/resources/images/logoRandyStanard01.png new file mode 100644 index 0000000000..f236c10a6e Binary files /dev/null and b/src/documentation/resources/images/logoRandyStanard01.png differ diff --git a/src/documentation/resources/images/logoRandyStanard02.png b/src/documentation/resources/images/logoRandyStanard02.png new file mode 100644 index 0000000000..d20c8bacc7 Binary files /dev/null and b/src/documentation/resources/images/logoRandyStanard02.png differ diff --git a/src/documentation/resources/images/logoRandyStanard03.png b/src/documentation/resources/images/logoRandyStanard03.png new file mode 100644 index 0000000000..45850fa744 Binary files /dev/null and b/src/documentation/resources/images/logoRandyStanard03.png differ diff --git a/src/documentation/resources/images/logoRandyStanard04.png b/src/documentation/resources/images/logoRandyStanard04.png new file mode 100644 index 0000000000..da62011014 Binary files /dev/null and b/src/documentation/resources/images/logoRandyStanard04.png differ diff --git a/src/documentation/resources/images/logoRandyStanard05.png b/src/documentation/resources/images/logoRandyStanard05.png new file mode 100644 index 0000000000..0b63989f94 Binary files /dev/null and b/src/documentation/resources/images/logoRandyStanard05.png differ diff --git a/src/documentation/resources/images/logoRandyStanard06.png b/src/documentation/resources/images/logoRandyStanard06.png new file mode 100644 index 0000000000..9474220a1c Binary files /dev/null and b/src/documentation/resources/images/logoRandyStanard06.png differ diff --git a/src/documentation/resources/images/logoRandyStanard07.png b/src/documentation/resources/images/logoRandyStanard07.png new file mode 100644 index 0000000000..c7b6aca5bc Binary files /dev/null and b/src/documentation/resources/images/logoRandyStanard07.png differ diff --git a/src/documentation/resources/images/logoRandyStanard08.png b/src/documentation/resources/images/logoRandyStanard08.png new file mode 100644 index 0000000000..83d5bf9ca9 Binary files /dev/null and b/src/documentation/resources/images/logoRandyStanard08.png differ diff --git a/src/documentation/resources/images/logoRussellBeattie1.png b/src/documentation/resources/images/logoRussellBeattie1.png new file mode 100644 index 0000000000..228d13c4e3 Binary files /dev/null and b/src/documentation/resources/images/logoRussellBeattie1.png differ diff --git a/src/documentation/resources/images/logoRussellBeattie2.png b/src/documentation/resources/images/logoRussellBeattie2.png new file mode 100644 index 0000000000..052209ec6f Binary files /dev/null and b/src/documentation/resources/images/logoRussellBeattie2.png differ diff --git a/src/documentation/resources/images/logoRussellBeattie3.png b/src/documentation/resources/images/logoRussellBeattie3.png new file mode 100644 index 0000000000..9a4e98c2da Binary files /dev/null and b/src/documentation/resources/images/logoRussellBeattie3.png differ diff --git a/src/documentation/resources/images/logoRussellBeattie4.png b/src/documentation/resources/images/logoRussellBeattie4.png new file mode 100644 index 0000000000..5a6b0fb334 Binary files /dev/null and b/src/documentation/resources/images/logoRussellBeattie4.png differ diff --git a/src/documentation/resources/images/logoRussellBeattie5.png b/src/documentation/resources/images/logoRussellBeattie5.png new file mode 100644 index 0000000000..71ef63c6fc Binary files /dev/null and b/src/documentation/resources/images/logoRussellBeattie5.png differ diff --git a/src/documentation/resources/images/logoWendyWise.png b/src/documentation/resources/images/logoWendyWise.png new file mode 100644 index 0000000000..43f7569cd5 Binary files /dev/null and b/src/documentation/resources/images/logoWendyWise.png differ diff --git a/src/documentation/resources/images/logoWendyWise2.png b/src/documentation/resources/images/logoWendyWise2.png new file mode 100644 index 0000000000..8ab6eaa07a Binary files /dev/null and b/src/documentation/resources/images/logoWendyWise2.png differ diff --git a/src/documentation/resources/images/old-project-logo.gif b/src/documentation/resources/images/old-project-logo.gif new file mode 100644 index 0000000000..b9c2ee1391 Binary files /dev/null and b/src/documentation/resources/images/old-project-logo.gif differ diff --git a/src/documentation/resources/images/poi-logo.png b/src/documentation/resources/images/poi-logo.png new file mode 100644 index 0000000000..73c02a5603 Binary files /dev/null and b/src/documentation/resources/images/poi-logo.png differ diff --git a/src/documentation/resources/images/project-logo.jpg b/src/documentation/resources/images/project-logo.jpg new file mode 100644 index 0000000000..e10d714139 Binary files /dev/null and b/src/documentation/resources/images/project-logo.jpg differ diff --git a/src/documentation/resources/images/project-logo.png b/src/documentation/resources/images/project-logo.png new file mode 100644 index 0000000000..f0b83c4e70 Binary files /dev/null and b/src/documentation/resources/images/project-logo.png differ diff --git a/src/documentation/resources/images/remove.jpg b/src/documentation/resources/images/remove.jpg new file mode 100644 index 0000000000..e18d135b35 Binary files /dev/null and b/src/documentation/resources/images/remove.jpg differ diff --git a/src/documentation/resources/images/simple-xls-with-function.jpg b/src/documentation/resources/images/simple-xls-with-function.jpg new file mode 100644 index 0000000000..d5879ae026 Binary files /dev/null and b/src/documentation/resources/images/simple-xls-with-function.jpg differ diff --git a/src/documentation/resources/images/ss-features.png b/src/documentation/resources/images/ss-features.png new file mode 100644 index 0000000000..17554c7151 Binary files /dev/null and b/src/documentation/resources/images/ss-features.png differ diff --git a/src/documentation/resources/images/timesheet.jpg b/src/documentation/resources/images/timesheet.jpg new file mode 100644 index 0000000000..1ff512b1f9 Binary files /dev/null and b/src/documentation/resources/images/timesheet.jpg differ diff --git a/src/documentation/resources/images/unknown.jpg b/src/documentation/resources/images/unknown.jpg new file mode 100644 index 0000000000..75f357e6c2 Binary files /dev/null and b/src/documentation/resources/images/unknown.jpg differ diff --git a/src/documentation/resources/images/update.jpg b/src/documentation/resources/images/update.jpg new file mode 100644 index 0000000000..586a4527e3 Binary files /dev/null and b/src/documentation/resources/images/update.jpg differ diff --git a/src/documentation/resources/images/usermodel.gif b/src/documentation/resources/images/usermodel.gif new file mode 100644 index 0000000000..4f4c3606c3 Binary files /dev/null and b/src/documentation/resources/images/usermodel.gif differ diff --git a/src/documentation/resources/images/utilClasses.gif b/src/documentation/resources/images/utilClasses.gif new file mode 100644 index 0000000000..5cb07b79a5 Binary files /dev/null and b/src/documentation/resources/images/utilClasses.gif differ diff --git a/src/documentation/resources/images/vba-example.jpg b/src/documentation/resources/images/vba-example.jpg new file mode 100644 index 0000000000..0d95b90001 Binary files /dev/null and b/src/documentation/resources/images/vba-example.jpg differ diff --git a/src/documentation/skinconf.xml b/src/documentation/skinconf.xml new file mode 100644 index 0000000000..9f34b88b61 --- /dev/null +++ b/src/documentation/skinconf.xml @@ -0,0 +1,142 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + ]> + + + + true + + false + + false + + true + + true + + false + + false + + poi.apache.org + Apache POI + + + POI + POI + http://poi.apache.org/ + resources/images/project-logo.jpg + + + Apache POI + Apache POI + http://poi.apache.org + resources/images/group-logo.jpg + + + + + + + 2002-2012 + The Apache Software Foundation + + + + + + + + + + + Built with Apache Forrest + http://forrest.apache.org/ + skin/images/built-with-forrest-button.png + 88 + 31 + + + + + diff --git a/src/documentation/skins/common/images/README.txt b/src/documentation/skins/common/images/README.txt new file mode 100644 index 0000000000..24bf01ad75 --- /dev/null +++ b/src/documentation/skins/common/images/README.txt @@ -0,0 +1,3 @@ +This directory is currently useless, as the sitemap only looks in +skins/{forrest:skin}, so files must be kept in synch manually until this is +fixed. diff --git a/src/documentation/skins/common/images/built-with-forrest-button.png b/src/documentation/skins/common/images/built-with-forrest-button.png new file mode 100644 index 0000000000..4a787abe4d Binary files /dev/null and b/src/documentation/skins/common/images/built-with-forrest-button.png differ diff --git a/src/documentation/skins/common/images/pdfdoc.gif b/src/documentation/skins/common/images/pdfdoc.gif new file mode 100644 index 0000000000..00dee28aad Binary files /dev/null and b/src/documentation/skins/common/images/pdfdoc.gif differ diff --git a/src/documentation/skins/common/images/printer.gif b/src/documentation/skins/common/images/printer.gif new file mode 100644 index 0000000000..5021187b06 Binary files /dev/null and b/src/documentation/skins/common/images/printer.gif differ diff --git a/src/documentation/skins/common/images/spacer.gif b/src/documentation/skins/common/images/spacer.gif new file mode 100644 index 0000000000..35d42e808f Binary files /dev/null and b/src/documentation/skins/common/images/spacer.gif differ diff --git a/src/documentation/skins/common/images/valid-html401.png b/src/documentation/skins/common/images/valid-html401.png new file mode 100644 index 0000000000..3855210c6c Binary files /dev/null and b/src/documentation/skins/common/images/valid-html401.png differ diff --git a/src/documentation/skins/common/images/xmldoc.gif b/src/documentation/skins/common/images/xmldoc.gif new file mode 100644 index 0000000000..ca1224f61f Binary files /dev/null and b/src/documentation/skins/common/images/xmldoc.gif differ diff --git a/src/documentation/skins/common/xslt/fo/document2fo.xsl b/src/documentation/skins/common/xslt/fo/document2fo.xsl new file mode 100644 index 0000000000..474e0e4bf0 --- /dev/null +++ b/src/documentation/skins/common/xslt/fo/document2fo.xsl @@ -0,0 +1,723 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Page + + + + + + + + + + + + + + + + Page + + + + + + + + + + + + + + + + Page + + + + + + + + + + + + + + + + + + + + + + + + + NOTICE: + + + + + + + + + + + 0 + + + + + + + + + + + + + + + + + + + + + + + + + + + + . + + + + + + pt + + + + + + + + + + + + + + + + + 0 + + + + + + + + + + by + + + , + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + • + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Note: + + + + + + + + + + + + Note: + + + + + + + + + + FIXME (): + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + in + + + + + + + + + + + + + + + + + + + + + + + + + Table + + + : + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + [] + + + + + + diff --git a/src/documentation/skins/common/xslt/fo/footerinfo.xsl b/src/documentation/skins/common/xslt/fo/footerinfo.xsl new file mode 100644 index 0000000000..d0c116520d --- /dev/null +++ b/src/documentation/skins/common/xslt/fo/footerinfo.xsl @@ -0,0 +1,76 @@ + + + + + + + + + + + + + + + + + Copyright ©   All rights reserved. + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/src/documentation/skins/common/xslt/fo/pdfoutline.xsl b/src/documentation/skins/common/xslt/fo/pdfoutline.xsl new file mode 100644 index 0000000000..f9eb96fd5a --- /dev/null +++ b/src/documentation/skins/common/xslt/fo/pdfoutline.xsl @@ -0,0 +1,51 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/src/documentation/skins/common/xslt/html/book2menu.xsl b/src/documentation/skins/common/xslt/html/book2menu.xsl new file mode 100644 index 0000000000..619d1decff --- /dev/null +++ b/src/documentation/skins/common/xslt/html/book2menu.xsl @@ -0,0 +1,180 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
  • + + + + + + + + + + +
    • +     + + + + + + + + + +     diff --git a/src/documentation/skins/common/xslt/html/document2html.xsl b/src/documentation/skins/common/xslt/html/document2html.xsl new file mode 100644 index 0000000000..fc9eaaabd6 --- /dev/null +++ b/src/documentation/skins/common/xslt/html/document2html.xsl @@ -0,0 +1,466 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + 2 + + + + + + + + + + + + + + + + + + + + + + + + + +
    + + + + + + + +
    + +

    + +

    +     +
    + +

    + +

    +     + + + + +
    + + + ; + + +
    +
    +     + + + + + + + + + + + + + + + + PDF
    + PDF     + +     +     + + + + + + + xml
    + xml     + +     +     + + + + + + 1 + + + + + + + + + + + + + + + + + + + + + + + ^ + + + + + + + + 15 + + + 0 + + + + +
    + +
    + + + + +
    +
    + + + Note + Warning + Fixme () + +
    +
    + +
    +
    +     + + +
    + + Notice: + +
    +     + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    + +
    +     + + + + 
    +
+      
+
+
    +     + + + + + + + + {@alt} + + + + + + + + + + + + + + + + +
    + {@alt} + + + + + + + +
    +     + + + + + + + + + + +
    +     + + + + + + + + + + + +
      + +
    • + + + + + + + +
      • +       +
    +     +     + + + + +     + + # + + + + + + + + + + + + + by  + ,  + + + + + + + + + + + + + + version + + + + + + + + + + v + + + + + + + + + + + + + + + +

    + + Type: + +

    +     + + +

    + +

    +     + + + + + + + + + + + + + + + + + + + + + + + + + + +     diff --git a/src/documentation/skins/common/xslt/html/dotdots.xsl b/src/documentation/skins/common/xslt/html/dotdots.xsl new file mode 100644 index 0000000000..0540f19d03 --- /dev/null +++ b/src/documentation/skins/common/xslt/html/dotdots.xsl @@ -0,0 +1,81 @@ + + + + + + + + + + + + + + ../ + + + + + + + + + + diff --git a/src/documentation/skins/common/xslt/html/pathutils.xsl b/src/documentation/skins/common/xslt/html/pathutils.xsl new file mode 100644 index 0000000000..4d147a54ba --- /dev/null +++ b/src/documentation/skins/common/xslt/html/pathutils.xsl @@ -0,0 +1,242 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/src/documentation/skins/common/xslt/html/renderlogo.xsl b/src/documentation/skins/common/xslt/html/renderlogo.xsl new file mode 100644 index 0000000000..6db63cf3a6 --- /dev/null +++ b/src/documentation/skins/common/xslt/html/renderlogo.xsl @@ -0,0 +1,65 @@ + + + + + + + + + + + + + + + + + + + {$name} + + + + + + + + + + + + + + + + + + + + + diff --git a/src/documentation/skins/common/xslt/html/site2xhtml.xsl b/src/documentation/skins/common/xslt/html/site2xhtml.xsl new file mode 100644 index 0000000000..4d74954cba --- /dev/null +++ b/src/documentation/skins/common/xslt/html/site2xhtml.xsl @@ -0,0 +1,157 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + <xsl:value-of select="div[@class='content']/table/tr/td/h1"/> + + + + + + + + + + + + + + + + + + + ================= start Tabs ================== + + ================= end Tabs ================== + ================= start Menu items ================== + + ================= end Menu items ================== + ================= start Content================== + + ================= end Content================== + + ================= start Footer ================== + Copyright ©   All rights reserved.
    + Apache POI, POI, Apache, the Apache feather logo, and the Apache + POI project logo are trademarks of The Apache Software Foundation. + + + + + + + + + + + + + + + + + + + + + + + + Valid HTML 4.01! + + +     + + + + + Valid HTML 4.01! + + Valid CSS! + + + + + + + + + + + +     diff --git a/src/documentation/skins/common/xslt/html/split.xsl b/src/documentation/skins/common/xslt/html/split.xsl new file mode 100644 index 0000000000..7a0d324039 --- /dev/null +++ b/src/documentation/skins/common/xslt/html/split.xsl @@ -0,0 +1,160 @@ + + + + + + + + + + + + + 40 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/src/documentation/skins/common/xslt/html/tab2menu.xsl b/src/documentation/skins/common/xslt/html/tab2menu.xsl new file mode 100644 index 0000000000..9e6047a6a1 --- /dev/null +++ b/src/documentation/skins/common/xslt/html/tab2menu.xsl @@ -0,0 +1,176 @@ + + + + + + + + + + + + + + + + + + + + + | + + + + + + + + + + + + + + + + + + + + +
    + +
    +     + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +     diff --git a/src/documentation/skins/common/xslt/html/tabutils.xsl b/src/documentation/skins/common/xslt/html/tabutils.xsl new file mode 100644 index 0000000000..ad58149e74 --- /dev/null +++ b/src/documentation/skins/common/xslt/html/tabutils.xsl @@ -0,0 +1,96 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + / + + + + / + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/src/documentation/skins/poi-site/css/mysite.css b/src/documentation/skins/poi-site/css/mysite.css new file mode 100644 index 0000000000..e2fef30032 --- /dev/null +++ b/src/documentation/skins/poi-site/css/mysite.css @@ -0,0 +1,139 @@ +/* +* 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. +*/ +/* + * Other colors: + * - dark blue: #036 + * - bluish: #269 + * + */ + +/* + * The Banner section. + */ +.banner, .projectLogo, .groupLogo, .projectLogo a, .groupLogo a, + .groupLogo a:visited, .projectLogo a:visited, + .groupLogo a:link, .projectLogo a:link { +} + +/* + * The Status + Footer section. + */ +.status, .breadcrumb, .searcher, .tabs { +} + +.selectedTab { +} + +/* + * The Menu section. + */ +.menuColumn { +} +.menubar { +} +.menu { +} +.menuLabel { +} +.menuItem { +} + +/* + * The Content section. + */ +.contentColumn { +} + +h1, h2, h3, h4 { +} + +h3, h4 { + } +h3 { + } +h4 { +} + +.code { +} + +.section { +} + +.subsection { +} + +/* + * The Footer section. + */ +.footer, .copyright, .host, .credit { +} + +/* + * General Settings + */ +body { +} + +a:link, .menuItem a:visited, .status a:visited { + color: #036; +} + +a:active, a:hover { + +} + +body, th, td { +} + +.logoImage { +} + +.frame { + border: solid black 1px; + margin: 1em 3em; +} + +.frame .label { + background: #369; + color: white; + font-weight: bold; + padding: 5px 10px; +} +.frame .content { + padding: 5px 10px; + background: #F0F0FF; + color: black; + line-height: 120%; + font-size: 90%; +} +.warning .label { + background: #C00; + color: white; +} +.warning .content { + background: #FFF0F0; + color: black; +} +.fixme .label { + background: #C6C600; +} + +.codefrag { + font-family: "Courier New", Courier, monospace; + font-size: 110%; +} diff --git a/src/documentation/skins/poi-site/css/print.css b/src/documentation/skins/poi-site/css/print.css new file mode 100644 index 0000000000..3f914431a7 --- /dev/null +++ b/src/documentation/skins/poi-site/css/print.css @@ -0,0 +1,32 @@ +/* +* 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. +*/ +#banner, #footer, #leftcol, #breadcrumbs, .docs #toc, .docs .courtesylinks { + display: none; + } +body.docs div.docs { + margin: 0 !important; + border: none !important + } + +/* just to be sure */ +#navcolumn { + width: 0px; +} + +#leftcol { + width: 0px; +} diff --git a/src/documentation/skins/poi-site/css/site.css b/src/documentation/skins/poi-site/css/site.css new file mode 100644 index 0000000000..b89e867ae0 --- /dev/null +++ b/src/documentation/skins/poi-site/css/site.css @@ -0,0 +1,104 @@ +/* +* 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. +*/ +div#banner { + border-top: 1px solid #fff; + border-bottom: 1px solid #aaa; +} + +p img.ontheright { + float: right; +} + +#banner, #banner td { + background: #fff; + color: #036; +} + +#tabs { + text-align: right; +} + +.selectedTab { + color: #036; +} + + a.unselectedTab { + color: #888888; +} + +#source { + background-color: #fff; + color: #000; + border-right: 1px solid #888; + border-left: 1px solid #888; + border-top: 1px solid #888; + border-bottom: 1px solid #888; + margin-right: 7px; + margin-left: 7px; + margin-top: 1em; +} + +#source pre { + margin-right: 7px; + margin-left: 7px; +} + +/* make the whole column grey */ +#navcolumn { + width: 180px; + } + +#leftcol { + width: 180px; +} + +/* + * The Menu section. + */ +.menuColumn { +} + +.menu { + padding-bottom: .2em; + font-size: x-small; + text-decoration: none; +} +.menuLabel { font-weight: bold; } +.menuItem { + padding-left: 12px; + text-decoration: none; +} + +/* breadcrumbs */ +#breadcrumbs +{ + font-weight: bold; +} +.breadcrumbTrail +{ + padding-left: 5px; +} +.breadcrumb +{ + font-weight: bold; +} +.crumbSeparator +{ +} +#authors { + font-size: x-small; +} diff --git a/src/documentation/skins/poi-site/css/tigris.css b/src/documentation/skins/poi-site/css/tigris.css new file mode 100644 index 0000000000..dc8f9cf494 --- /dev/null +++ b/src/documentation/skins/poi-site/css/tigris.css @@ -0,0 +1,450 @@ +/* +* 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. +*/ +/* contains rules unsuitable for Netscape 4.x; simpler rules are in ns4_only.css. see */ + +/* colors, backgrounds, borders, link indication */ + +body { + background: #fff; + color: #000; + } +.app h3, .app h4, .app th, .tabs td, .tabs th, .functnbar { + background-image: url(images/nw_maj_rond.gif); + background-repeat: no-repeat; + } +#navcolumn div div, body.docs #toc li li { + background-image: url(images/strich.gif); + background-repeat: no-repeat; + background-position: .5em .5em; + } +#navcolumn div div.heading { + background-image: none; + } +.app h3, .app h4 { + color: #fff; + } +.app h3 { + background-color: #036; + } +.app h4 { + background-color: #888; + } +.a td { + background: #ddd; + } +.b td { + background: #efefef; + } +table, th, td { + border: none + } +.mtb { + border-top: solid 1px #ddd; + } +div.colbar { + background: #bbb; + } +div#banner { + border-top: 1px solid #369; + border-bottom: 1px solid #003; + } +div#helptext th { + border-bottom: 1px solid #996; + border-right: 1px solid #996; + } +div#helptext td { + border-bottom: 1px solid #cc9; + border-right: 1px solid #cc9; + } +.tabs { + border-bottom: .75em #888 solid; + } +.tabs th, .tabs td { + border-right: 1px solid #333; + } +.tabs td { + border-bottom: 1px solid #ddd; + } +#navcolumn { + background: #eee; + border-right: 1px solid #aaa; + border-bottom: 1px solid #aaa; + } +#breadcrumbs { + border-bottom: 1px solid #aaa; + background-color: #ddd; + } +#navcolumn, #breadcrumbs { + border-top: 1px solid #fff; + } +#rightcol div.www, #rightcol div.help { + border: 1px solid #ddd; + } +div#navcolumn div.focus { + border-top: 1px solid #aaa; + border-left: 1px solid #aaa; + background-color: #fff; + } +body.docs div.docs { + background: #fff; + border-left: 1px solid #ddd; + border-top: 1px solid #ddd; + } +body.docs { + background: #eee url(images/help_logo.gif) top right no-repeat !important; + } +.docs h3, .docs h4 { + border-top: solid 1px #000; + } +#alerterrormessage { + background: url(images/icon_alert.gif) top left no-repeat !important; + } +.functnbar { + background-color: #aaa; + } +.functnbar2, .functnbar3 { + background: #aaa; + } +.functnbar3 { + background-color: #ddd; + } +.functnbar, .functnbar2, .functnbar3 { + color: #000; + } +.functnbar a, .functnbar2 a, .functnbar3 a { + color: #000; + text-decoration: underline; + } +#topmodule { + background: #ddd; + border-top: 1px solid #fff; + border-bottom: 1px solid #aaa; + border-right: 1px solid #aaa; + } +#topmodule #issueid { + border-right: 1px solid #aaa; + } +a:link, #navcolumn a:visited, .app a:visited, .tasknav a:visited { + color: blue; + } +a:active, a:hover, #leftcol a:active, #leftcol a:hover { + color: #f30 !important; + } +#login a:link, #login a:visited { + color: white; + text-decoration: underline; + } +#banner a:active, #banner a:hover { + color: #f90 !important; + } +#leftcol a, #breadcrumbs a { + text-decoration: none; + } +a:link.selfref, a:visited.selfref { + color: #555 !important; + text-decoration: none; + } +h2 .lastchild { + color: #777 + } +.tabs td, .tabs th { + background-color: #ddd; + } +.app th { + background-color: #bbb; + } +.tabs th { + background-color: #888; + color: #fff; + } +.axial th { + background-color: #ddd; + color: black + } +.tabs td { + background-color: #ddd; + } +.alert { + color: #c00; + } +.confirm { + color: green; + } +.info { + color: blue; + } +.selection { + background: #ffc; + } +#login { + color: #fff; + } +#helptext th { + background: #cc9; + } +#helptext td { + background: #ffc; + } +.tabs a { + text-decoration: none; + } +#navcolumn div strong { + color: #000; + } +#banner, #banner td { + background: #036; + color: #fff; + } +body #banner #login a { + color: #fff; + } + + +/* font and text properties, exclusive of link indication, alignment, text-indent */ + +body, th, td, input, select, textarea, h2 small { + font-family: Verdana, Helvetica, Arial, sans-serif; + } +code, pre { + font-family: 'Andale Mono', Courier, monospace; + } +html body, body th, body td, textarea, h2 small, .app h3, .app h4, #rightcol h3, #bodycol pre, #bodycol code { + font-size: x-small; + voice-family: "\"}\""; + voice-family: inherit; + font-size: small + } +html>body, html>body th, html>body td, html>body input, html>body select, html>body textarea, html>body h2 small, html>body .app h3, html>body .app h4, html>body #rightcol h3, html>body #bodycol pre, html>body #bodycol code { + font-size: small + } +small, div#footer td, div#login, div.tabs th, div.tabs td, input, select, .paginate, .functnbar, .functnbar2, .functnbar3, #breadcrumbs td, .courtesylinks, #rightcol div.help, .colbar, .tasknav, body.docs div#toc, #leftcol { + font-size: x-small; + voice-family: "\"}\""; + voice-family: inherit; + font-size: x-small + } +html>body small, html>body div#footer td, html>body div#login, html>body div#helptext td, html>body div#helptext th, html>body div.tabs th, html>body div.tabs td, html>body input, html>body select, html>body .paginate, html>body .functnbar, html>body .functnbar2, html>body .functnbar3, html>body #breadcrumbs td, html>body .courtesylinks, html>body #rightcol div.help, html>body .colbar, html>body .tasknav, html>body.docs #toc { + font-size: x-small + } +#bodycol h2 { + font-family: Tahoma, Verdana, Helvetica, Arial, sans-serif; + font-size: 1.5em; + font-weight: normal; + } +h2 small { + font-weight: bold; + letter-spacing: .06em; + } +dt { + font-weight: bold + } +#login .username { + font-weight: bold; + } +h4 { + font-size: 1em; + } +#breadcrumbs td { + font-weight: bold; + } +.selection { + font-weight: bold + } + + +/* box properties (exclusive of borders), positioning, alignments, list types, text-indent */ + +#bodycol h2 { + margin-top: .3em; + margin-bottom: .5em; + } +p, ul, ol, dl { + margin-top: .67em; + margin-bottom: .67em; + } +h3, h4 { + margin-bottom: 0; + } +form { + margin-top: 0; + margin-bottom: 0; + } +#bodycol { + padding-left: 12px; + padding-right: 12px; + width: 100%; + voice-family: "\"}\""; + voice-family: inherit; + width: auto; + } +html>body #bodycol { + width: auto; + } +.docs { + line-height: 1.4; + } +.app h3, .app h4 { + padding: 5px; + margin-right: 2px; + margin-left: 2px; + } +.h3 p, .h4 p, .h3 dt, .h4 dt { + margin-right: 7px; + margin-left: 7px; + } +.tasknav { + margin-bottom: 1.33em + } +div.colbar { + padding: 4px; + margin: 2px 2px 0; + } +.tabs { + margin-top: .67em; + margin-right: 2px; + margin-left: 2px; + } +#leftcol { + padding-bottom: .5em; + } +#breadcrumbs td { + vertical-align: middle; + padding: 2px 8px; + } +#rightcol div.www, #rightcol div.help { + padding: 0 .5em + } +#navcolumn { + margin: -8px -8px 0 -8px; + padding: 4px; + } +#navcolumn div { + padding-left: 5px + } +div#navcolumn div div { + margin-top: .3em; + margin-bottom: .3em; + } +div#navcolumn div.focus { + margin-top: -.1em; + padding: .2em 4px; + } +body.docs #toc { + position: absolute; + top: 15px; + left: 0px; + width: 120px; + padding: 0 20px 0 0 + } +body.docs #toc ul, #toc ol { + margin-left: 0; + padding-left: 0; + } +body.docs #toc li { + margin-top: 7px; + padding-left: 10px; + list-style-type: none; + } +body.docs div.docs { + margin: 61px 0 0 150px; + padding: 1em 2em 1em 1em !important; + } +.docs p+p { + text-indent: 5%; + margin-top: -.67em + } +.docs h3, .docs h4 { + margin-bottom: .1em; + padding-top: .3em; + } +#alerterrormessage { + padding-left: 100px; + } +.functnbar, .functnbar2, .functnbar3 { + padding: 5px; + margin: .67em 2px; + } +#topmodule td { + vertical-align: middle; + padding: 2px 8px + } +body { + padding: 1em; + } +body.composite, body.docs { + margin: 0; + padding: 0; + } +th, td { + text-align: left; + vertical-align: top + } +.right { + text-align: right !important; + } +.center { + text-align: center !important; + } +.tabs td, .tabs th { + padding-left: 7px; + padding-right: 7px; + } +.axial th { + text-align: right; + } +.app .axial td th { + text-align: left; + } +body td .stb { + margin-top: 1em; + text-indent: 0; + } +body td .mtb { + margin-top: 2em; + text-indent: 0; + } +dd { + margin-bottom: .67em; + } +#footer { + margin: 4px + } +#helptext { + margin-top: 1em + } +#helptext td div { + margin: .5em + } +.courtesylinks { + margin-top: 1em; + padding-top: 1em + } +#navcolumn div { + margin-bottom: .5em; + } +#navcolumn div div { + margin-top: .3em + } +#navcolumn div div { + padding-left: 1em; + } +#banner, #banner td { + vertical-align: middle; + } +body.docs, body.nonav { + margin: 1em + } diff --git a/src/documentation/skins/poi-site/images/add.jpg b/src/documentation/skins/poi-site/images/add.jpg new file mode 100644 index 0000000000..06831eeb3d Binary files /dev/null and b/src/documentation/skins/poi-site/images/add.jpg differ diff --git a/src/documentation/skins/poi-site/images/built-with-forrest-button.png b/src/documentation/skins/poi-site/images/built-with-forrest-button.png new file mode 100644 index 0000000000..4a787abe4d Binary files /dev/null and b/src/documentation/skins/poi-site/images/built-with-forrest-button.png differ diff --git a/src/documentation/skins/poi-site/images/favicon.ico b/src/documentation/skins/poi-site/images/favicon.ico new file mode 100644 index 0000000000..161bcf7841 Binary files /dev/null and b/src/documentation/skins/poi-site/images/favicon.ico differ diff --git a/src/documentation/skins/poi-site/images/note.gif b/src/documentation/skins/poi-site/images/note.gif new file mode 100644 index 0000000000..83ce9ec312 Binary files /dev/null and b/src/documentation/skins/poi-site/images/note.gif differ diff --git a/src/documentation/skins/poi-site/images/nw_maj_rond.gif b/src/documentation/skins/poi-site/images/nw_maj_rond.gif new file mode 100644 index 0000000000..add42a4024 Binary files /dev/null and b/src/documentation/skins/poi-site/images/nw_maj_rond.gif differ diff --git a/src/documentation/skins/poi-site/images/nw_min.gif b/src/documentation/skins/poi-site/images/nw_min.gif new file mode 100644 index 0000000000..bf4bc759c4 Binary files /dev/null and b/src/documentation/skins/poi-site/images/nw_min.gif differ diff --git a/src/documentation/skins/poi-site/images/pdfdoc.gif b/src/documentation/skins/poi-site/images/pdfdoc.gif new file mode 100644 index 0000000000..00dee28aad Binary files /dev/null and b/src/documentation/skins/poi-site/images/pdfdoc.gif differ diff --git a/src/documentation/skins/poi-site/images/printer.gif b/src/documentation/skins/poi-site/images/printer.gif new file mode 100644 index 0000000000..5021187b06 Binary files /dev/null and b/src/documentation/skins/poi-site/images/printer.gif differ diff --git a/src/documentation/skins/poi-site/images/remove.jpg b/src/documentation/skins/poi-site/images/remove.jpg new file mode 100644 index 0000000000..8c9b9efa8f Binary files /dev/null and b/src/documentation/skins/poi-site/images/remove.jpg differ diff --git a/src/documentation/skins/poi-site/images/spacer.gif b/src/documentation/skins/poi-site/images/spacer.gif new file mode 100644 index 0000000000..35d42e808f Binary files /dev/null and b/src/documentation/skins/poi-site/images/spacer.gif differ diff --git a/src/documentation/skins/poi-site/images/strich.gif b/src/documentation/skins/poi-site/images/strich.gif new file mode 100644 index 0000000000..a33e79d96b Binary files /dev/null and b/src/documentation/skins/poi-site/images/strich.gif differ diff --git a/src/documentation/skins/poi-site/images/update.jpg b/src/documentation/skins/poi-site/images/update.jpg new file mode 100644 index 0000000000..beb9207336 Binary files /dev/null and b/src/documentation/skins/poi-site/images/update.jpg differ diff --git a/src/documentation/skins/poi-site/images/valid-html401.png b/src/documentation/skins/poi-site/images/valid-html401.png new file mode 100644 index 0000000000..3855210c6c Binary files /dev/null and b/src/documentation/skins/poi-site/images/valid-html401.png differ diff --git a/src/documentation/skins/poi-site/images/vcss.png b/src/documentation/skins/poi-site/images/vcss.png new file mode 100644 index 0000000000..9b2f596e01 Binary files /dev/null and b/src/documentation/skins/poi-site/images/vcss.png differ diff --git a/src/documentation/skins/poi-site/images/void.gif b/src/documentation/skins/poi-site/images/void.gif new file mode 100644 index 0000000000..75b945d255 Binary files /dev/null and b/src/documentation/skins/poi-site/images/void.gif differ diff --git a/src/documentation/skins/poi-site/images/xmldoc.gif b/src/documentation/skins/poi-site/images/xmldoc.gif new file mode 100644 index 0000000000..ca1224f61f Binary files /dev/null and b/src/documentation/skins/poi-site/images/xmldoc.gif differ diff --git a/src/documentation/skins/poi-site/xslt/fo/document2fo.xsl b/src/documentation/skins/poi-site/xslt/fo/document2fo.xsl new file mode 100644 index 0000000000..54ce2a7ec2 --- /dev/null +++ b/src/documentation/skins/poi-site/xslt/fo/document2fo.xsl @@ -0,0 +1,32 @@ + + + + + + + + + + + + + diff --git a/src/documentation/skins/poi-site/xslt/html/book2menu.xsl b/src/documentation/skins/poi-site/xslt/html/book2menu.xsl new file mode 100644 index 0000000000..cc6c295d29 --- /dev/null +++ b/src/documentation/skins/poi-site/xslt/html/book2menu.xsl @@ -0,0 +1,65 @@ + + + + + + + + + +
    + +
    +     + + +
    + + +
    +     + + + + +
    + +
    +     + + + + + + + + + + + + + + + + +     diff --git a/src/documentation/skins/poi-site/xslt/html/document2html.xsl b/src/documentation/skins/poi-site/xslt/html/document2html.xsl new file mode 100644 index 0000000000..4c3dd1570b --- /dev/null +++ b/src/documentation/skins/poi-site/xslt/html/document2html.xsl @@ -0,0 +1,291 @@ + + + + + + + + + + + + + + + + + + <xsl:value-of select="header/title"/> + + + NO TITLE + + + + + +
    + + + by  + + ,  + + + + + +
    +     + + +     +     + + + + + + +     + + + + + + + + + + + + + + + + + + + + + + + + +

    + +     + +

    + +     + +

    + +     + +
    + +     +     + +     + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + a + + + b + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +     diff --git a/src/documentation/skins/poi-site/xslt/html/site2xhtml.xsl b/src/documentation/skins/poi-site/xslt/html/site2xhtml.xsl new file mode 100644 index 0000000000..b3b633ed09 --- /dev/null +++ b/src/documentation/skins/poi-site/xslt/html/site2xhtml.xsl @@ -0,0 +1,262 @@ + + + + + + + + + + + + *** This is a generated file. Do not edit. *** + + + + + + + <xsl:value-of select="/site/document/title" /> + + + + + + ================= start Banner ================== + + ================= end Banner ================== + + ================= start Main ================== + + + ================= start Status ================== + + + + + + + ================= end Status ================== + + + + + + ================= start Menu ================== + + ================= end Menu ================== + + ================= start Content ================== + + ================= end Content ================== + + +
    + + +
    + + + + + + + + + + + + + + + + +
    + Search +
    + + + + + + +
    +
    +     +     		+
    +
    +
    +

    + +

    +     +
    +
    + +
    +
    +
    +
    + ================= end Main ================== + + ================= start Footer ================== + + ================= end Footer ================== + + + +     + +     diff --git a/src/documentation/skins/poi-site/xslt/html/tab2menu.xsl b/src/documentation/skins/poi-site/xslt/html/tab2menu.xsl new file mode 100644 index 0000000000..202424115c --- /dev/null +++ b/src/documentation/skins/poi-site/xslt/html/tab2menu.xsl @@ -0,0 +1,123 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + | + + + + + + + | XML + + + + + | PDF + + + + + | + + + + + + + + + + + + + + + + + + + + + + +