mirror of
https://github.com/apache/poi.git
synced 2026-02-27 20:40:08 +08:00
755 lines
29 KiB
HTML
755 lines
29 KiB
HTML
<!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™ - Logging Framework</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> > <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 – 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">
|
|
<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">
|
|
|
|
|
|
</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="menupage">
|
|
<div class="menupagetitle">Logging framework</div>
|
|
</div>
|
|
<div class="menuitem">
|
|
<a href="../components/configuration.html">Configuration</a>
|
|
</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™ - Logging Framework</h1>
|
|
<div id="front-matter"></div>
|
|
|
|
<a name="Introduction"></a>
|
|
<h2 class="boxed">Introduction</h2>
|
|
<div class="section">
|
|
<p>
|
|
Logging in POI is used primarily as a debugging mechanism, not a normal runtime
|
|
logging system. Logging at levels noisier than WARN is ONLY for autopsy type debugging, and should
|
|
NEVER be enabled on a production system.
|
|
</p>
|
|
</div>
|
|
|
|
<a name="POI+5.1.0+and+above"></a>
|
|
<h2 class="boxed">POI 5.1.0 and above</h2>
|
|
<div class="section">
|
|
<p>
|
|
Since version 5.1.0 Apache POI uses <a href="https://logging.apache.org/log4j/2.x/">Apache Log4j v2</a> directly.
|
|
</p>
|
|
<p>
|
|
Apache POI only depends on log4j-api and allows choosing which logging framework to use. log4j-core is
|
|
just one of many options.
|
|
If you want to continue to use another SLF4J compatible logging framework, you can deploy the
|
|
<a href="https://logging.apache.org/log4j/log4j-2.2/log4j-to-slf4j/index.html">log4j-to-slf4j</a> jar to
|
|
facilitate this.
|
|
</p>
|
|
<p>
|
|
POI tries to name loggers after the canonical name of the containing class. For example,
|
|
<span class="codefrag">org.apache.poi.poifs.filesystem.POIFSFileSystem</span>. Use your logging framework's typical
|
|
mechanisms for activating and deactivating logging for specific loggers.
|
|
</p>
|
|
<p>
|
|
All loggers are named <span class="codefrag">com.apache.poi.*</span>, so rules applied to <span class="codefrag">com.apache.poi</span>
|
|
will affect all POI loggers.
|
|
</p>
|
|
</div>
|
|
|
|
<a name="Logging+with+Log4j+2+Core"></a>
|
|
<h2 class="boxed">Logging with Log4j 2 Core</h2>
|
|
<div class="section">
|
|
<p>
|
|
Capturing POI logs using Log4j 2 Core is as simple as including the
|
|
<a href="https://logging.apache.org/log4j/2.x/maven-artifacts.html"><span class="codefrag">log4j-core</span></a> JAR in
|
|
your project. POI also has dependencies on libraries that make use of the SLF4J and Apache Commons
|
|
Logging APIs. Gather logs from these dependencies by adding the
|
|
<a href="https://logging.apache.org/log4j/2.x/log4j-jcl/index.html">Commons Logging Bridge</a> and the
|
|
the <a href="https://logging.apache.org/log4j/2.x/log4j-slf4j-impl/index.html">SLF4J Binding</a> to your
|
|
project.
|
|
</p>
|
|
<p>
|
|
The simplest configuration is to capture all POI logs at the same level as your application. You might
|
|
want to collect all messages <span class="codefrag">INFO</span> and higher, and are OK with capturing POI messages as well.
|
|
</p>
|
|
<div class="code">
|
|
<div class="codeline">
|
|
<span class="lineno"></span><span class="codebody"></span>
|
|
</div>
|
|
<div class="codeline">
|
|
<span class="lineno"></span><span class="codebody"><Configuration ...></span>
|
|
</div>
|
|
<div class="codeline">
|
|
<span class="lineno"></span><span class="codebody"> <Loggers></span>
|
|
</div>
|
|
<div class="codeline">
|
|
<span class="lineno"></span><span class="codebody"> <Root level="INFO"></span>
|
|
</div>
|
|
<div class="codeline">
|
|
<span class="lineno"></span><span class="codebody"> ...</span>
|
|
</div>
|
|
<div class="codeline">
|
|
<span class="lineno"></span><span class="codebody"> </Root></span>
|
|
</div>
|
|
<div class="codeline">
|
|
<span class="lineno"></span><span class="codebody"> </Loggers></span>
|
|
</div>
|
|
<div class="codeline">
|
|
<span class="lineno"></span><span class="codebody"></Configuration></span>
|
|
</div>
|
|
<div class="codeline">
|
|
<span class="lineno"></span><span class="codebody"></span>
|
|
</div>
|
|
</div>
|
|
<p>
|
|
A more recommended configuration is to capture only messages from loggers you opt in to. For example,
|
|
you might want to capture all messages from <span class="codefrag">com.example.myapplication</span> at <span class="codefrag">INFO</span>
|
|
but only POI messages at <span class="codefrag">WARN</span> or more severe.
|
|
</p>
|
|
<div class="code">
|
|
<div class="codeline">
|
|
<span class="lineno"></span><span class="codebody"></span>
|
|
</div>
|
|
<div class="codeline">
|
|
<span class="lineno"></span><span class="codebody"><Configuration ...></span>
|
|
</div>
|
|
<div class="codeline">
|
|
<span class="lineno"></span><span class="codebody"> <Loggers></span>
|
|
</div>
|
|
<div class="codeline">
|
|
<span class="lineno"></span><span class="codebody"> <Logger name="com.example.myapplication" level="INFO" /></span>
|
|
</div>
|
|
<div class="codeline">
|
|
<span class="lineno"></span><span class="codebody"> <Logger name="org.apache.poi" level="WARN" /></span>
|
|
</div>
|
|
<div class="codeline">
|
|
<span class="lineno"></span><span class="codebody"></span>
|
|
</div>
|
|
<div class="codeline">
|
|
<span class="lineno"></span><span class="codebody"> <Root level="OFF"></span>
|
|
</div>
|
|
<div class="codeline">
|
|
<span class="lineno"></span><span class="codebody"> ...</span>
|
|
</div>
|
|
<div class="codeline">
|
|
<span class="lineno"></span><span class="codebody"> </Root></span>
|
|
</div>
|
|
<div class="codeline">
|
|
<span class="lineno"></span><span class="codebody"> </Loggers></span>
|
|
</div>
|
|
<div class="codeline">
|
|
<span class="lineno"></span><span class="codebody"></Configuration></span>
|
|
</div>
|
|
<div class="codeline">
|
|
<span class="lineno"></span><span class="codebody"></span>
|
|
</div>
|
|
</div>
|
|
<p>Another strategy you may decide to use is to capture all messages except those coming from POI.</p>
|
|
<div class="code">
|
|
<div class="codeline">
|
|
<span class="lineno"></span><span class="codebody"></span>
|
|
</div>
|
|
<div class="codeline">
|
|
<span class="lineno"></span><span class="codebody"><Configuration ...></span>
|
|
</div>
|
|
<div class="codeline">
|
|
<span class="lineno"></span><span class="codebody"> <Loggers></span>
|
|
</div>
|
|
<div class="codeline">
|
|
<span class="lineno"></span><span class="codebody"> <Logger name="org.apache.poi" level="OFF" /></span>
|
|
</div>
|
|
<div class="codeline">
|
|
<span class="lineno"></span><span class="codebody"></span>
|
|
</div>
|
|
<div class="codeline">
|
|
<span class="lineno"></span><span class="codebody"> <Root level="INFO"></span>
|
|
</div>
|
|
<div class="codeline">
|
|
<span class="lineno"></span><span class="codebody"> ...</span>
|
|
</div>
|
|
<div class="codeline">
|
|
<span class="lineno"></span><span class="codebody"> </Root></span>
|
|
</div>
|
|
<div class="codeline">
|
|
<span class="lineno"></span><span class="codebody"> </Loggers></span>
|
|
</div>
|
|
<div class="codeline">
|
|
<span class="lineno"></span><span class="codebody"></Configuration></span>
|
|
</div>
|
|
<div class="codeline">
|
|
<span class="lineno"></span><span class="codebody"></span>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
|
|
<a name="Log4J+SimpleLogger"></a>
|
|
<h2 class="boxed">Log4J SimpleLogger</h2>
|
|
<div class="section">
|
|
<p>
|
|
If your main aim is just to get rid of the scary logging log message from Log4J that says
|
|
'ERROR StatusLogger Log4j2 could not find a logging implementation.', then one option is to
|
|
enable the SimpleLogger using a system property.
|
|
</p>
|
|
<p>
|
|
-Dlog4j2.loggerContextFactory=org.apache.logging.log4j.simple.SimpleLoggerContextFactory
|
|
</p>
|
|
</div>
|
|
|
|
<a name="Logging+with+SLF4J"></a>
|
|
<h2 class="boxed">Logging with SLF4J</h2>
|
|
<div class="section">
|
|
<p>
|
|
If you want to continue to use another SLF4J compatible logging framework, you can deploy the
|
|
<a href="https://logging.apache.org/log4j/log4j-2.2/log4j-to-slf4j/index.html">log4j-to-slf4j</a> jar
|
|
and the intended slf4j-bridges to facilitate this.
|
|
</p>
|
|
<p>
|
|
See <a href="https://www.slf4j.org/">https://www.slf4j.org/</a> for more details about using SLF4J.
|
|
</p>
|
|
</div>
|
|
|
|
<a name="Logging+with+Logback"></a>
|
|
<h2 class="boxed">Logging with Logback</h2>
|
|
<div class="section">
|
|
<p>
|
|
Capturing POI logs using Logback requires adding the
|
|
<a href="https://logging.apache.org/log4j/2.x/log4j-to-slf4j/index.html">Log4j to SLF4J Adapter</a> to
|
|
your project, along with the standard Logback dependencies. POI also has dependencies on libraries that
|
|
make use of the SLF4J and Apache Commons Logging APIs. Gather logs from these dependencies by adding the
|
|
<a href="https://www.slf4j.org/legacy.html#jcl-over-slf4j">Commons Logging Bridge</a> to your project.
|
|
</p>
|
|
<p>
|
|
The simplest configuration is to capture all POI logs at the same level as your application. You might
|
|
want to collect all messages <span class="codefrag">INFO</span> and higher, and are OK with capturing POI messages as well.
|
|
</p>
|
|
<div class="code">
|
|
<div class="codeline">
|
|
<span class="lineno"></span><span class="codebody"></span>
|
|
</div>
|
|
<div class="codeline">
|
|
<span class="lineno"></span><span class="codebody"><configuration ...></span>
|
|
</div>
|
|
<div class="codeline">
|
|
<span class="lineno"></span><span class="codebody"> <root level="INFO"></span>
|
|
</div>
|
|
<div class="codeline">
|
|
<span class="lineno"></span><span class="codebody"> ...</span>
|
|
</div>
|
|
<div class="codeline">
|
|
<span class="lineno"></span><span class="codebody"> </root></span>
|
|
</div>
|
|
<div class="codeline">
|
|
<span class="lineno"></span><span class="codebody"></configuration></span>
|
|
</div>
|
|
<div class="codeline">
|
|
<span class="lineno"></span><span class="codebody"></span>
|
|
</div>
|
|
</div>
|
|
<p>
|
|
A more recommended configuration is to capture only messages from loggers you opt in to. For example,
|
|
you might want to capture all messages from <span class="codefrag">com.example.myapplication</span> at <span class="codefrag">INFO</span>
|
|
but only POI messages at <span class="codefrag">WARN</span> or more severe.
|
|
</p>
|
|
<div class="code">
|
|
<div class="codeline">
|
|
<span class="lineno"></span><span class="codebody"></span>
|
|
</div>
|
|
<div class="codeline">
|
|
<span class="lineno"></span><span class="codebody"><configuration ...></span>
|
|
</div>
|
|
<div class="codeline">
|
|
<span class="lineno"></span><span class="codebody"> <logger name="com.example.myapplication" level="INFO" /></span>
|
|
</div>
|
|
<div class="codeline">
|
|
<span class="lineno"></span><span class="codebody"> <logger name="org.apache.poi" level="WARN" /></span>
|
|
</div>
|
|
<div class="codeline">
|
|
<span class="lineno"></span><span class="codebody"></span>
|
|
</div>
|
|
<div class="codeline">
|
|
<span class="lineno"></span><span class="codebody"> <root level="OFF"></span>
|
|
</div>
|
|
<div class="codeline">
|
|
<span class="lineno"></span><span class="codebody"> ...</span>
|
|
</div>
|
|
<div class="codeline">
|
|
<span class="lineno"></span><span class="codebody"> </root></span>
|
|
</div>
|
|
<div class="codeline">
|
|
<span class="lineno"></span><span class="codebody"></configuration></span>
|
|
</div>
|
|
<div class="codeline">
|
|
<span class="lineno"></span><span class="codebody"></span>
|
|
</div>
|
|
</div>
|
|
<p>Another strategy you may decide to use is to capture all messages except those coming from POI.</p>
|
|
<div class="code">
|
|
<div class="codeline">
|
|
<span class="lineno"></span><span class="codebody"></span>
|
|
</div>
|
|
<div class="codeline">
|
|
<span class="lineno"></span><span class="codebody"><configuration ...></span>
|
|
</div>
|
|
<div class="codeline">
|
|
<span class="lineno"></span><span class="codebody"> <logger name="org.apache.poi" level="OFF" /></span>
|
|
</div>
|
|
<div class="codeline">
|
|
<span class="lineno"></span><span class="codebody"></span>
|
|
</div>
|
|
<div class="codeline">
|
|
<span class="lineno"></span><span class="codebody"> <root level="INFO"></span>
|
|
</div>
|
|
<div class="codeline">
|
|
<span class="lineno"></span><span class="codebody"> ...</span>
|
|
</div>
|
|
<div class="codeline">
|
|
<span class="lineno"></span><span class="codebody"> </root></span>
|
|
</div>
|
|
<div class="codeline">
|
|
<span class="lineno"></span><span class="codebody"></configuration></span>
|
|
</div>
|
|
<div class="codeline">
|
|
<span class="lineno"></span><span class="codebody"></span>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
|
|
<a name="POI+5.0.0"></a>
|
|
<h2 class="boxed">POI 5.0.0</h2>
|
|
<div class="section">
|
|
<p>
|
|
POI 5.0.0 switched to using <a href="https://www.slf4j.org/">SLF4J</a> for logging. If you want
|
|
to enable logging, please read up on the various SLF4J compatible logging frameworks.
|
|
<a href="https://logging.apache.org/log4j/2.x/">Apache Log4j v2</a> is a good choice.
|
|
<a href="https://logback.qos.ch/">Logback</a> is also widely used.
|
|
</p>
|
|
</div>
|
|
|
|
<a name="Legacy+POI+Logging+Framework+%28no+longer+supported+in+POI+5.0.0+and+above%29"></a>
|
|
<h2 class="boxed">Legacy POI Logging Framework (no longer supported in POI 5.0.0 and above)</h2>
|
|
<div class="section">
|
|
<p>
|
|
Prior to POI 5.0.0, POI used a custom logging framework which allows to configure where logs are sent to.
|
|
</p>
|
|
<p>
|
|
Logging in POI 3 and 4 is used only as a debugging mechanism, not as a normal runtime
|
|
logging system. Logging at level debug/info is ONLY for debugging, and should
|
|
NEVER be enabled on a production system.
|
|
</p>
|
|
<p>
|
|
The framework is extensible so that you can send log messages to any logging framework
|
|
that your application uses.
|
|
</p>
|
|
<p>
|
|
A number of default logging implementations are supported by POI out-of-the-box and can be selected via a
|
|
system property.
|
|
</p>
|
|
</div>
|
|
|
|
<a name="POI+4.x+and+before%3A+Enable+Legacy+POI+Logging+Framework"></a>
|
|
<h2 class="boxed">POI 4.x and before: Enable Legacy POI Logging Framework</h2>
|
|
<div class="section">
|
|
<p>
|
|
By default, logging is disabled in POI 3 and 4. Sometimes, it might be useful
|
|
to enable logging to see some debug messages printed out which can
|
|
help in analyzing problems.
|
|
</p>
|
|
<p>
|
|
You can select the logging framework by setting the system property <em>org.apache.poi.util.POILogger</em> during application startup or by calling System.setProperty():
|
|
</p>
|
|
<div class="code">
|
|
<div class="codeline">
|
|
<span class="lineno"></span><span class="codebody"></span>
|
|
</div>
|
|
<div class="codeline">
|
|
<span class="lineno"></span><span class="codebody">System.setProperty("org.apache.poi.util.POILogger", "org.apache.poi.util.CommonsLogger" );</span>
|
|
</div>
|
|
<div class="codeline">
|
|
<span class="lineno"></span><span class="codebody"></span>
|
|
</div>
|
|
</div>
|
|
<p>
|
|
Note: You need to call <em>setProperty()</em> before any POI functionality is invoked as the logger is only initialized during startup.
|
|
</p>
|
|
</div>
|
|
|
|
<a name="POI+4.x+and+before%3A+Available+Legacy+POI+Logging+Framework+implementations"></a>
|
|
<h2 class="boxed">POI 4.x and before: Available Legacy POI Logging Framework implementations</h2>
|
|
<div class="section">
|
|
<p>
|
|
The following logger implementations are provided by POI 3 and 4:
|
|
</p>
|
|
<table class="ForrestTable" cellspacing="1" cellpadding="4">
|
|
|
|
<tr>
|
|
|
|
<th colspan="1" rowspan="1">Class</th>
|
|
<th colspan="1" rowspan="1">Type</th>
|
|
|
|
</tr>
|
|
|
|
<tr>
|
|
|
|
<td colspan="1" rowspan="1">org.apache.poi.util.SystemOutLogger</td>
|
|
<td colspan="1" rowspan="1">Sends log output to the system console</td>
|
|
|
|
</tr>
|
|
|
|
<tr>
|
|
|
|
<td colspan="1" rowspan="1">org.apache.poi.util.NullLogger</td>
|
|
<td colspan="1" rowspan="1">Default logger, does not log anything</td>
|
|
|
|
</tr>
|
|
|
|
<tr>
|
|
|
|
<td colspan="1" rowspan="1">org.apache.poi.util.CommonsLogger</td>
|
|
<td colspan="1" rowspan="1">Allows to use <a href="https://commons.apache.org/proper/commons-logging/">Apache Commons Logging</a> for logging. This can use JDK1.4 logging,
|
|
log4j, logkit, etc. The log4j dependency was removed in POI 5.0.0, so you will need to include this dependency yourself if you need it.</td>
|
|
|
|
</tr>
|
|
|
|
<tr>
|
|
|
|
<td colspan="1" rowspan="1">org.apache.poi.util.DummyPOILogger</td>
|
|
<td colspan="1" rowspan="1">Simple logger which will keep all log-lines in memory for later analysis (this class is not in the jar, just in the test source).
|
|
Used primarily for testing. Note: this may cause a memory leak if used in production application!</td>
|
|
|
|
</tr>
|
|
|
|
</table>
|
|
</div>
|
|
|
|
<a name="POI+4.x+and+before%3A+Sending+logs+to+a+different+log+framework"></a>
|
|
<h2 class="boxed">POI 4.x and before: Sending logs to a different log framework</h2>
|
|
<div class="section">
|
|
<p>
|
|
You can send logs to other logging frameworks by implementing the interface <em>org.apache.poi.util.POILogger</em>.
|
|
</p>
|
|
</div>
|
|
|
|
<a name="POI+4.x+and+before%3A+Implementation+details"></a>
|
|
<h2 class="boxed">POI 4.x and before: Implementation details</h2>
|
|
<div class="section">
|
|
<p>
|
|
Every class uses a <span class="codefrag">POILogger</span> to log, and gets it using a static method
|
|
of the <span class="codefrag">POILogFactory</span> .
|
|
</p>
|
|
<p>
|
|
Each class in POI can log using a <span class="codefrag">POILogger</span>, which is an abstract class.
|
|
We decided to make our own logging facade because:</p>
|
|
<ol>
|
|
|
|
<li>we need to log many values and we put many methods in this class to facilitate the
|
|
programmer, without having him write string concatenations;</li>
|
|
|
|
<li>we need to be able to use POI without any logger package present.</li>
|
|
|
|
</ol>
|
|
</div>
|
|
|
|
<p align="right">
|
|
<font size="-2">by Dominik Stadler, Marius Volkhart</font>
|
|
</p>
|
|
</div>
|
|
<!--+
|
|
|end content
|
|
+-->
|
|
<div class="clearboth"> </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 ©
|
|
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/logging.html">dev@poi.apache.org</a>
|
|
</div>
|
|
<!--+
|
|
|end bottomstrip
|
|
+-->
|
|
</div>
|
|
</body>
|
|
</html>
|