Added info on latest logging system.

git-svn-id: https://svn.apache.org/repos/asf/jakarta/poi/trunk@352703 13f79535-47bb-0310-9956-ffa450edef68
This commit is contained in:
Nicola Ken Barozzi 2002-06-15 15:38:29 +00:00
parent 4a34e13429
commit c5285fb57e
2 changed files with 84 additions and 0 deletions

View File

@ -9,6 +9,11 @@
<menu-item label="Main" href="../index.html"/>
</menu>
<menu label="POI Util">
<menu-item label="Overview" href="index.html"/>
<menu-item label="Logging" href="logging.html"/>
</menu>
</book>

View File

@ -0,0 +1,79 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "../dtd/document-v11.dtd">
<document>
<header>
<title>Poi Utils</title>
<subtitle>Overview</subtitle>
<authors>
<person name="Nicola Ken Barozzi" email="nicolaken@apache.org"/>
</authors>
</header>
<body>
<section title="Logging">
<p>
Logging in POI is used only as a debugging mechanism, not a normal runtime
logging system.
</p>
<p>
Hence, we need to be able to easily disable it entirely and make POI not dependent
on any logging package.
</p>
<warning>
POI is not dependent on commons-logging for running, but not for compiling.
</warning>
<section title="Logging Overview">
<p>
Every class uses a <code>POILogger</code> to log, and gets it using a static method
of the <code>POILogFactory</code> .
</p>
<p>
The <code>POILogFactory</code> uses the <code>NullLogger</code> by default;
it can be instructed to use any other <code>POILogger</code> implementation
by setting the system property <code>org.apache.poi.util.POILogger</code>.
</p>
<note> java -Dorg.apache.poi.util.POILogger=the.package.of.MyPoiLoggerImpl ProgramThatUsesPoi
</note>
<fixme author="nicolaken"> Still needs testing.
</fixme>
</section>
<section title="POILogFactory">
<p>
Each class in POI can get its <code>POILogger</code> by calling a static method
of the <code>POILogFactory</code> .
</p>
</section>
<section title="POILogger">
<p>
Each class in POI can log using a <code>POILogger</code>, 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>
<p>There are three implementations available, and you can roll out your own, just
extend <code>org.apache.poi.util.POILogger</code>.
</p>
<section title="NullLogger">
<p>Discards every logging request.</p>
</section>
<section title="SystemOutLogger">
<p>Sends every logging request to System.out.</p>
</section>
<section title="CommonsLogger">
<p>Sends every logging request to the Commons Logging package. This can use JDK1.4 logging,
log4j, logkit, and is an actively maintained Jakarta Project.</p>
</section>
</section>
</section>
</body>
</document>