Provides logging support for the API.

Logging ensures that problems and program errors are recorded for later analysis. The logging mechanism must be configured properly to record the information. For OpenNTF Domino API the configuration is stored in the IBM_TECHNICAL_SUPPORT\org.openntf.domino.logging.logconfig.properties file in the Domino data directory. When this file does not exist, the ODA uses default settings.

Default logging settings

By default the log messages for the org.openntf.domino package with level WARNING and higher are:

Logging configuration

Configuration for the logging mechanism is stored in the IBM_TECHNICAL_SUPPORT\org.openntf.domino.logging.logconfig.properties file in the Domino data directory. This file is checked for changes every minute and dynamically reloaded when needed. The message "Logging: Updated LogConfig from changed PropertyFile" is printed on the server console when the configuration is successfully reloaded.

The configuration file consists of two parts. First part defines the Handlers, second part defines the Filter Handlers.

Handlers

A Handler object takes log messages from a Logger and exports them. You may define arbitrary many handlers. These handlers must be listed on the "Handlers=<handler 1 name>, <handler 2 name>" line. Handler names are arbitrary. Each handler is configured by Handler. <handler name>-properties, where the following properties may/must be defined:
Class Required Handler's class name (subclass of java.util.logging.Handler).
MinimalLevel Optional Minimal level (SEVERE, WARNING, FINE, ...) the handler may publish.
Formatter Optional Class for the handler's Formatter; if none is specified, some default formatter is used.
Props Optional Set of comma-separated properties for handler configuration. The properties are specific to the handler.

A handler's class must implement some static methods which will be called via reflection:

{@link org.openntf.domino.logging.LogHandlerConfigIF} configFromProps(String props) [public static] The "Props" from above are examined, the resulting Object should contain a configuration set for the handler. In case of "wrong" props, an Exception should be thrown.
<HandlerClass> getInstance(LogHandlerConfigIF config, boolean useDefaultFormatter) [public static] Parameter config contains the return value from configFromProps method, useDefaultFormatter is true if (and only if) no Formatter is configured.

Additionally, a handler may implement the {@link org.openntf.domino.logging.LogHandlerUpdateIF} interface to enable the handler to be dynamically attached to a new log configuration.

Example
	Handlers=HFile1, HConsole, HLogDB

	Handler.HFile1.Class=org.openntf.domino.logging.LogHandlerFile
	Handler.HFile1.Props=	Limit=50000000,	\
			Count=10, \
			Append=true, \
			Pattern=<notesdata>/IBM_TECHNICAL_SUPPORT/org.openntf.log.%u.%g.txt
	
	Handler.HConsole.Class=org.openntf.domino.logging.LogHandlerConsole
	Handler.HConsole.MinimalLevel=WARNING
	
	Handler.HLogDB.Class=org.openntf.domino.logging.LogHandlerOpenLog
	Handler.HLogDB.MinimalLevel=INFO
	Handler.HLogDB.Props=	LogDB=OpenLog.nsf
	
	
FilterHandlers

Handlers are attached to Loggers through FilterHandlers. Loggers are identified by name (usually a package or a class name) and specified using the LoggerPrefices property. FilterHandlers are identified by name, each can have the following properties:

LoggerPrefices Required Comma separated names of loggers to attached the specified handlers to
DefaultLevel Required Messages of this level and above will be passed to the Handler. If the message level is the same or above of a MinimalLevel property specified for the handler, it will be processed.
DefaultHandlers Required Comma separated list of handler names specified on the "Handlers=" line. Specified handlers will be attached to loggers identified by LoggerPrefices property.
Example
FilterHandlers=OpenNTF

FilterHandler.OpenNTF.LoggerPrefices=org.openntf.domino
FilterHandler.OpenNTF.DefaultLevel=WARNING
FilterHandler.OpenNTF.DefaultHandlers=HFile1, HConsole, HLogDB
Filter Config Entries

Optionally a FilterHandler can be accompanied by a Filter Config Entry. They further fine tune the behavior of the logging mechanism. Filter Config Entries can be used to change loggers based on a formula condition.

There can be any number of Filter Config Entries. They are supposed to be named FCE1, FCE2 and so on and are attached to a FilterHandler.

Available properties:
FCE<n> Required Logger name; must be a child of one of the FilterHandler's loggers
FCE<n>.Level Required FINEST, FINER, FINE, CONFIG, INFO, WARNING, or SEVERE
FCE<n>.Handlers Required One or more defined Handlers (not necessarily contained in DefaultHandlers)
FCE<n>.FormulaCondition Optional Condition as a formula (in Formula Language); the following variables may be used:
  • $USER$ - the actual user (given by Session.getEffectiveUser)
  • $DBPATH$ - path of the current DB (getApiPath)
  • $LOGGER$ - the Logger which generated the LogRecord
  • $MESSAGE$ - the LogRecord's message
FCE<n>.ValidUntil Optional Expiration date in ISO format (yyyy-mm-dd), i.e. the whole FCE entry is ignored after this date.
Example

In this example the logging level for the "org.openntf.domino.impl.Document" logger will be changed to FINE and log records will be written to a file pointing to by the HFile1 handler from Monday through Friday:

FilterHandler.OpenNTF.FCE1=org.openntf.domino.impl.Document
FilterHandler.OpenNTF.FCE1.Level=FINE
FilterHandler.OpenNTF.FCE1.Handlers=HFile1
FilterHandler.OpenNTF.FCE1.FormulaCondition=@Weekday(@Today) = 2:3:4:5:6
	
Complete example

Below is a complete example of the configuration file. It defines three handlers - HFile1 writes log records to a text file, HConsole handler writes to the server console and HLogDB to the OpenLog.nsf Notes database. A more detailed logging is turned on for an application with the path ending with hvm.nsf for the implementation of a Document class (via a Filter Config Entry).

Handlers=HFile1, HConsole, HLogDB

Handler.HFile1.Class=org.openntf.domino.logging.LogHandlerFile
Handler.HFile1.Props=	Limit=50000000,	\
			Count=10, \
			Append=true, \
			Pattern=<notesdata>/IBM_TECHNICAL_SUPPORT/org.openntf.log.%u.%g.txt

Handler.HConsole.Class=org.openntf.domino.logging.LogHandlerConsole
Handler.HConsole.MinimalLevel=WARNING

Handler.HLogDB.Class=org.openntf.domino.logging.LogHandlerOpenLog
Handler.HLogDB.MinimalLevel=INFO
Handler.HLogDB.Props=	LogDB=OpenLog.nsf

FilterHandlers=OpenNTF

FilterHandler.OpenNTF.LoggerPrefices=org.openntf.domino
FilterHandler.OpenNTF.DefaultLevel=WARNING
FilterHandler.OpenNTF.DefaultHandlers=HFile1, HConsole, HLogDB

FilterHandler.OpenNTF.FCE1=org.openntf.domino.impl.Document
FilterHandler.OpenNTF.FCE1.Level=FINE
FilterHandler.OpenNTF.FCE1.Handlers=HFile1
FilterHandler.OpenNTF.FCE1.FormulaCondition=@Ends($DBPATH$; "hvm.nsf")

Using your own loggers

You can configure OpenNTF Domino API logging for your own loggers. This way messages logged by your logger will be recorded using the same mechanisms as ODA uses.

Configuration

A minimum configuration requires:

Using your own FilterHandler helps to distinguish your logging settings from the settings for the ODA.

Bellow is an example of this configuration which adds a new filter handler and specifies the required properties. Log messages will be recorded using the handler HFile1 defined in the Handlers part. You can also specify your own handler which writes messages to a separate file or a separate copy of OpenLog.nsf database. Check the MinimalLevel property of the handler - if this is specified then only messages of that level and above will be recorded no matter what DefaultLevel you specify for your FilterHandler.

FilterHandlers=OpenNTF,[your filter handler name]
	
FilterHandler.[your filter handler name].LoggerPrefices=[hierarchical dot-separated name of your logger]
FilterHandler.[your filter handler name].DefaultLevel=INFO
FilterHandler.[your filter handler name].DefaultHandlers=HFile1
	

Created By :