<?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 V2.0//EN" "document-v20.dtd">

<document>
  <header>
    <title>Apache POI - Component Overview</title>
    <authors>
      <person id="AO" name="Andrew C. Oliver" email="acoliver@apache.org"/>
      <person id="RK" name="Rainer Klute" email="klute@apache.org"/>
      <person id="DF" name="David Fisher" email="dfisher@jmlafferty.com"/>
    </authors>
  </header>
  <body>
    <section><title>Apache POI Project Components</title>
      <p>The Apache POI project is the master project for developing pure
        Java ports of file formats based on Microsoft's OLE 2 Compound
        Document Format.  OLE 2 Compound Document Format is used by
        Microsoft Office Documents, as well as by programs using MFC
        property sets to serialize their document objects.
      </p>
      <p>Apache POI is also the master project for developing pure
        Java ports of file formats based on Office Open XML (ooxml). 
        OOXML is part of an ECMA / ISO standardisation effort. This
        documentation is quite large, but you can normally find the bit you
        need without too much effort!
        <a href="http://www.ecma-international.org/publications/standards/Ecma-376.htm">ECMA-376 standard is here</a>,
        and is also under the 
        <a href="https://msdn.microsoft.com/en-us/openspecifications/default">Microsoft OSP</a>.
      </p>
    
    
      <section><title>POIFS for OLE 2 Documents</title>
        <p>
	  POIFS is the oldest and most stable part of POI.  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 for the binary (non-XML)
          Microsoft Office formats ultimately rely on it by
          definition.  Please see <a href="./poifs/index.html">the POIFS project page</a> for more information.
	</p>
      </section>
      <section><title>HSSF and XSSF for Excel Documents</title>
        <p>
	  HSSF is our port of the Microsoft Excel 97 (-2003) 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
          <a href="site:spreadsheet">the HSSF+XSSF project page</a> for more
          information.
	</p>
      </section>
      <section><title>HWPF and XWPF for Word Documents</title>
	<p>
	  HWPF is our port of the Microsoft Word 97 (-2003) file format to pure
	  Java.  It supports read, and limited write capabilities. It also provides
      simple text extraction support for the older Word 6 and Word 95 formats.
      Please see <a href="site:document">the HWPF project page for more
	    information</a>.  This component remains in early stages of
	  development. It can already read and write simple files.
	</p>
	<p>
	  We are also working on the XWPF for the WordprocessingML (2007+) format from the 
	  OOXML specification. This provides read and write support for simpler
      files, along with text extraction capabilities.
	</p>
      </section>
      <section><title>HSLF and XSLF for PowerPoint Documents</title>
	<p>
	  HSLF is our port of the Microsoft PowerPoint 97(-2003) file format to pure
	  Java. It supports read and write capabilities. Please see <a
	    href="site:slideshow">the HSLF project page for more
	    information</a>.
	</p>
	<p>
	  We are also working on the XSLF for the PresentationML (2007+) format from the 
	  OOXML specification.
	</p>
      </section>
      <section><title>HPSF for OLE 2 Document Properties</title>
	<p>
	  HPSF is our port of the OLE 2 property set format to pure
	  Java. Property sets are mostly use to store a document's properties
	  (title, author, date of last modification etc.), but they can be used
	  for application-specific purposes as well.
	</p>
	<p>
	  HPSF supports both reading and writing of properties.
	</p>
	<p>
	  Please see <a href="./hpsf/index.html">the HPSF project
	    page</a> for more information.
	</p>
      </section>
      <section><title>HDGF and XDGF for Visio Documents</title>
	<p>
	  HDGF is our port of the Microsoft Visio 97(-2003) file format to pure
	  Java. It currently only supports reading at a very low level, and
	  simple text extraction. Please see <a
	    href="./diagram/index.html">the HDGF / Diagram project page for more
	    information</a>.
	</p>
	<p>
	  XDGF is our port of the Microsoft Visio XML (.vsdx) file format to pure
	  Java. It has slightly more support than HDGF. Please see <a
	    href="./diagram/index.html">the XDGF / Diagram project page for more
	    information</a>.
	</p>
      </section>
      <section><title>HPBF for Publisher Documents</title>
	<p>
	  HPBF is our port of the Microsoft Publisher 98(-2007) file format to pure
	  Java. It currently only supports reading at a low level for around
	  half of the file parts, and simple text extraction.  Please see <a
	    href="./hpbf/index.html">the HPBF project page for more
	    information</a>.
	</p>
      </section>
      <section><title>HMEF for TNEF (winmail.dat) Outlook Attachments</title>
	<p>
     HMEF is our port of the Microsoft TNEF (Transport Neutral Encoding
     Format) file format to pure Java. TNEF is sometimes used by Outlook
     for encoding the message, and will typically come through as
     winmail.dat. HMEF currently only supports reading at a low level, but
     we hope to add text and attachment extraction. Please see <a
	    href="./hmef/index.html">the HMEF project page for more
	    information</a>.
	</p>
      </section>
      <section><title>HSMF for Outlook Messages</title>
	<p>
	  HSMF is our port of the Microsoft Outlook message file format to pure
	  Java. It currently only some of the textual content of MSG files, and
      some attachments. Further support and documentation is coming in slowly.
	  For now, users are advised to consult the unit tests for example use.
	  Please see <a href="./hsmf/index.html">the HSMF project page for more
	    information</a>.
	</p>
	<p>
	  Microsoft has recently added the Outlook file format to its OSP. More information
	  is now available making implementing this API an easier task.
	</p>
      </section>
    </section>
    <section id="components"><title>Component Map</title>
      <p>
        The Apache POI distribution consists of support for many document file formats. This support is provided
        in several Jar files. Not all of the Jars are needed for every format. The following tables
        show the relationships between POI components, Maven repository tags, and the project's Jar files.
      </p>
      <table>
        <tr>
          <th>Component</th>
          <th>Application type</th>
          <th>Maven artifactId</th>
          <th>Notes</th>
        </tr>
        <tr>
          <td><a href="./poifs/index.html">POIFS</a></td>
          <td>OLE2 Filesystem</td>
          <td><em>poi</em></td>
          <td>Required to work with OLE2 / POIFS based files</td>
        </tr>
        <tr>
          <td><a href="./hpsf/index.html">HPSF</a></td>
          <td>OLE2 Property Sets</td>
          <td><em>poi</em></td>
          <td>&nbsp;</td>
        </tr>
        <tr>
          <td><a href="site:spreadsheet">HSSF</a></td>
          <td>Excel XLS</td>
          <td><em>poi</em></td>
          <td>For HSSF only, if common SS is needed see below</td>
        </tr>
        <tr>
          <td><a href="site:slideshow">HSLF</a></td>
          <td>PowerPoint PPT</td>
          <td><em>poi-scratchpad</em></td>
          <td>&nbsp;</td>
        </tr>
        <tr>
          <td><a href="site:document">HWPF</a></td>
          <td>Word DOC</td>
          <td><em>poi-scratchpad</em></td>
          <td>&nbsp;</td>
        </tr>
        <tr>
          <td><a href="./diagram/index.html">HDGF</a></td>
          <td>Visio VSD</td>
          <td><em>poi-scratchpad</em></td>
          <td>&nbsp;</td>
        </tr>
        <tr>
          <td><a href="./hpbf/index.html">HPBF</a></td>
          <td>Publisher PUB</td>
          <td><em>poi-scratchpad</em></td>
          <td>&nbsp;</td>
        </tr>
        <tr>
          <td><a href="./hsmf/index.html">HSMF</a></td>
          <td>Outlook MSG</td>
          <td><em>poi-scratchpad</em></td>
          <td>&nbsp;</td>
        </tr>
        <tr>
          <td>DDF</td>
          <td>Escher common drawings</td>
          <td><em>poi</em></td>
          <td>&nbsp;</td>
        </tr>
        <tr>
          <td>HWMF</td>
          <td>WMF drawings</td>
          <td><em>poi-scratchpad</em></td>
          <td>&nbsp;</td>
        </tr>
        <tr>
          <td><a href="./oxml4j/index.html">OpenXML4J</a></td>
          <td>OOXML</td>
          <td><em>poi-ooxml</em> plus either <em>poi-ooxml-schemas</em> or<br/>
              <em>ooxml-schemas</em> and <em>ooxml-security</em></td>
          <td>See notes below for differences between these options</td>
        </tr>
        <tr>
          <td><a href="site:spreadsheet">XSSF</a></td>
          <td>Excel XLSX</td>
          <td><em>poi-ooxml</em></td>
          <td>&nbsp;</td>
        </tr>
        <tr>
          <td><a href="site:slideshow">XSLF</a></td>
          <td>PowerPoint PPTX</td>
          <td><em>poi-ooxml</em></td>
          <td>&nbsp;</td>
        </tr>
        <tr>
          <td><a href="site:document">XWPF</a></td>
          <td>Word DOCX</td>
          <td><em>poi-ooxml</em></td>
          <td>&nbsp;</td>
        </tr>
        <tr>
          <td><a href="./diagram/index.html">XDGF</a></td>
          <td>Visio VSDX</td>
          <td><em>poi-ooxml</em></td>
          <td>&nbsp;</td>
        </tr>
        <tr>
          <td><a href="./slideshow/index.html">Common SL</a></td>
          <td>PowerPoint PPT and PPTX</td>
          <td><em>poi-scratchpad</em> and <em>poi-ooxml</em></td>
          <td>SL code is in the core POI jar, but implementations are in poi-scratchpad
              and poi-ooxml.</td>
        </tr>
        <tr>
          <td><a href="site:spreadsheet">Common SS</a></td>
          <td>Excel XLS and XLSX</td>
          <td><em>poi-ooxml</em></td>
          <td>WorkbookFactory and friends all require poi-ooxml, not just core poi</td>
        </tr>
      </table>

      <p><br /></p>

      <p>
        This table maps artifacts into the jar file name. "version-yyyymmdd" is 
        the POI version stamp. You can see what the latest stamp is on the
        <a href="site:download">downloads page</a>.
      </p>
      <table>
        <tr>
          <th>Maven artifactId</th>
          <th>Prerequisites</th>
          <th>JAR</th>
        </tr>
        <tr>
          <td>poi</td>
          <td><a href="https://search.maven.org/#artifactdetails|commons-logging|commons-logging|1.2|jar">commons-logging</a>,
              <a href="https://search.maven.org/#artifactdetails|commons-codec|commons-codec|1.11|jar">commons-codec</a>,
              <a href="https://search.maven.org/#artifactdetails|org.apache.commons|commons-collections4|4.2|jar">commons-collections</a> (since POI 3.15 beta 3),
              <a href="https://search.maven.org/#artifactdetails|org.apache.commons|commons-math3|3.6.1|jar">commons-math</a> (since POI 4.0.0),
              <a href="https://search.maven.org/#artifactdetails|log4j|log4j|1.2.17|bundle">log4j</a>
          </td>
          <td>poi-version-yyyymmdd.jar</td>
        </tr>
        <tr>
          <td>poi-scratchpad</td>
          <td><a href="https://search.maven.org/#search|gav|1|g:org.apache.poi AND a:poi">poi</a></td>
          <td>poi-scratchpad-version-yyyymmdd.jar</td>
        </tr>
        <tr>
          <td>poi-ooxml</td>
          <td><a href="https://search.maven.org/#search|gav|1|g:org.apache.poi AND a:poi">poi</a>,
              <a href="https://search.maven.org/#search|gav|1|g:org.apache.poi AND a:poi-ooxml-schemas">poi-ooxml-schemas</a>,
              <a href="https://search.maven.org/#artifactdetails|org.apache.commons|commons-compress|1.18|jar">commons-compress</a> (since POI 4.0.0)<br/>
              For SVG support:
              <a href="https://search.maven.org/#search|gav|1|g:org.apache.xmlgraphics AND a:batik-all">batik-all</a>,
              <a href="https://search.maven.org/#search|gav|1|g:xml-apis AND a:xml-apis-ext">xml-apis-ext</a>,
              <a href="https://search.maven.org/#search|gav|1|g:org.apache.xmlgraphics AND a:xmlgraphics-commons">xmlgraphics-commons</a>
          </td>
          <td>poi-ooxml-version-yyyymmdd.jar</td>
        </tr>
        <tr>
          <td>poi-ooxml-schemas</td>
          <td><a href="https://search.maven.org/#artifactdetails|org.apache.xmlbeans|xmlbeans|3.0.1|jar">xmlbeans</a></td>
          <td>poi-ooxml-schemas-version-yyyymmdd.jar</td>
        </tr>
        <tr>
          <td>poi-examples</td>
          <td><a href="https://search.maven.org/#search|gav|1|g:org.apache.poi AND a:poi">poi</a>, 
              <a href="https://search.maven.org/#search|gav|1|g:org.apache.poi AND a:poi-scratchpad">poi-scratchpad</a>,
              <a href="https://search.maven.org/#search|gav|1|g:org.apache.poi AND a:poi-ooxml">poi-ooxml</a>
          </td>
          <td>poi-examples-version-yyyymmdd.jar</td>
        </tr>
        <tr>
          <td>ooxml-schemas</td>
          <td><a href="https://search.maven.org/#artifactdetails|org.apache.xmlbeans|xmlbeans|3.0.1|jar">xmlbeans</a></td>
          <td><a href="https://search.maven.org/#artifactdetails|org.apache.poi|ooxml-schemas|1.4|jar">ooxml-schemas-1.4.jar</a></td>
        </tr>
        <tr>
          <td>ooxml-security</td>
          <td><a href="https://search.maven.org/#artifactdetails|org.apache.xmlbeans|xmlbeans|3.0.1|jar">xmlbeans</a><br/>
          For signing: 
          <a href="https://search.maven.org/#artifactdetails|org.bouncycastle|bcpkix-jdk15on|1.60|jar">bcpkix-jdk15on</a>,
          <a href="https://search.maven.org/#artifactdetails|org.bouncycastle|bcprov-jdk15on|1.60|jar">bcprov-jdk15on</a>,
          <a href="https://search.maven.org/#artifactdetails|org.apache.santuario|xmlsec|2.1.0|bundle">xmlsec</a>,
          <a href="https://search.maven.org/#artifactdetails|org.slf4j|slf4j-api|1.7.25|jar">slf4j-api</a>
          </td>
          <td><a href="https://search.maven.org/#artifactdetails|org.apache.poi|ooxml-security|1.1|jar">ooxml-security-1.1.jar</a></td>
        </tr>
      </table>

      <p>&nbsp;</p>
      <note><!-- remove this note after 4.0.0 release, as this will be old news then -->
        Apache commons-collections4 was added as a dependency in POI 3.15 beta 3.<br/>
        Apache commons-math3 was added as a dependency in POI 4.0.0.
      </note>
      <p>
        poi-ooxml requires poi-ooxml-schemas. This is a substantially smaller 
        version of the ooxml-schemas jar (ooxml-schemas-1.4.jar for POI 4.0.0 
        or later, ooxml-schemas-1.3.jar for POI 3.14 or to POI 3.17, 
        ooxml-schemas-1.1.jar for POI 3.7 up to POI 3.13, ooxml-schemas-1.0.jar 
        for POI 3.5 and 3.6).
        The larger ooxml-schemas jar is <a href="../help/index.html#faq-N10025">normally</a> 
        only required for development. Similarly, the ooxml-security jar, which contains
        all of the classes relating to encryption and signing, is normally only
        required for development. A subset of its contents are in poi-ooxml-schemas.
        This JAR is ooxml-security-1.1.jar for POI 3.14 onwards and ooxml-security-1.0.jar
        prior to that.
      </p>
      <p>
        The OOXML jars require a stax implementation, but now that Apache
        POI requires Java 8, that dependency is provided by the JRE and no additional
        stax jars are required. The OOXML jars used to require DOM4J, but
        the code has now been changed to use JAXP and no additional dom4j
        jars are required. By the way, look at this <a href="../help/index.html#faq-N1017E">FAQ</a>
        if you have problems when using a non-Oracle JDK.
      </p>
      <p>
        The ooxml schemas jars are compiled with <a href="https://xmlbeans.apache.org/">Apache XMLBeans</a> 2.3, and so
        can be used at runtime with any version of XMLBeans from 3.0.0 or newer.
        Wherever possible though, we recommend that you use XMLBeans 3.0.2
        with Apache POI, and that is the version now shipped in the binary
        release packages.
      </p>
    </section>
    <section><title>Examples</title>
      <p>
	    Small sample programs using the POI API are available in the
        <a href="https://svn.apache.org/repos/asf/poi/trunk/src/examples/src/org/apache/poi/">src/examples</a> 
        (<a href="https://svn.apache.org/viewvc/poi/trunk/src/examples/src/org/apache/poi/">viewvc</a>) directory of the source distribution.
      </p>
        <section><title>POI Browser</title>
          <p>
            The POI Browser is a very simple Swing GUI tool that displays the
            internal structure of a Microsoft Office file and especially the
            property set streams. Further information and  instructions how to
            execute it can be found in the <a
          href="https://svn.apache.org/repos/asf/poi/trunk/src/examples/src/org/apache/poi/poifs/poibrowser/POIBrowser.java">POI
              source code</a> 
              (<a
          href="https://svn.apache.org/viewvc/poi/trunk/src/examples/src/org/apache/poi/poifs/poibrowser/POIBrowser.java">viewvc</a>).
          </p>
        </section>
      <p>
        All of the examples are included in POI distributions as a poi-examples artifact.
      </p>
    </section>
    <section><title>Running POI on other JVM languages</title>
      <p>
        POI can be run on most languages that run on the JVM. For code examples,
        see <a href="poi-jvm-languages.html">Running POI on other JVM languages</a>
      </p>
    </section>
    <section><title>Contributed Software</title>
      <p>
	    Besides the "official" components outlined above there is some further
	    software distributed with POI. This is called "contributed" software. It
        is not explicitly recommended or even maintained by the POI team, but
        it might still be useful to you.
      </p>
      <p>
          See <a href="poi-ruby.html">POI Ruby Bindings</a>  and other code in the
          <a
         href="http://svn.apache.org/repos/asf/poi/trunk/src/contrib/">poi-contrib module</a>
      </p>
    </section>
  </body>
  <footer>
    <legal>
      Copyright (c) @year@ The Apache Software Foundation. All rights reserved.
      <br />
      Apache POI, POI, Apache, the Apache feather logo, and the Apache 
      POI project logo are trademarks of The Apache Software Foundation.
    </legal>
  </footer>
</document>
