>
 
 

Apache POI - Logging Framework

Introduction

POI uses a custom logging framework which allows to configure where logs are sent to.

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.

The framework is extensible so that you can send log messages to any logging framework that your application uses.

A number of default logging implementations are supported by POI out-of-the-box and can be selected via a system property.

Enable logging

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.

You can select the logging framework by setting the system property org.apache.poi.util.POILogger during application startup or by calling System.setProperty():

System.setProperty("org.apache.poi.util.POILogger", "org.apache.poi.util.CommonsLogger" );

Note: You need to call setProperty() before any POI functionality is invoked as the logger is only initialized during startup.

Available logger implementations

The following logger implementations are provided by POI:

Class Type
org.apache.poi.util.SystemOutLogger Sends log output to the system console
org.apache.poi.util.NullLogger Default logger, does not log anything
org.apache.poi.util.CommonsLogger Allows to use for logging. This can use JDK1.4 logging, log4j, logkit, etc. The log4j dependency was removed in POI 5.0.0, so you will need to include this dependency yourself if you need it.
org.apache.poi.util.DummyPOILogger Simple logger which will keep all log-lines in memory for later analysis (this class is not in the jar, just in the test source). Used primarily for testing. Note: this may cause a memory leak if used in production application!

Sending logs to a different log framework

You can send logs to other logging frameworks by implementing the interface org.apache.poi.util.POILogger.

Implementation details

Every class uses a POILogger to log, and gets it using a static method of the POILogFactory .

Each class in POI can log using a POILogger, which is an abstract class. We decided to make our own logging facade because:

  1. we need to log many values and we put many methods in this class to facilitate the programmer, without having him write string concatenations;
  2. we need to be able to use POI without any logger package present.

by Dominik Stadler