DOCSEARCHbyAlgolia
Submit Docs

Apache POI Documentation

repository·trunk·Indexed 25 days ago

https://github.com/apache/poi

A Java library for reading and writing Microsoft Office binary (OLE2) and XML-based (OOXML) file formats. It supports Excel (HSSF, XSSF, SXSSF), Word (HWPF, XWPF), PowerPoint (HSLF, XSLF), Outlook, Visio, and Publisher. The library provides various JARs including poi-ooxml and poi-scratchpad, and offers an OSGi Bundle for bare OSGi containers. Current development (6.0.0) requires Java 11 or later, while versions 4 and 5 require Java 8 or later.

Tokens
1.5K
Snippets
1
Records
8
Agent score
79%

What's inside Apache POI

  1. Overview of Apache POI components and formats

    trunk

    Apache POI is a Java library for reading and writing Microsoft Office file formats. It supports two primary underlying formats:

    1. OLE2 (Binary Formats): Uses components named with the H??F prefix (e.g., HSSF for Excel, HWPF for Word, HSLF for PowerPoint). These handle legacy Microsoft Office files like XLS, DOC, and PPT.
    2. OOXML (Open XML Formats): Uses components named with the X??F prefix (e.g., XSSF for Excel, XWPF for Word, XSLF for PowerPoint). These handle modern standards-based formats like XLSX, DOCX, and PPTX.

    Supported Applications:

    • Excel: HSSF (Binary), XSSF (OOXML), and SXSSF (Streaming OOXML).
    • Word: HWPF (Binary) and XWPF (OOXML).
    • PowerPoint: HSLF (Binary) and XSLF (OOXML).
    • Outlook: HSMF and HMEF.
    • Visio: HDGF and XDGF.
    • Publisher: HPBF.
    • Other: TNEF (HMEF) for Outlook winmail.dat files.

  2. Use the Apache POI OSGi Bundle

    trunk
    The Apache POI OSGi Bundle is an Uber jar designed for use in bare OSGi containers. It is self-contained and exports all POI classes, XML Beans, OOXML Schemas, and required dependencies. The bundle size is approximately 21 MB.

  3. Check Java version compatibility

    trunk

    Ensure your development environment meets the following requirements:

    • Current Development (6.0.0): Requires Java 11 or later.
    • POI 4 and 5 releases: Require Java 8 or later.

  4. How Entry types (DocumentEntry vs DirectoryEntry) work

    trunk

    In an OLE2 filesystem, every Entry is either a DocumentEntry or a DirectoryEntry.

    • DocumentEntry: Represents a file or a specific data block within the filesystem.
    • DirectoryEntry: Represents a directory that can contain other entries.

    You can distinguish between them using isDirectoryEntry() and isDocumentEntry(). If you need to traverse the tree, getParent() returns the DirectoryEntry that owns the current entry (returns null if the entry is the root).

  5. Configure optional dependencies for the Apache POI OSGi Bundle

    trunk

    While the bundle is self-contained for core functionality, certain features require additional OSGi bundles to be present in your container. Depending on your use case, you may need to provide the following:

    Image Rendering (WMF/EMF)

    To render WMF/EMF images, you must provide Apache Batik.

    • Available via ServiceMix on Maven Central: org.apache.servicemix.bundles:org.apache.servicemix.bundles.batik:1.14_1

    XML Beans XSLT/XQuery

    If using XML Beans as an XSLT and XQuery Processor engine, you must provide Saxon.

    • Available on Maven Central: net.sf.saxon:Saxon-HE:12.3

    Digital Signatures and Validation

    To sign or validate signed Office documents, you must provide the following bundles:

    • Apache XML Security for Java: org.apache.santuario:xmlsec:3.0.6
    • XML Commons Resolver: xml-resolver:xml-resolver:1.2-osgi
    • Bouncy Castle: org.bouncycastle:bcprov-ext-jdk18on:1.84 and org.bouncycastle:bcpkix-jdk18on:1.84

    PDF Rendering

    To render to PDF documents, you must provide PDFBox and PDFBox Graphics2D.

    • PDFBox: org.apache.pdfbox:pdfbox and org.apache.pdfbox:fontbox
    • PDFBox Graphics2D: de.rototor.pdfbox:graphics2d

  6. Identify the required JAR files for your project

    trunk

    When adding Apache POI to your project via a build tool (like Maven or Gradle), choose the JARs based on the file formats you need to support:

    • poi: The main JAR containing shared interfaces.
    • poi-ooxml: Required for supporting modern OOXML file formats (X**F).
    • poi-scratchpad: Provides extra classes to support legacy MS file formats (H**F).
    • poi-ooxml-lite: A lightweight version of OOXML support containing only the most commonly used classes.
    • poi-ooxml-full: A complete version of OOXML support based on MS XSDs; use this instead of poi-ooxml-lite if you need support for less common features.
    • poi-excelant: Tools for working with Excel files in Apache Ant scripts.
    • poi-examples: Example code implementations.

    You can find specific dependency definitions for your build tool at mvnrepository.com/artifact/org.apache.poi.

  7. Use the Entry interface to manage OLE2 filesystem objects

    trunk

    The org.apache.poi.poifs.filesystem.Entry interface is the base type for all objects managed within an OLE2 filesystem. Entries are categorized into two types: DocumentEntry (representing data/files) and DirectoryEntry (representing folders). You can use this interface to navigate the filesystem hierarchy, rename entries, or delete them.

    /**
 * This interface provides access to an object managed by a Filesystem
 * instance. Entry objects are further divided into DocumentEntry and
 * DirectoryEntry instances.
 */
public interface Entry {
    public String getName();
    public boolean isDirectoryEntry();
    public boolean isDocumentEntry();
    public DirectoryEntry getParent();
    public boolean delete();
    public boolean renameTo(final String newName);
}

  8. Delete or rename an Entry

    trunk

    You can modify the filesystem structure using the following methods on an Entry object:

    Deleting an Entry

    Call delete() to remove the entry. Note the following constraints:

    • The root entry cannot be deleted.
    • A directory can only be deleted if it is empty.
    • The method returns true if successful, false otherwise.

    Renaming an Entry

    Call renameTo(String newName) to change the entry's name. Note the following constraints:

    • You cannot rename the root entry (its name is dictated by the Filesystem).
    • The operation fails if a sibling entry (an entry with the same parent) already exists with the same newName.
    • The method returns true if successful, false otherwise.