Logging

PDFTextStream is designed to integrate seamlessly into your application’s infrastructure, including whatever logging apparatus your application depends upon.

Without any special configuration, PDFTextStream automatically detects and configures itself if one of the following logging toolkits is available:

• JDK v1.4+ java.util.logging package
• Log4J

When one of these logging toolkits is used, which levels of log messages are outputted, their format, and their destination are all determined by the logging toolkit configuration. If none of the logging toolkits listed above are available, error information will be written to standard out.

PDFTextStream uses the java.util.logging package by default. To force it to use Log4J, simply set the pdfts.loggingtype system variable to "log4j" before using PDFTextStream.

Custom Logging Toolkit API

If you use a custom logging toolkit, or a toolkit that is not natively supported, you can register it with PDFTextStream with relative ease. To do so, simply follow this process:

1. Create a class that implements the com.snowtide.util.logging.LogFactoryinterface. Thisclass dispenses com.snowtide.util.logging.Log instances to which PDFTextStream sends logging messages.
2. Register your LogFactory implementation with com.snowtide.util.logging.LoggingRegistry. This can be done in one of two ways:
   • Before using PDFTextStream, pass an instance of your LogFactory implementation to the LoggingRegistry.registerFactory(LogFactory) method.
         OR
   • Set the system property pdfts.logfactory to the full classname of your LogFactory implementation. This can be done when starting your java application using the -D switch, or by editing the appropriate settings in your application server configuration.

PDFTextStream creates and gathers all of the com.snowtide.util.logging.Log instances it will need at class initialization time, so your LogFactory implementation must be registered before then in order for it to be used.

Customizing Logging

Please refer to the documentation related to the logging toolkit your application uses to determine how best to configure logging for the com.snowtide.pdf package.

It should be noted that while PDFTextStream presents you (the application developer) with a very simple and clean interface, there are many, many more classes involved in the reading of text content aside from com.snowtide.pdf.PDFTextStream. As such, some logging information does occasionally come from those classes, so any changes to logging configuration settings should be made at the package level in order to affect all classes in the PDFTextStream library. (In particular, it is recommended that logging for the com.snowtide.pdf package be set at INFO or above, as PDFTextStream and its associated classes log significant diagnostic information at the DEBUG level.)

For example, to change the logging level applied to messages emitted by PDFTextStream regardless of the logging level applied to the rest of your application, you would add these lines to your log4j.properties file (this example is provided for users of Log4J; please check your logging toolkit's documentation on how best to achieve similar effects):

log4j.logger.com.snowtide.pdf=ERROR