pashko/apache-poi
1
0
Fork 0
mirror of https://github.com/apache/poi.git synced 2026-02-27 20:40:08 +08:00
Code Issues Packages Projects Releases Wiki Activity
apache-poi/content/components/configuration.html
PJ Fanning e901a2c083 publish site
2026-02-16 20:14:18 +01:00

589 lines
21 KiB
HTML
Raw Blame History

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<META http-equiv="Content-Type" content="text/html; charset=UTF-8">
<meta content="Apache Forrest" name="Generator">
<meta name="Forrest-version" content="0.9">
<meta name="Forrest-skin-name" content="pelt">
<title>Apache POI&trade; - Configuration</title>
<link type="text/css" href="../skin/basic.css" rel="stylesheet">
<link media="screen" type="text/css" href="../skin/screen.css" rel="stylesheet">
<link media="print" type="text/css" href="../skin/print.css" rel="stylesheet">
<link type="text/css" href="../skin/profile.css" rel="stylesheet">
<script src="../skin/getBlank.js" language="javascript" type="text/javascript"></script><script src="../skin/getMenu.js" language="javascript" type="text/javascript"></script><script src="../skin/fontsize.js" language="javascript" type="text/javascript"></script>
<link rel="shortcut icon" href="../images/favicon.ico">
</head>
<body onload="init()">
<script type="text/javascript">ndeSetTextSize();</script>
<div id="top">
<!--+
|breadtrail
+-->
<div class="breadtrail">
<a href="https://www.apache.org">Apache Software Foundation</a> &gt; <a href="https://poi.apache.org">Apache POI</a><script src="../skin/breadcrumbs.js" language="JavaScript" type="text/javascript"></script>
</div>
<!--+
|header
+-->
<div class="header">
<!--+
|start group logo
+-->
<div class="grouplogo">
<a href="https://www.apache.org"><img class="logoImage" alt="Apache Software Foundation" src="../images/asflogo_horizontal_color.svg" title="The Apache Software Foundation is a cornerstone of the modern Open Source software ecosystem &ndash; supporting some of the most widely used and important software solutions powering today's Internet economy."></a>
</div>
<!--+
|end group logo
+-->
<!--+
|start Project Logo
+-->
<div class="projectlogo">
<a href="https://poi.apache.org"><img class="logoImage" alt="Apache POI" src="../images/project-header.png" title="Apache POI is well-known in the Java field as a library for reading and writing Microsoft Office file formats, such as Excel, PowerPoint, Word, Visio, Publisher and Outlook. It supports both the older (OLE2) and new (OOXML - Office Open XML) formats."></a>
</div>
<!--+
|end Project Logo
+-->
<!--+
|start Search
+-->
<div class="searchbox">
<form action="https://www.google.com/search" method="get" class="roundtopsmall">
<input value="poi.apache.org" name="sitesearch" type="hidden"><input onFocus="getBlank (this, 'Search the site with google');" size="25" name="q" id="query" type="text" value="Search the site with google">&nbsp;
<input name="Search" value="Search" type="submit">
</form>
</div>
<!--+
|end search
+-->
<!--+
|start Tabs
+-->
<ul id="tabs">
<li>
<a class="unselected" href="../index.html">Home</a>
</li>
<li>
<a class="unselected" href="../help/index.html">Help</a>
</li>
<li class="current">
<a class="selected" href="../components/index.html">Component APIs</a>
</li>
<li>
<a class="unselected" href="../devel/index.html">Getting Involved</a>
</li>
</ul>
<!--+
|end Tabs
+-->
</div>
</div>
<div id="main">
<div id="publishedStrip">
<!--+
|start Subtabs
+-->
<div id="level2tabs"></div>
<!--+
|end Endtabs
+-->
<script type="text/javascript"><!--
document.write("Last Published: " + document.lastModified);
// --></script>
</div>
<!--+
|breadtrail
+-->
<div class="breadtrail">
&nbsp;
</div>
<!--+
|start Menu, mainarea
+-->
<!--+
|start Menu
+-->
<div id="menu">
<div onclick="SwitchMenu('menu_selected_1.1', '../skin/')" id="menu_selected_1.1Title" class="menutitle" style="background-image: url('../skin/images/chapter_open.gif');">Component APIs</div>
<div id="menu_selected_1.1" class="selectedmenuitemgroup" style="display: block;">
<div class="menuitem">
<a href="../components/index.html">Overview</a>
</div>
<div class="menuitem">
<a href="../apidocs/index.html">Javadocs</a>
</div>
<div onclick="SwitchMenu('menu_1.1.3', '../skin/')" id="menu_1.1.3Title" class="menutitle">Excel (HSSF/XSSF)</div>
<div id="menu_1.1.3" class="menuitemgroup">
<div class="menuitem">
<a href="../components/spreadsheet/index.html">Overview</a>
</div>
<div class="menuitem">
<a href="../components/spreadsheet/quick-guide.html">Quick Guide</a>
</div>
<div class="menuitem">
<a href="../components/spreadsheet/how-to.html">HOWTO</a>
</div>
<div class="menuitem">
<a href="../components/spreadsheet/converting.html">HSSF to SS Converting</a>
</div>
<div class="menuitem">
<a href="../components/spreadsheet/formula.html">Formula Support</a>
</div>
<div class="menuitem">
<a href="../components/spreadsheet/eval.html">Formula Evaluation</a>
</div>
<div class="menuitem">
<a href="../components/spreadsheet/eval-devguide.html">Eval Dev Guide</a>
</div>
<div class="menuitem">
<a href="../components/spreadsheet/examples.html">Examples</a>
</div>
<div class="menuitem">
<a href="../components/spreadsheet/use-case.html">Use Case</a>
</div>
<div class="menuitem">
<a href="../components/spreadsheet/diagrams.html">Pictorial Docs</a>
</div>
<div class="menuitem">
<a href="../components/spreadsheet/limitations.html">Limitations</a>
</div>
<div class="menuitem">
<a href="../components/spreadsheet/user-defined-functions.html">User Defined Functions</a>
</div>
<div class="menuitem">
<a href="../components/spreadsheet/excelant.html">ExcelAnt Tests</a>
</div>
<div class="menuitem">
<a href="../components/spreadsheet/hacking-hssf.html">Hacking HSSF</a>
</div>
<div class="menuitem">
<a href="../components/spreadsheet/record-generator.html">Record Generator</a>
</div>
<div class="menuitem">
<a href="../components/spreadsheet/chart.html">Charts</a>
</div>
</div>
<div onclick="SwitchMenu('menu_1.1.4', '../skin/')" id="menu_1.1.4Title" class="menutitle">PowerPoint (HSLF/XSLF)</div>
<div id="menu_1.1.4" class="menuitemgroup">
<div class="menuitem">
<a href="../components/slideshow/index.html">Overview</a>
</div>
<div class="menuitem">
<a href="../components/slideshow/quick-guide.html">Quick Guide</a>
</div>
<div class="menuitem">
<a href="../components/slideshow/how-to-shapes.html">HSLF Cookbook</a>
</div>
<div class="menuitem">
<a href="../components/slideshow/xslf-cookbook.html">XSLF Cookbook</a>
</div>
<div class="menuitem">
<a href="../components/slideshow/ppt-wmf-emf-renderer.html">Render SL/WMF/EMF</a>
</div>
<div class="menuitem">
<a href="../components/slideshow/ppt-file-format.html">PPT File Format</a>
</div>
</div>
<div onclick="SwitchMenu('menu_1.1.5', '../skin/')" id="menu_1.1.5Title" class="menutitle">Word (HWPF/XWPF)</div>
<div id="menu_1.1.5" class="menuitemgroup">
<div class="menuitem">
<a href="../components/document/index.html">Overview</a>
</div>
<div class="menuitem">
<a href="../components/document/quick-guide.html">HWPF Quick Guide</a>
</div>
<div class="menuitem">
<a href="../components/document/quick-guide-xwpf.html">XWPF Quick Guide</a>
</div>
<div class="menuitem">
<a href="../components/document/docoverview.html">HWPF Format</a>
</div>
<div class="menuitem">
<a href="../components/document/projectplan.html">HWPF Project plan</a>
</div>
</div>
<div class="menuitem">
<a href="../components/hsmf/index.html">Outlook (HSMF)</a>
</div>
<div class="menuitem">
<a href="../components/diagram/index.html">Visio (HDGF+XDGF)</a>
</div>
<div onclick="SwitchMenu('menu_1.1.8', '../skin/')" id="menu_1.1.8Title" class="menutitle">Publisher (HPBF)</div>
<div id="menu_1.1.8" class="menuitemgroup">
<div class="menuitem">
<a href="../components/hpbf/index.html">Overview</a>
</div>
<div class="menuitem">
<a href="../components/hpbf/file-format.html">File Format</a>
</div>
</div>
<div onclick="SwitchMenu('menu_1.1.9', '../skin/')" id="menu_1.1.9Title" class="menutitle">OLE2 Filesystem (POIFS)</div>
<div id="menu_1.1.9" class="menuitemgroup">
<div class="menuitem">
<a href="../components/poifs/index.html">Overview</a>
</div>
<div class="menuitem">
<a href="../components/poifs/how-to.html">How To</a>
</div>
<div class="menuitem">
<a href="../components/poifs/embeded.html">Embedded Documents</a>
</div>
<div class="menuitem">
<a href="../components/poifs/fileformat.html">File System Documentation</a>
</div>
<div class="menuitem">
<a href="../components/poifs/usecases.html">Use Cases</a>
</div>
<div class="menuitem">
<a href="../components/poifs/design.html">Design</a>
</div>
</div>
<div onclick="SwitchMenu('menu_1.1.10', '../skin/')" id="menu_1.1.10Title" class="menutitle">OLE2 Document Props (HPSF)</div>
<div id="menu_1.1.10" class="menuitemgroup">
<div class="menuitem">
<a href="../components/hpsf/index.html">Overview</a>
</div>
<div class="menuitem">
<a href="../components/hpsf/how-to.html">How To</a>
</div>
<div class="menuitem">
<a href="../components/hpsf/thumbnails.html">Thumbnails</a>
</div>
<div class="menuitem">
<a href="../components/hpsf/internals.html">Internals</a>
</div>
<div class="menuitem">
<a href="../components/hpsf/todo.html">To Do</a>
</div>
</div>
<div class="menuitem">
<a href="../components/hmef/index.html">TNEF (HMEF) for winmail.dat</a>
</div>
<div class="menuitem">
<a href="../components/oxml4j/index.html">OpenXML4J (OOXML)</a>
</div>
<div class="menuitem">
<a href="../components/logging.html">Logging framework</a>
</div>
<div class="menupage">
<div class="menupagetitle">Configuration</div>
</div>
</div>
<div id="credit"></div>
<div id="roundbottom">
<img style="display: none" class="corner" height="15" width="15" alt="" src="../skin/images/rc-b-l-15-1body-2menu-3menu.png"></div>
<!--+
|alternative credits
+-->
<div id="credit2">
<a href="https://donate.apache.org/"><img border="0" title="Support Apache" alt="Support Apache - logo" src="../images/support-asf.png" style="width: 125px;height: 125px;"></a><a href="https://www.apache.org/foundation/press/kit/#poweredby"><img border="0" title="powered by POI" alt="powered by POI - logo" src="../images/poweredby-poi-logo.png" style="width: 125px;height: 125px;"></a>
</div>
</div>
<!--+
|end Menu
+-->
<!--+
|start content
+-->
<div id="content">
<h1>Apache POI&trade; - Configuration</h1>
<div id="front-matter"></div>
<a name="Overview"></a>
<h2 class="boxed">Overview</h2>
<div class="section">
<p>The best way to learn about using Apache POI is to read through the <a href="index.html">feature documentation</a>
and other online examples online.
</p>
<p>To keep the features documentation focused on the APIs, there is little mention of some of the configuration
settings that can be enabled that may prove useful to users who have to handle very large documents or very
large throughput.
</p>
</div>
<a name="Configuration+via+Java-code+when+calling+Apache+POI"></a>
<h2 class="boxed">Configuration via Java-code when calling Apache POI</h2>
<div class="section">
<p>These API methods allow to configure behavior of Apache POI for special needs, e.g. when processing excessively
large files.
</p>
<table class="ForrestTable" cellspacing="1" cellpadding="4">
<tr>
<th colspan="1" rowspan="1">Configuration Setting</th>
<th colspan="1" rowspan="1">Description</th>
</tr>
<tr>
<td colspan="1" rowspan="1">org.apache.poi.ooxml.POIXMLTypeLoader.DEFAULT_XML_OPTIONS</td>
<td colspan="1" rowspan="1">POI support for XSSF APIs relies heavily on <a href="https://xmlbeans.apache.org">XMLBeans</a>.
This instance can be <a href="https://xmlbeans.apache.org/docs/5.0.0/org/apache/xmlbeans/XmlOptions.html">configured</a>.
It is recommended to take care if you do change any of the config items.
In POI 5.1.0, we will disallow Doc Type parsing in the XML files embedded in xlsx/docx/pptx/etc files, by default.
DEFAULT_XML_OPTIONS.setDisallowDocTypeDeclaration(false) will undo this change.
</td>
</tr>
<tr>
<td colspan="1" rowspan="1"><a href="https://poi.apache.org/apidocs/5.0/org/apache/poi/util/IOUtils.html#setByteArrayMaxOverride-int-">
org.apache.poi.util.IOUtils.setByteArrayMaxOverride(int maxOverride)</a>
</td>
<td colspan="1" rowspan="1">If this value is set to &gt; 0, IOUtils.safelyAllocate(long, int) will ignore the maximum record length parameter.
This is designed to allow users to bypass the hard-coded maximum record lengths if they are willing to accept the risk of allocating memory up to the size specified.
It also allows to impose a lower limit than used for very memory constrained systems.
<p>
<strong>Note</strong>: This is a per-allocation limit and does not allow you to limit overall sum of allocations! Use -1 for using the limits specified per record-type.
</p>
</td>
</tr>
<tr>
<td colspan="1" rowspan="1"><a href="https://poi.apache.org/apidocs/5.0/org/apache/poi/openxml4j/util/ZipSecureFile.html#setMinInflateRatio-double-">
org.apache.poi.openxml4j.util.ZipSecureFile.setMinInflateRatio(double ratio)</a>
</td>
<td colspan="1" rowspan="1">Sets the ratio between de- and inflated bytes to detect zipbomb.
It defaults to 1% (= 0.01d), i.e. when the compression is better than 1% for any given read package part, the parsing will fail indicating a Zip-Bomb.
</td>
</tr>
<tr>
<td colspan="1" rowspan="1"><a href="https://poi.apache.org/apidocs/5.0/org/apache/poi/openxml4j/util/ZipSecureFile.html#setMaxEntrySize-long-">
org.apache.poi.openxml4j.util.ZipSecureFile.setMaxEntrySize(long maxEntrySize)</a>
</td>
<td colspan="1" rowspan="1">Sets the maximum file size of a single zip entry. It defaults to 4GB, i.e. the 32-bit zip format maximum.
This can be used to limit memory consumption and protect against security vulnerabilities when documents are provided by users.
POI 5.1.0 removes the previous limit of 4GB on this setting.
</td>
</tr>
<tr>
<td colspan="1" rowspan="1"><a href="https://poi.apache.org/apidocs/5.0/org/apache/poi/openxml4j/util/ZipSecureFile.html#setMaxTextSize-long-">
org.apache.poi.openxml4j.util.ZipSecureFile.setMaxTextSize(long maxTextSize)</a>
</td>
<td colspan="1" rowspan="1">Sets the maximum number of characters of text that are extracted before an exception is thrown during extracting text from documents.
This can be used to limit memory consumption and protect against security vulnerabilities when documents are provided by users.
The default is approx 10 million chars. Prior to POI 5.1.0, the max allowed was approx 4 billion chars.
</td>
</tr>
<tr>
<td colspan="1" rowspan="1">org.apache.poi.openxml4j.util.ZipInputStreamZipEntrySource.setThresholdBytesForTempFiles(int thresholdBytes)
</td>
<td colspan="1" rowspan="1"><strong>Added in POI 5.1.0.</strong>
Number of bytes at which a zip entry is regarded as too large for holding in memory
and the data is put in a temp file instead - defaults to -1 meaning temp files are not used
and that zip entries with more than 2GB of data after decompressing will fail, 0 means all
zip entries are stored in temp files. A threshold like 50000000 (approx 50Mb is recommended)
</td>
</tr>
<tr>
<td colspan="1" rowspan="1">org.apache.poi.openxml4j.util.ZipInputStreamZipEntrySource.setEncryptTempFiles(boolean encrypt)
</td>
<td colspan="1" rowspan="1"><strong>Added in POI 5.1.0.</strong>
Whether temp files should be encrypted (default false). Only affects temp files related to zip entries.
</td>
</tr>
<tr>
<td colspan="1" rowspan="1">org.apache.poi.openxml4j.opc.ZipPackage.setUseTempFilePackageParts(boolean tempFilePackageParts)
</td>
<td colspan="1" rowspan="1"><strong>Added in POI 5.1.0.</strong>
Whether to save package part data in temp files to save memory (default=false).
</td>
</tr>
<tr>
<td colspan="1" rowspan="1">org.apache.poi.openxml4j.opc.ZipPackage.setEncryptTempFilePackageParts(boolean encryptTempFiles)
</td>
<td colspan="1" rowspan="1"><strong>Added in POI 5.1.0.</strong>
Whether to encrypt package part temp files (default=false).
</td>
</tr>
<tr>
<td colspan="1" rowspan="1">org.apache.poi.extractor.ExtractorFactory.setThreadPrefersEventExtractors(boolean preferEventExtractors) and
org.apache.poi.extractor.ExtractorFactory.setAllThreadsPreferEventExtractors(Boolean preferEventExtractors)
</td>
<td colspan="1" rowspan="1">
When creating text-extractors for documents, allows to choose a different type of extractor which parses documents
via an event-based parser.
</td>
</tr>
<tr>
<td colspan="1" rowspan="1">Various classes: setMaxRecordLength(int length)
</td>
<td colspan="1" rowspan="1">
Allows to override the default max record length for various classes which
parse input data. E.g. XMLSlideShow, XSSFBParser, HSLFSlideShow, HWPFDocument,
HSSFWorkbook, EmbeddedExtractor, StringUtil, ...
<br>
This may be useful if you try to process very large files which otherwise trigger
the excessive-memory-allocation prevention in Apache POI.
</td>
</tr>
<tr>
<td colspan="1" rowspan="1">org.apache.poi.xslf.usermodel.XSLFPictureData.setMaxImageSize(int length)
</td>
<td colspan="1" rowspan="1">
Allows to override the default max image size allowed for XSLF pictures.
</td>
</tr>
<tr>
<td colspan="1" rowspan="1">org.apache.poi.xssf.usermodel.XSSFPictureData#setMaxImageSize(int length)
</td>
<td colspan="1" rowspan="1">
Allows to override the default max image size allowed for XSSF pictures.
</td>
</tr>
<tr>
<td colspan="1" rowspan="1">org.apache.poi.xwpf.usermodel.XWPFPictureData#setMaxImageSize(int length)
</td>
<td colspan="1" rowspan="1">
Allows to override the default max image size allowed for XWPF pictures.
</td>
</tr>
</table>
</div>
<a name="Observed+Java+System+Properties"></a>
<h2 class="boxed">Observed Java System Properties</h2>
<div class="section">
<p>Apache POI supports some Java System Properties.
</p>
<table class="ForrestTable" cellspacing="1" cellpadding="4">
<tr>
<th colspan="1" rowspan="1">System property</th>
<th colspan="1" rowspan="1">Description</th>
</tr>
<tr>
<td colspan="1" rowspan="1">java.io.tmpdir</td>
<td colspan="1" rowspan="1">
Apache POI uses the default mechanism of the JDK for specifying the location of
temporary files.
</td>
</tr>
<tr>
<td colspan="1" rowspan="1">org.apache.poi.hwpf.preserveBinTables and org.apache.poi.hwpf.preserveTextTable</td>
<td colspan="1" rowspan="1">
Allows to adjust how parsing Word documents via HWPF is handling tables.
</td>
</tr>
<tr>
<td colspan="1" rowspan="1">org.apache.poi.ss.ignoreMissingFontSystem</td>
<td colspan="1" rowspan="1"><strong>Added in POI 5.2.3.</strong>
Instructs Apache POI to ignore some errors due to missing fonts and thus allows
to perform more functionality even when no fonts are installed.
<br>
Note: Some functionality will still not be possible as it cannot use default-values, e.g. rendering
slides, drawing, ...
</td>
</tr>
</table>
</div>
<p align="right">
<font size="-2">by&nbsp;POI Developers</font>
</p>
</div>
<!--+
|end content
+-->
<div class="clearboth">&nbsp;</div>
</div>
<div id="footer">
<!--+
|start bottomstrip
+-->
<div class="lastmodified">
<script type="text/javascript"><!--
document.write("Last Published: " + document.lastModified);
// --></script>
</div>
<div class="copyright">
Copyright &copy;
2001-2026 <a href="https://www.apache.org/">The Apache Software Foundation</a>
<br>
Apache POI, POI, Apache, the Apache logo, and the Apache
POI project logo are trademarks of The Apache Software Foundation.
</div>
<div id="feedback">
Send feedback about the website to:
<a id="feedbackto" href="mailto:dev@poi.apache.org?subject=Feedback%C2%A0components/configuration.html">dev@poi.apache.org</a>
</div>
<!--+
|end bottomstrip
+-->
</div>
</body>
</html>
Reference in New Issue View Git Blame Copy Permalink