src/documentation/content/xdocs/utils/logging.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!--
   3    ====================================================================
   4    Licensed to the Apache Software Foundation (ASF) under one or more
   5    contributor license agreements.  See the NOTICE file distributed with
   6    this work for additional information regarding copyright ownership.
   7    The ASF licenses this file to You under the Apache License, Version 2.0
   8    (the "License"); you may not use this file except in compliance with
   9    the License.  You may obtain a copy of the License at
  10
  11        http://www.apache.org/licenses/LICENSE-2.0
  12
  13    Unless required by applicable law or agreed to in writing, software
  14    distributed under the License is distributed on an "AS IS" BASIS,
  15    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  16    See the License for the specific language governing permissions and
  17    limitations under the License.
  18    ====================================================================
  19 -->
  20 <!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "../dtd/document-v11.dtd">
  21
  22 <document>
  23  <header>
  24   <title>POI Utils</title>
  25   <subtitle>Overview</subtitle>
  26   <authors>
  27    <person name="Nicola Ken Barozzi" email="nicolaken@apache.org"/>
  28    <person name="Andrew C. Oliver" email="acoliver@apache.org"/>
  29   </authors>
  30  </header>
  31
  32  <body>
  33  <section><title>Logging</title>
  34
  35   <p>
  36     Logging in POI is used only as a debugging mechanism, not a normal runtime
  37     logging system.  Logging is ONLY for autopsie type debugging, and should
  38     NEVER be enabled on a production system.  Enabling logging will reduce
  39     performance by at least a factor of 100.  If you are not developing
  40     POI or trying to debug why POI isn't reading a file correctly, then DO
  41     NOT enable logging.  You've been warned.
  42   </p>
  43
  44   <p>
  45     Hence, we need to be able to easily disable it entirely and make POI not dependent
  46     on any logging package.
  47   </p>
  48
  49   <warning>
  50     POI is not dependent on commons-logging for running, but not for compiling.
  51   </warning>
  52
  53    <section><title>Logging Overview</title>
  54      <p>
  55        Every class uses a <code>POILogger</code> to log, and gets it using a static method
  56        of the <code>POILogFactory</code> .
  57      </p>
  58      <p>
  59        The <code>POILogFactory</code> uses the <code>NullLogger</code> by default;
  60        it can be instructed to use any other <code>POILogger</code> implementation
  61        by setting the system property <code>org.apache.poi.util.POILogger</code>.
  62      </p>
  63      <note> java -Dorg.apache.poi.util.POILogger=the.package.of.MyPoiLoggerImpl ProgramThatUsesPoi
  64      </note>
  65      <fixme author="nicolaken"> Still needs testing.
  66      </fixme>
  67    </section>
  68
  69    <section><title>POILogFactory</title>
  70      <p>
  71        Each class in POI can get its <code>POILogger</code> by calling a static method
  72        of the <code>POILogFactory</code> .
  73      </p>
  74    </section>
  75
  76    <section><title>POILogger</title>
  77      <p>
  78      Each class in POI can log using a <code>POILogger</code>, which is an abstract class.
  79      We decided to make our own logging facade because:</p>
  80      <ol>
  81       <li>we need to log many values and we put many methods in this class to facilitate the
  82           programmer, without having him write string concatenations;</li>
  83       <li>we need to be able to use POI without any logger package present.</li>
  84      </ol>
  85      <p>There are three implementations available, and you can roll out your own, just
  86      extend <code>org.apache.poi.util.POILogger</code>.
  87      </p>
  88    <section><title>NullLogger</title>
  89      <p>Discards every logging request.</p>
  90    </section>
  91    <section><title>SystemOutLogger</title>
  92      <p>Sends every logging request to System.out.</p>
  93    </section>
  94    <section><title>CommonsLogger</title>
  95      <p>Sends every logging request to the Commons Logging package. This can use JDK1.4 logging,
  96      log4j, logkit, and is an actively maintained Jakarta Project.</p>
  97    </section>
  98
  99   </section>
 100   </section>
 101  </body>
 102 </document>