--- /dev/null
+<?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>
projects / poi.git / commitdiff