src/documentation/content/xdocs/index.xml - poi - Git at Google

 <?xml version="1.0" encoding="UTF-8"?>
 <!--
    ====================================================================
    Licensed to the Apache Software Foundation (ASF) under one or more
    contributor license agreements.  See the NOTICE file distributed with
    this work for additional information regarding copyright ownership.
    The ASF licenses this file to You under the Apache License, Version 2.0
    (the "License"); you may not use this file except in compliance with
    the License.  You may obtain a copy of the License at

        http://www.apache.org/licenses/LICENSE-2.0

    Unless required by applicable law or agreed to in writing, software
    distributed under the License is distributed on an "AS IS" BASIS,
    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    See the License for the specific language governing permissions and
    limitations under the License.
    ====================================================================
 -->
 <!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "./dtd/document-v11.dtd">

 <document>
   <header>
     <title>Apache POI - Java API To Access Microsoft Format Files</title>
     <authors>
       <person id="AO" name="Andrew C. Oliver" email="acoliver@apache.org"/>
       <person id="GJS" name="Glen Stampoultzis" email="user@poi.apache.org"/>
       <person id="AS" name="Avik Sengupta" email="user@poi.apache.org"/>
       <person id="RK" name="Rainer Klute" email="klute@apache.org"/>
     </authors>
   </header>

   <body>
 	<section><title>POI 3.0 Release</title>
 	  <p>After quite a wait, version 3.0 of Apache POI (formerly
 		Apache Jakarta POI) has now been released. You can
 		<link href="./changes.html">view the changelog</link>, and
 		<link href="http://www.apache.org/dyn/closer.cgi/poi/release/">download</link>
 		the source and binaries from your
 		<link href="http://www.apache.org/dyn/closer.cgi/poi/release/">local mirror</link>.</p>
       <p>We would also like to confirm that verion 3.0 of Apache POI does
 		<em>not</em> contain any viruses. Users of broken virus checkers
 		which do detect a 94 byte file, sci_cec.db, as containing one are
 		advised to contact their vendor for a fix.</p>
 	</section>

     <section><title>Purpose</title>
       <p>
       The POI project consists of APIs for manipulating various file formats
       based upon Microsoft's OLE 2 Compound Document format using pure Java.  In short, you can
       read and write MS Excel files using Java.  Soon, you'll be able to read and write
       Word files using Java.  POI is your Java Excel solution as well as your Java Word solution.
       However, we have a complete API for porting other OLE 2 Compound Document formats and welcome
       others to participate.
       </p>
       <p>
       OLE 2 Compound Document Format based files include most Microsoft Office
       files such as XLS and DOC as well as MFC serialization API based file formats.
       </p>
       <p>
          As a general policy we try to collaborate as much as possible with other projects to
          provide this functionality.  Examples include: <link href="http://xml.apache.org/cocoon">Cocoon</link> for
          which there are serializers for HSSF;
          <link href="http://www.openoffice.org">Open Office.org</link> with whom we collaborate in documenting the
          XLS format; and <link href="http://lucene.apache.org/">Lucene</link>
          for which we provide format interpretors.  When practical, we donate
          components directly to those projects for POI-enabling them.
       </p>
       <section><title>Why/when would I use POI?</title>
         <p>
  		We'll tackle this on a component level. POI refers to the whole project.
         </p>
         <p>
 		So why should you use POIFS or HSSF?
         </p>
         <p>
 		You'd use POIFS if you had a document written in OLE 2 Compound Document Format, probably written using
 		MFC, that you needed to read in Java. Alternatively, you'd use POIFS to write OLE 2 Compound Document Format
 		if you needed to inter-operate with software running on the Windows platform. We are not just bragging when
 		we say that POIFS is the most complete and correct implementation of this file format to date!
         </p>
         <p>
 		You'd use HSSF if you needed to read or write an Excel file using Java (XLS). You can also read and modify
 		spreadsheets using this API, although right now writing is more mature.
         </p>
       </section>
     </section>


     <section><title>Components To Date</title>
         <section><title>Overview</title>
 	<p>The following are components of the entire POI project and a brief
 	  summary of their purpose.</p>
         </section>
         <section><title>POIFS for OLE 2 Documents</title>
              <p>POIFS is the oldest and most stable part of the project.  It is our port of the OLE 2 Compound Document Format to
              pure Java.  It supports both read and write functionality.  All of our components ultimately rely on it by
              definition.  Please see <link href="./poifs/index.html">the POIFS project page</link> for more information.</p>
         </section>
         <section><title>HSSF for Excel Documents</title>
              <p>HSSF is our port of the Microsoft Excel 97(-2003) file format (BIFF8) to pure Java.  It supports read and write
              capability.  Please see <link href="./hssf/index.html">the HSSF project page</link> for more information.</p>
         </section>
         <section><title>HWPF for Word Documents</title>
 	<p>HWPF is our port of the Microsoft Word 97 file format to pure
 	  Java.  It supports read, and limited write capabilities. Please see <link
 	    href="./hwpf/index.html">the HWPF project page for more
 	    information</link>.  This component is in the early stages of
 	  development. It can already read and write simple files.</p>
 	<p>Presently we are looking for a contributor to foster the HWPF
 	  development. Jump in!</p>
         </section>
         <section><title>HSLF for PowerPoint Documents</title>
 	<p>HSLF is our port of the Microsoft PowerPoint 97(-2003) file format to pure
 	  Java. It supports read and write capabilities of some, but not yet all
       of the core records. Please see <link
 	    href="./hslf/index.html">the HSLF project page for more
 	    information</link>.</p>
         </section>
         <section><title>HDGF for Visio Documents</title>
 	<p>HDGF is our port of the Microsoft Viso 97(-2003) file format to pure
 	  Java. It currently only supports reading at a very low level, and
       simple text extraction. Please see <link
 	    href="./hdgf/index.html">the HDGF project page for more
 	    information</link>.</p>
         </section>
         <section><title>HPSF for Document Properties</title>
 	<p>HPSF is our port of the OLE 2 property set format to pure
 	  Java. Property sets are mostly use to store a document's properties
 	  (title, author, date of last modification etc.), but they can be used
 	  for application-specific purposes as well.</p>

 	<p>HPSF supports reading and writing of properties. However, you will
       need to be using version 3.0 of POI to utilise the write support.</p>

 	<p>Please see <link href="./hpsf/index.html">the HPSF project
 	    page</link> for more information.</p>
         </section>

      </section>

     <section><title>Contributing </title>
         <p>
 		So you'd like to contribute to the project? Great! We need enthusiastic, hard-working, talented folks to help
 		us on the project in several areas. The first is bug reports and feature requests! The second is documentation -
 		we'll be at your every beck and call if you've got a critique or you'd like to contribute or otherwise improve
 		the documentation. We could especially use some help documenting the HSSF file format! Last, but not least, we
 		could use some binary crunching Java coders to chew through the complexity that characterizes Microsoft's file
 		formats and help us port new ones to a superior Java platform!
         </p>
         <p>So if you're motivated, ready, and have the time, join the mail lists and we'll be happy to help you get started on the
            project!
         </p>


     </section>
   </body>
   <footer>
     <legal>
       Copyright (c) @year@ The Apache Software Foundation. All rights reserved.
       $Revision$ $Date$
     </legal>
   </footer>
 </document>

 <!-- Keep this comment at the end of the file
 Local variables:
 mode: xml
 sgml-omittag:nil
 sgml-shorttag:nil
 sgml-namecase-general:nil
 sgml-general-insert-case:lower
 sgml-minimize-attributes:nil
 sgml-always-quote-attributes:t
 sgml-indent-step:2
 sgml-indent-data:t
 sgml-parent-document:nil
 sgml-exposed-tags:nil
 sgml-local-catalogs:nil
 sgml-local-ecat-files:nil
 End:
 -->
	<?xml version="1.0" encoding="UTF-8"?>
	<!--
	====================================================================
	Licensed to the Apache Software Foundation (ASF) under one or more
	contributor license agreements. See the NOTICE file distributed with
	this work for additional information regarding copyright ownership.
	The ASF licenses this file to You under the Apache License, Version 2.0
	(the "License"); you may not use this file except in compliance with
	the License. You may obtain a copy of the License at

	http://www.apache.org/licenses/LICENSE-2.0

	Unless required by applicable law or agreed to in writing, software
	distributed under the License is distributed on an "AS IS" BASIS,
	WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
	See the License for the specific language governing permissions and
	limitations under the License.
	====================================================================
	-->
	<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "./dtd/document-v11.dtd">

	<document>
	<header>
	<title>Apache POI - Java API To Access Microsoft Format Files</title>
	<authors>
	<person id="AO" name="Andrew C. Oliver" email="acoliver@apache.org"/>
	<person id="GJS" name="Glen Stampoultzis" email="user@poi.apache.org"/>
	<person id="AS" name="Avik Sengupta" email="user@poi.apache.org"/>
	<person id="RK" name="Rainer Klute" email="klute@apache.org"/>
	</authors>
	</header>

	<body>
	<section><title>POI 3.0 Release</title>
	<p>After quite a wait, version 3.0 of Apache POI (formerly
	Apache Jakarta POI) has now been released. You can
	<link href="./changes.html">view the changelog</link>, and
	<link href="http://www.apache.org/dyn/closer.cgi/poi/release/">download</link>
	the source and binaries from your
	<link href="http://www.apache.org/dyn/closer.cgi/poi/release/">local mirror</link>.</p>
	<p>We would also like to confirm that verion 3.0 of Apache POI does
	<em>not</em> contain any viruses. Users of broken virus checkers
	which do detect a 94 byte file, sci_cec.db, as containing one are
	advised to contact their vendor for a fix.</p>
	</section>

	<section><title>Purpose</title>
	<p>
	The POI project consists of APIs for manipulating various file formats
	based upon Microsoft's OLE 2 Compound Document format using pure Java. In short, you can
	read and write MS Excel files using Java. Soon, you'll be able to read and write
	Word files using Java. POI is your Java Excel solution as well as your Java Word solution.
	However, we have a complete API for porting other OLE 2 Compound Document formats and welcome
	others to participate.
	</p>
	<p>
	OLE 2 Compound Document Format based files include most Microsoft Office
	files such as XLS and DOC as well as MFC serialization API based file formats.
	</p>
	<p>
	As a general policy we try to collaborate as much as possible with other projects to
	provide this functionality. Examples include: <link href="http://xml.apache.org/cocoon">Cocoon</link> for
	which there are serializers for HSSF;
	<link href="http://www.openoffice.org">Open Office.org</link> with whom we collaborate in documenting the
	XLS format; and <link href="http://lucene.apache.org/">Lucene</link>
	for which we provide format interpretors. When practical, we donate
	components directly to those projects for POI-enabling them.
	</p>
	<section><title>Why/when would I use POI?</title>
	<p>
	We'll tackle this on a component level. POI refers to the whole project.
	</p>
	<p>
	So why should you use POIFS or HSSF?
	</p>
	<p>
	You'd use POIFS if you had a document written in OLE 2 Compound Document Format, probably written using
	MFC, that you needed to read in Java. Alternatively, you'd use POIFS to write OLE 2 Compound Document Format
	if you needed to inter-operate with software running on the Windows platform. We are not just bragging when
	we say that POIFS is the most complete and correct implementation of this file format to date!
	</p>
	<p>
	You'd use HSSF if you needed to read or write an Excel file using Java (XLS). You can also read and modify
	spreadsheets using this API, although right now writing is more mature.
	</p>
	</section>
	</section>


	<section><title>Components To Date</title>
	<section><title>Overview</title>
	<p>The following are components of the entire POI project and a brief
	summary of their purpose.</p>
	</section>
	<section><title>POIFS for OLE 2 Documents</title>
	<p>POIFS is the oldest and most stable part of the project. It is our port of the OLE 2 Compound Document Format to
	pure Java. It supports both read and write functionality. All of our components ultimately rely on it by
	definition. Please see <link href="./poifs/index.html">the POIFS project page</link> for more information.</p>
	</section>
	<section><title>HSSF for Excel Documents</title>
	<p>HSSF is our port of the Microsoft Excel 97(-2003) file format (BIFF8) to pure Java. It supports read and write
	capability. Please see <link href="./hssf/index.html">the HSSF project page</link> for more information.</p>
	</section>
	<section><title>HWPF for Word Documents</title>
	<p>HWPF is our port of the Microsoft Word 97 file format to pure
	Java. It supports read, and limited write capabilities. Please see <link
	href="./hwpf/index.html">the HWPF project page for more
	information</link>. This component is in the early stages of
	development. It can already read and write simple files.</p>
	<p>Presently we are looking for a contributor to foster the HWPF
	development. Jump in!</p>
	</section>
	<section><title>HSLF for PowerPoint Documents</title>
	<p>HSLF is our port of the Microsoft PowerPoint 97(-2003) file format to pure
	Java. It supports read and write capabilities of some, but not yet all
	of the core records. Please see <link
	href="./hslf/index.html">the HSLF project page for more
	information</link>.</p>
	</section>
	<section><title>HDGF for Visio Documents</title>
	<p>HDGF is our port of the Microsoft Viso 97(-2003) file format to pure
	Java. It currently only supports reading at a very low level, and
	simple text extraction. Please see <link
	href="./hdgf/index.html">the HDGF project page for more
	information</link>.</p>
	</section>
	<section><title>HPSF for Document Properties</title>
	<p>HPSF is our port of the OLE 2 property set format to pure
	Java. Property sets are mostly use to store a document's properties
	(title, author, date of last modification etc.), but they can be used
	for application-specific purposes as well.</p>

	<p>HPSF supports reading and writing of properties. However, you will
	need to be using version 3.0 of POI to utilise the write support.</p>

	<p>Please see <link href="./hpsf/index.html">the HPSF project
	page</link> for more information.</p>
	</section>

	</section>

	<section><title>Contributing </title>
	<p>
	So you'd like to contribute to the project? Great! We need enthusiastic, hard-working, talented folks to help
	us on the project in several areas. The first is bug reports and feature requests! The second is documentation -
	we'll be at your every beck and call if you've got a critique or you'd like to contribute or otherwise improve
	the documentation. We could especially use some help documenting the HSSF file format! Last, but not least, we
	could use some binary crunching Java coders to chew through the complexity that characterizes Microsoft's file
	formats and help us port new ones to a superior Java platform!
	</p>
	<p>So if you're motivated, ready, and have the time, join the mail lists and we'll be happy to help you get started on the
	project!
	</p>


	</section>
	</body>
	<footer>
	<legal>
	Copyright (c) @year@ The Apache Software Foundation. All rights reserved.
	$Revision$ $Date$
	</legal>
	</footer>
	</document>

	<!-- Keep this comment at the end of the file
	Local variables:
	mode: xml
	sgml-omittag:nil
	sgml-shorttag:nil
	sgml-namecase-general:nil
	sgml-general-insert-case:lower
	sgml-minimize-attributes:nil
	sgml-always-quote-attributes:t
	sgml-indent-step:2
	sgml-indent-data:t
	sgml-parent-document:nil
	sgml-exposed-tags:nil
	sgml-local-catalogs:nil
	sgml-local-ecat-files:nil
	End:
	-->