<?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"/>     
   <person name="Andrew C. Oliver" email="acoliver@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.  Logging is ONLY for autopsie type debugging, and should 
    NEVER be enabled on a production system.  Enabling logging will reduce 
    performance by at least a factor of 100.  If you are not developing 
    POI or trying to debug why POI isn't reading a file correctly, then DO 
    NOT enable logging.  You've been warned. 
  </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>
