Package org.jboss.logmanager.formatters

## Class StructuredFormatter

- java.lang.Object
- - java.util.logging.Formatter
  - - org.jboss.logmanager.ExtFormatter
    - - org.jboss.logmanager.formatters.StructuredFormatter

Direct Known Subclasses:
  `JsonFormatter`, `XmlFormatter`

    public abstract class StructuredFormatter
    extends ExtFormatter

An abstract class that uses a generator to help generate structured data from a `record`.

Note that including details can be expensive in terms of calculating the caller.

By default the record delimiter is set to `\n`.

Author:
  James R. Perkins

### Nested Class Summary

Nested Classes
`static class` `StructuredFormatter.ExceptionOutputType` Defines the way a cause will be formatted.
`protected static interface` `StructuredFormatter.Generator` A generator used to create the structured output.
`static class` `StructuredFormatter.Key` The key used for the structured log record data.

### Constructor Summary

Constructors
`protected` `StructuredFormatter()`
`protected` `StructuredFormatter​(java.lang.String keyOverrides)`
`protected` `StructuredFormatter​(java.util.Map<StructuredFormatter.Key,java.lang.String> keyOverrides)`

### Method Summary

All Methods Instance Methods Abstract Methods Concrete Methods
`protected void` `after​(StructuredFormatter.Generator generator, ExtLogRecord record)` Invoked after the structured data has been added to the generator.
`protected void` `before​(StructuredFormatter.Generator generator, ExtLogRecord record)` Invoked before the structured data is added to the generator.
`protected abstract StructuredFormatter.Generator` `createGenerator​(java.io.Writer writer)` Creates the generator used to create the structured data.
`java.lang.String` `format​(ExtLogRecord record)` Format a message using an extended log record.
`java.time.format.DateTimeFormatter` `getDateTimeFormatter()` Returns the current formatter used to format a records date and time.
`StructuredFormatter.ExceptionOutputType` `getExceptionOutputType()` Get the current output type for exceptions.
`protected java.lang.String` `getKey​(StructuredFormatter.Key defaultKey)` Checks to see if the key should be overridden.
`java.lang.String` `getKeyOverrides()` A string representation of the key overrides.
`java.lang.String` `getMetaData()` Returns the value set for meta data.
`java.lang.String` `getRecordDelimiter()` Returns the character used to indicate the record has is complete.
`java.time.ZoneId` `getZoneId()` Returns the current zone id used for the date and time formatter.
`boolean` `isCallerCalculationRequired()` Determines whether or not this formatter will require caller, source level, information when a log record is formatted.
`protected boolean` `isDetailedExceptionOutputType()` Checks the exception output type and determines if detailed output should be written.
`protected boolean` `isFormattedExceptionOutputType()` Checks the exception output type and determines if formatted output should be written.
`boolean` `isPrintDetails()` Indicates whether or not details should be printed.
`void` `setDateFormat​(java.lang.String pattern)` Sets the pattern to use when formatting the date.
`void` `setExceptionOutputType​(StructuredFormatter.ExceptionOutputType exceptionOutputType)` Set the output type for exceptions.
`void` `setMetaData​(java.lang.String metaData)` Sets the meta data to use in the structured format.
`void` `setPrintDetails​(boolean printDetails)` Sets whether or not details should be printed.
`void` `setRecordDelimiter​(java.lang.String eorDelimiter)` Sets the value to be used to indicate the end of a record.
`void` `setZoneId​(java.lang.String zoneId)` Sets the `ZoneId` to use when formatting the date and time from the `LogRecord`.

### Methods inherited from class org.jboss.logmanager.ExtFormatter

`format`

### Methods inherited from class java.util.logging.Formatter

`formatMessage, getHead, getTail`

### Methods inherited from class java.lang.Object

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

### Constructor Detail

#### StructuredFormatter

    protected StructuredFormatter()

#### StructuredFormatter

    protected StructuredFormatter​(java.util.Map<StructuredFormatter.Key,java.lang.String> keyOverrides)

#### StructuredFormatter

    protected StructuredFormatter​(java.lang.String keyOverrides)

### Method Detail

#### createGenerator

    protected abstract StructuredFormatter.Generator createGenerator​(java.io.Writer writer)
                                                              throws java.lang.Exception

Creates the generator used to create the structured data.

Returns:
  the generator to use
Throws:
  `java.lang.Exception` - if an error occurs creating the generator

#### before

    protected void before​(StructuredFormatter.Generator generator,
                          ExtLogRecord record)
                   throws java.lang.Exception

Invoked before the structured data is added to the generator.

Parameters:
  `generator` - the generator to use
  `record` - the log record
Throws:
  `java.lang.Exception`

#### after

    protected void after​(StructuredFormatter.Generator generator,
                         ExtLogRecord record)
                  throws java.lang.Exception

Invoked after the structured data has been added to the generator.

Parameters:
  `generator` - the generator to use
  `record` - the log record
Throws:
  `java.lang.Exception`

#### getKey

    protected final java.lang.String getKey​(StructuredFormatter.Key defaultKey)

Checks to see if the key should be overridden.

Parameters:
  `defaultKey` - the default key
Returns:
  the overridden key or the default key if no override exists

#### format

    public final java.lang.String format​(ExtLogRecord record)

Description copied from class: `ExtFormatter`
Format a message using an extended log record.

Specified by:
  `format` in class `ExtFormatter`
Parameters:
  `record` - the log record
Returns:
  the formatted message

#### isCallerCalculationRequired

    public boolean isCallerCalculationRequired()

Description copied from class: `ExtFormatter`
Determines whether or not this formatter will require caller, source level, information when a log record is formatted.

Overrides:
  `isCallerCalculationRequired` in class `ExtFormatter`
Returns:
  `true` if the formatter will need caller information, otherwise `false`
See Also:
  `LogRecord.getSourceClassName()`, `ExtLogRecord.getSourceFileName()`, `ExtLogRecord.getSourceLineNumber()`, `LogRecord.getSourceMethodName()`

#### getKeyOverrides

    public java.lang.String getKeyOverrides()

A string representation of the key overrides. The default is `null`.

Returns:
  a string representation of the key overrides or `null` if no overrides were configured

#### getRecordDelimiter

    public java.lang.String getRecordDelimiter()

Returns the character used to indicate the record has is complete. This defaults to `\n` and may be `null` if no end of record character is desired.

Returns:
  the end of record delimiter or `null` if no delimiter is desired

#### setRecordDelimiter

    public void setRecordDelimiter​(java.lang.String eorDelimiter)

Sets the value to be used to indicate the end of a record. If set to `null` no delimiter will be used at the end of the record.

Parameters:
  `eorDelimiter` - the delimiter to be used or `null` to not use a delimiter

#### getMetaData

    public java.lang.String getMetaData()

Returns the value set for meta data.

The value is a string where key/value pairs are separated by commas. The key and value are separated by an equal sign.

Returns:
  the meta data string or `null` if one was not set
See Also:
  `PropertyValues.stringToMap(String)`

#### setMetaData

    public void setMetaData​(java.lang.String metaData)

Sets the meta data to use in the structured format.

The value is a string where key/value pairs are separated by commas. The key and value are separated by an equal sign.

Parameters:
  `metaData` - the meta data to set or `null` to not format any meta data
See Also:
  `PropertyValues.stringToMap(String)`

#### getDateTimeFormatter

    public java.time.format.DateTimeFormatter getDateTimeFormatter()

Returns the current formatter used to format a records date and time.

Returns:
  the current formatter

#### setDateFormat

    public void setDateFormat​(java.lang.String pattern)

Sets the pattern to use when formatting the date. The pattern must be a valid `DateTimeFormatter.ofPattern(String)` pattern.

If the pattern is `null` a default formatter will be used. The zone id will always be appended to the formatter. By default the zone id will default to the systems zone id.

Parameters:
  `pattern` - the pattern to use or `null` to use a default pattern

#### getZoneId

    public java.time.ZoneId getZoneId()

Returns the current zone id used for the date and time formatter.

Returns:
  the current zone id

#### setZoneId

    public void setZoneId​(java.lang.String zoneId)

Sets the `ZoneId` to use when formatting the date and time from the `LogRecord`.

The rules of the id must conform to the rules specified on `ZoneId.of(String)`.

Parameters:
  `zoneId` - the zone id or `null` to use the system default
See Also:
  `ZoneId.of(String)`

#### isPrintDetails

    public boolean isPrintDetails()

Indicates whether or not details should be printed.

Returns:
  `true` if details should be printed, otherwise `false`

#### setPrintDetails

    public void setPrintDetails​(boolean printDetails)

Sets whether or not details should be printed.

Printing the details can be expensive as the values are retrieved from the caller. The details include the source class name, source file name, source method name and source line number.

Parameters:
  `printDetails` - `true` if details should be printed

#### getExceptionOutputType

    public StructuredFormatter.ExceptionOutputType getExceptionOutputType()

Get the current output type for exceptions.

Returns:
  the output type for exceptions

#### setExceptionOutputType

    public void setExceptionOutputType​(StructuredFormatter.ExceptionOutputType exceptionOutputType)

Set the output type for exceptions. The default is `DETAILED`.

Parameters:
  `exceptionOutputType` - the desired output type, if `null` `StructuredFormatter.ExceptionOutputType.DETAILED` is used

#### isDetailedExceptionOutputType

    protected boolean isDetailedExceptionOutputType()

Checks the exception output type and determines if detailed output should be written.

Returns:
  `true` if detailed output should be written, otherwise `false`

#### isFormattedExceptionOutputType

    protected boolean isFormattedExceptionOutputType()

Checks the exception output type and determines if formatted output should be written. The formatted output is equivalent to `Throwable.printStackTrace()`.

Returns:
  `true` if formatted exception output should be written, otherwise `false`