Class XMLFormatter

java.lang.Object

java.util.logging.Formatter

java.util.logging.XMLFormatter

public class XMLFormatter
extends Formatter

Format a LogRecord into a standard XML format.

The DTD specification is provided as Appendix A to the Java Logging APIs specification.

The XMLFormatter can be used with arbitrary character encodings, but it is recommended that it normally be used with UTF-8. The character encoding can be set on the output Handler.

Implementation Requirements:

Since JDK 9, instances of LogRecord contain an Instant which can have nanoseconds below the millisecond resolution. The DTD specification has been updated to allow for an optional <nanos> element. By default, the XMLFormatter will compute the nanosecond adjustment below the millisecond resolution (using LogRecord.getInstant().getNano() % 1000_000) - and if this is not 0, this adjustment value will be printed in the new <nanos> element. The event instant can then be reconstructed using Instant.ofEpochSecond(millis/1000L, (millis % 1000L) * 1000_000L + nanos) where millis and nanos represent the numbers serialized in the <millis> and <nanos> elements, respectively.
The <date> element will now contain the whole instant as formatted by the DateTimeFormatter.ISO_INSTANT formatter.

For compatibility with old parsers, XMLFormatters can be configured to revert to the old format by specifying a <xml-formatter-fully-qualified-class-name>.useInstant = false property in the logging configuration. When useInstant is false, the old formatting will be preserved. When useInstant is true (the default), the <nanos> element will be printed and the <date> element will contain the formatted instant.

For instance, in order to configure plain instances of XMLFormatter to omit the new <nano> element, java.util.logging.XMLFormatter.useInstant = false can be specified in the logging configuration.

Since:

1.4

Constructor Summary

Constructors

Constructor	Description
XMLFormatter()	Creates a new instance of XMLFormatter.

Method Summary

Modifier and Type	Method	Description
String	format(LogRecord record)	Format the given message to XML.
String	getHead(Handler h)	Return the header string for a set of XML formatted records.
String	getTail(Handler h)	Return the tail string for a set of XML formatted records.

Methods declared in class Formatter

formatMessage

Modifier and Type	Method	Description
String	formatMessage(LogRecord record)	Localize and format the message string from a log record.

Methods declared in class Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Modifier and Type	Method	Description
protected Object	clone()	Answers a new instance of the same class as the receiver, whose slots have been filled in with the values in the slots of the receiver.
boolean	equals(Object o)	Compares the argument to the receiver, and answers true if they represent the same object using a class specific comparison.
protected void	finalize()	Deprecated, for removal: This API element is subject to removal in a future version. May cause performance issues, deadlocks and hangs.
final Class<? extends Object>	getClass()	Answers the unique instance of java.lang.Class which represents the class of the receiver.
int	hashCode()	Answers an integer hash code for the receiver.
final void	notify()	Causes one thread which is waiting on the receiver to be made ready to run.
final void	notifyAll()	Causes all threads which are waiting on the receiver to be made ready to run.
String	toString()	Answers a string containing a concise, human-readable description of the receiver.
final void	wait()	Causes the thread which sent this message to be made not ready to run pending some change in the receiver (as indicated by notify or notifyAll).
final void	wait(long time)	Causes the thread which sent this message to be made not ready to run either pending some change in the receiver (as indicated by notify or notifyAll) or the expiration of the timeout.
final void	wait(long time, int frac)	Causes the thread which sent this message to be made not ready to run either pending some change in the receiver (as indicated by notify or notifyAll) or the expiration of the timeout.

Constructor Details

XMLFormatter

public XMLFormatter()

Creates a new instance of XMLFormatter.

Implementation Requirements:

Since JDK 9, the XMLFormatter will print out the record event time as an Instant. This instant has the best resolution available on the system. The <date> element will contain the instant as formatted by the DateTimeFormatter.ISO_INSTANT. In addition, an optional <nanos> element containing a nanosecond adjustment will be printed if the instant contains some nanoseconds below the millisecond resolution.

This new behavior can be turned off, and the old formatting restored, by specifying a property in the logging configuration. If LogManager.getLogManager().getProperty( this.getClass().getName()+".useInstant") is "false" or "0", the old formatting will be restored.

Method Details

format

public String format(LogRecord record)

Format the given message to XML.

This method can be overridden in a subclass. It is recommended to use the Formatter.formatMessage(LogRecord) convenience method to localize and format the message field.

Specified by:

format in class Formatter

Parameters:

record - the log record to be formatted.

Returns:

a formatted log record

getHead

public String getHead(Handler h)

Return the header string for a set of XML formatted records.

Overrides:

getHead in class Formatter

Parameters:

h - The target handler (can be null)

Returns:

a valid XML string

getTail

public String getTail(Handler h)

Return the tail string for a set of XML formatted records.

Overrides:

getTail in class Formatter

Parameters:

h - The target handler (can be null)

Returns:

a valid XML string