<?xml version="1.0" encoding="UTF-8"?>
<!--
   ====================================================================
   Licensed to the Apache Software Foundation (ASF) under one or more
   contributor license agreements.  See the NOTICE file distributed with
   this work for additional information regarding copyright ownership.
   The ASF licenses this file to You under the Apache License, Version 2.0
   (the "License"); you may not use this file except in compliance with
   the License.  You may obtain a copy of the License at

       http://www.apache.org/licenses/LICENSE-2.0

   Unless required by applicable law or agreed to in writing, software
   distributed under the License is distributed on an "AS IS" BASIS,
   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   See the License for the specific language governing permissions and
   limitations under the License.
   ====================================================================
-->
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN" "document-v20.dtd">

<document>
    <header>
        <title>Apache POI - Logging Framework</title>
        <authors>
            <person id="DS" name="Dominik Stadler" email="centic@apache.org"/>
        </authors>
    </header>

    <body>
        <section>
            <title>Introduction</title>
            <p>
                POI uses a custom logging framework which allows to configure where logs are sent to.
            </p>
            <p>
                Logging in POI is used only as a debugging mechanism, not a normal runtime
                logging system.  Logging on level debug/info is ONLY for autopsie type 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>
        </section>
        <section><title>Enable logging</title>
        <p>
            By default, logging is disabled in POI. 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>
        <source>
            System.setProperty("org.apache.poi.util.POILogger", "org.apache.poi.util.CommonsLogger" );
        </source>
        <p>
            Note: You need to call <em>setProperty()</em> before any POI functionality is invoked as the logger is only initialized during startup.
        </p>
        </section>
        <section><title>Available logger implementations</title>
            <p>
                The following logger implementations are provided by POI:
            </p>
            <table>
            <tr>
                <th>Class</th>
                <th>Type</th>
            </tr>
            <tr>
                <td>org.apache.poi.util.SystemOutLogger</td>
                <td>Sends log output to the system console</td>
            </tr>
            <tr>
                <td>org.apache.poi.util.NullLogger</td>
                <td>Default logger, does not log anything</td>
            </tr>
            <tr>
                <td>org.apache.poi.util.CommonsLogger</td>
                <td>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, ...</td>
            </tr>
            <tr>
                <td>org.apache.poi.util.DummyPOILogger</td>
                <td>Simple logger which will keep all log-lines in memory for later analysis. Used primarily for testing. Note: this may cause a memory leak if used in production application!</td>
            </tr>
            </table>
        </section>
        <section><title>Sending logs to a different log framework</title>
            <p>
                You can send logs to other logging frameworks by implementing the interface <em>org.apache.poi.util.POILogger</em>.
            </p>
        </section>
        <section><title>Implementation details</title>
            <p>
                Every class uses a <code>POILogger</code> to log, and gets it using a static method
                of the <code>POILogFactory</code> .
            </p>
            <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>
        </section>
    </body>
    <footer>
        <legal>
            Copyright (c) @year@ The Apache Software Foundation All rights reserved.
            <br />
            Apache POI, POI, Apache, the Apache feather logo, and the Apache
            POI project logo are trademarks of The Apache Software Foundation.
        </legal>
    </footer>
</document>
