Module java.logging
Package java.util.logging

Class 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 Detail

      • 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 Detail

      • 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