diff --git a/src/documentation/xdocs/utils/book.xml b/src/documentation/xdocs/utils/book.xml index f6ed52ceee..d335bf38b4 100644 --- a/src/documentation/xdocs/utils/book.xml +++ b/src/documentation/xdocs/utils/book.xml @@ -9,6 +9,11 @@ + + + + + diff --git a/src/documentation/xdocs/utils/logging.xml b/src/documentation/xdocs/utils/logging.xml new file mode 100644 index 0000000000..7e675ee6d3 --- /dev/null +++ b/src/documentation/xdocs/utils/logging.xml @@ -0,0 +1,79 @@ + + + + +
+ Poi Utils + Overview + + + +
+ + +
+ +

+ Logging in POI is used only as a debugging mechanism, not a normal runtime + logging system. +

+ +

+ Hence, we need to be able to easily disable it entirely and make POI not dependent + on any logging package. +

+ + + POI is not dependent on commons-logging for running, but not for compiling. + + +
+

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

+

+ The POILogFactory uses the NullLogger by default; + it can be instructed to use any other POILogger implementation + by setting the system property org.apache.poi.util.POILogger. +

+ java -Dorg.apache.poi.util.POILogger=the.package.of.MyPoiLoggerImpl ProgramThatUsesPoi + + Still needs testing. + +
+ +
+

+ Each class in POI can get its POILogger by calling 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. +
  2. we need to be able to use POI without any logger package present.
    3. +
+

There are three implementations available, and you can roll out your own, just + extend org.apache.poi.util.POILogger. +

+
+

Discards every logging request.

+
+
+

Sends every logging request to System.out.

+
+
+

Sends every logging request to the Commons Logging package. This can use JDK1.4 logging, + log4j, logkit, and is an actively maintained Jakarta Project.

+
+ +
+
+ +