JSR-047 and Commons Logging support

The Log and Trace Analyzer provides standalone and plug-in support for new and existing users of the following logging utilities:

JSR-047 Java Logging APIs
Commons Logging

The details of this support are as follows.

Capability to export log messages to a logging agent
An extension of the java.util.logging.Handler abstract class under the org.eclipse.hyades.logging.java package allows loggers to be configured to export log messages to a Logging Agent.
This org.eclipse.hyades.logging.java.LoggingAgentHandler handler checks if a java.util.logging.LogRecord log message that is written to a logger can be logged based on the handler's filter and logging level. If the log message is to be logged, a Logging Agent is created with the same name as the logger that logs the message. The message is formatted using an org.eclipse.hyades.logging.java.XmlFormatter and written to the Logging Agent.

Capability to convert log messages to XML
An extension of the java.util.logging.Formatter abstract class under the org.eclipse.hyades.logging.java package allows org.eclipse.hyades.logging.java.LoggingAgentHandler and other handlers to format java.util.logging.LogRecord log messages to XML. This org.eclipse.hyades.logging.java.XmlFormatter formatter converts the java.util.logging.LogRecord message to XML equivalent to the current org.eclipse.hyades.internal.logging.core.XmlGenerator implementation but excluding the host, process, and agent tags. The generated XML is not formatted and the maximum nesting level is set to 4. When formatting, the object is checked if it implements the org.eclipse.hyades.logging.core. IExternalizableToXml interface. If so, the externalizeCanonicalXmlString() API is called in place of XML serialization by means of introspection for performance reasons.

The following output illustrates the XML conversion of a log message (the string "Hello World" (SEVERE logging level)):

   <LogRecord logging.util.id="java.util.logging.LogRecord_10468105484720000"
   logging.util.agent_idref="AGENT_CREATE.org.eclipse.hyades.tests.java.JavaLoggingTest.1063298146.542"
   logging.util.MsgLoggerLevel="SEVERE" LoggerName="org.eclipse.hyades.tests.java.JavaLoggingTest"
   ResourceBundleName="null" SequenceNumber="0" SourceClassName="org.eclipse.hyades.tests.java.JavaLoggingTest"
   SourceMethodName="main" Message="Hello World" ThreadID="10"
   Millis="1046810548171">
   	<ResourceBundle Instance_Name="ResourceBundle" Value="null"/>
	<Level Instance_Name="Level" logging.util.id="java.util.logging.Level_10468105484720001"
   		ResourceBundleName="sun.util.logging.resources.logging" Name="SEVERE"
   		LocalizedName="SEVERE"><Class Instance_Name="Class" logging.util.id="java.lang.Class_10468105484720002"
   		Name="java.util.logging.Level" Type="class" Package="java.util.logging"
   		Modifers="public" Superclass="java.lang.Object" />
   	</Level>
   	<Array Instance_Name="Parameters" Value="null" />
	<Throwable Instance_Name="Thrown" Value="null" />
	<Class Instance_Name="Class" logging.util.id="java.lang.Class_10468105484820000"
	   Name="java.util.logging.LogRecord" Type="class" Package="java.util.logging"
	   Modifers="public" Superclass="java.lang.Object" />
  </LogRecord>

Capability to bootstrap extension classes to existing Java Logging APIs
To bootstrap the org.eclipse.hyades.logging.java14 extension classes to the existing Java Logging APIs in JDK 1.4.0 and above, you must add the following entries to the JRE_HOME\lib\logging.properties configuration file before VM start-up or before the java.util.logging.LogManager.readConfiguration() API is called:
```
handlers= <your current handlers>, org.eclipse.hyades.logging.java.LoggingAgentHandler
org.eclipse.hyades.logging.java.LoggingAgentHandler.formatter = org.eclipse.hyades.logging.java.XmlFormatter
```
Alternatively, you can use the org.eclipse.hyades.logging.java14 plug-in extension classes with the existing Java Logging APIs in JDK 1.4.0 and above on the Logger (for example, handler) and Handler (for example, formatter) programmatically at run-time using the addHandler() and setFormatter() APIs, respectively.
Capability to include a Common Base Event in a log record
An extension of the java.util.logging.LogRecord class under the org.eclipse.hyades.logging.java package enables you to create a customized log record for including an org.eclipse.hyades.logging.events.ICommonBaseEvent in a java.util.logging.LogRecord.

This org.eclipse.hyades.logging.java.CommonBaseEventLogRecord simple extends java.util.logging.LogRecord and contains a single reference to an org.eclipse.hyades.logging.events.ICommonBaseEvent. You are responsible for creating a new org.eclipse.hyades.logging.java.CommonBaseEventLogRecord object before writing to the java.util.logging.Logger.
Capability to allow filtering of logged records from being processed by the handler class
You can filter the logged records from being processed by the org.eclipse.hyades.logging.java.LoggingAgentHandler class by setting an implementation of the java.util.logging.Filter interface such as the org.eclipse.hyades.logging.java.CommonBaseEventFilter (only permits org.eclipse.hyades.logging.java.CommonBaseEventLogRecord to be successfully logged) and logging java.util.logging.Level on the handler. These values can be set programmatically at run time using the setFilter() and setLevel() APIs, respectively.

Alternatively, you can add the following entries to the JRE_HOME\lib\logging.properties configuration file before VM start-up or before the java.util.logging.LogManager.readConfiguration() API is called:
```
org.eclipse.hyades.logging.java.LoggingAgentHandler.level = <level>
org.eclipse.hyades.logging.java.LoggingAgentHandler.filter = org.eclipse.hyades.logging.java.CommonBaseEventFilter
```
Capability to create a customized logger for java.lang.Objects and java.lang.Throwables
An implementation of the org.apache.commons.logging.Log interface under the org.eclipse.hyades.logging.commons package enables you to create a customized logger for logging java.lang.Objects and java.lang.Throwables to a Logging Agent with the same name as the logger.
This org.eclipse.hyades.logging.commons.Logger checks if java.lang.Object and/or java.lang.Throwable log messages written to a logger can be logged based on the logger's logging level. If the log message is to be logged, the java.lang.Object and java.lang.Throwable log message is formatted using an org.eclipse.hyades.internal.logging.core.XmlGenerator and written to the Logging Agent. When formatting, the object is checked if it implements the org.eclipse.hyades.logging.core. IExternalizableToXml interface. If so, the externalizeCanonicalXmlString() API is called in place of XML serialization by means of introspection for performance reasons. To bootstrap the org.eclipse.hyades.logging.commons.Logger class to the org.apache.commons.logging.LogFactory class, you must set the following system property on VM start-up:
```
-Dorg.apache.commons.logging.Log=org.eclipse.hyades.logging.commons.Logger
```

Precautions

If you log string log messages, you must not imbed XML fragments in the message. If you imbed XML fragments in the log message, the XML content will be normalized and added to the value of the value attribute of a string tag. For example,
```
   <String logging.util.agent_idref="AGENT_CREATE.LoggingUtilSample
   logger.1045075846.538" logging.util.MsgLoggerLevel="FINEST"
   Value="&lt;tag attribute=&quot;value&quot;/&gt;"/>
   
```
If you use the com.ibm.etools.logging.util standalone logging utilities, you must add the path to the hlcore.jar, hparse.jar, hexl.jar and hexr.jar JAR files to the system and VM class path.

Related concepts
Common Base Event model