Logging

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

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

• the 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.

PDFxStream uses the java.util.logging package by default. You may use the pdfxs.loggingtype configuration option to force PDFxStream to use Log4J.

Custom Logging Toolkit API

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

1. Create a class that implements com.snowtide.util.logging.LogFactory. This class will dispense com.snowtide.util.logging.Log instances to which PDFxStream 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 PDFxStream, pass an instance of your LogFactory implementation to com.snowtide.util.logging.LoggingRegistry.registerFactory(LogFactory) method.
         OR
   • Set the system property pdfxs.logfactory to the fully-qualified classname of your LogFactory implementation.

PDFxStream creates and gathers all of the 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.** packages.

It should be noted that while PDFxStream presents you with a very simple and clean public API, there are many, many more classes behind the scenes are critical to its operation. Because some logging information does occasionally come from those classes, any changes to logging configuration settings should be made at the package level in order to affect all classes in the PDFxStream library. In particular, it is recommended that logging for all com.snowtide.** packages be set at INFO or above, as PDFxStream and its associated classes log significant diagnostic information at the DEBUG level.

For example, to change the logging level applied to messages emitted by PDFxStream 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=ERROR