Package org.apache.logging.log4j.core.pattern

Class ThrowablePatternConverter

java.lang.Object

org.apache.logging.log4j.core.pattern.AbstractPatternConverter

org.apache.logging.log4j.core.pattern.LogEventPatternConverter

org.apache.logging.log4j.core.pattern.ThrowablePatternConverter

All Implemented Interfaces:

PatternConverter

Direct Known Subclasses:

ExtendedThrowablePatternConverter, RootThrowablePatternConverter

@NullMarked
@Plugin(name="ThrowablePatternConverter",
        category="Converter")
public class ThrowablePatternConverter
extends LogEventPatternConverter

Outputs certain information extracted from the Throwable associated with a LogEvent.

Field Summary

Fields

Modifier and Type	Field	Description
private final Function<LogEvent,String>	effectiveLineSeparatorProvider
protected final List<PatternFormatter>	formatters	Deprecated. Kept for binary backward compatibility.
protected final ThrowableFormatOptions	options
private final ThrowableRenderer	renderer

Fields inherited from class org.apache.logging.log4j.core.pattern.AbstractPatternConverter

LOGGER

Fields inherited from interface org.apache.logging.log4j.core.pattern.PatternConverter

CATEGORY

Constructor Summary

Constructors

Modifier	Constructor	Description
protected	ThrowablePatternConverter(String name, String style, @Nullable String[] options)	Deprecated. Use ThrowablePatternConverter(String, String, String[], Configuration, ThrowablePropertyRendererFactory, ThrowableStackTraceRendererFactory) instead.
protected	ThrowablePatternConverter(String name, String style, @Nullable String[] options, @Nullable Configuration config)	Deprecated. Use ThrowablePatternConverter(String, String, String[], Configuration, ThrowablePropertyRendererFactory, ThrowableStackTraceRendererFactory) instead.
(package private)	ThrowablePatternConverter(String name, String style, @Nullable String[] options, @Nullable Configuration config, @Nullable ThrowablePropertyRendererFactory propertyRendererFactory, @Nullable ThrowableStackTraceRendererFactory stackTraceRendererFactory)	The canonical constructor.

Method Summary

Modifier and Type	Method	Description
private static Function<LogEvent,String>	createEffectiveLineSeparator(String separator, @Nullable String suffix, @Nullable Configuration config, List<PatternFormatter> suffixFormatters)	Creates a lambda that returns the effective line separator by concatenating the formatted suffix with the separator.
private static ThrowableRenderer	createEffectiveRenderer(String[] rawOptions, ThrowableFormatOptions options, @Nullable ThrowablePropertyRendererFactory propertyRendererFactory, @Nullable ThrowableStackTraceRendererFactory stackTraceRendererFactory)
void	format(LogEvent event, StringBuilder buffer)	Formats an event into a string buffer.
ThrowableFormatOptions	getOptions()
protected String	getSuffix(LogEvent logEvent)	Deprecated. Planned to be removed without a replacement
boolean	handlesThrowable()	Indicates this converter handles Throwables.
static ThrowablePatternConverter	newInstance(@Nullable Configuration config, @Nullable String[] options)	Creates an instance of the class.

Methods inherited from class org.apache.logging.log4j.core.pattern.LogEventPatternConverter

emptyVariableOutput, format, isVariable

Methods inherited from class org.apache.logging.log4j.core.pattern.AbstractPatternConverter

getName, getStyleClass

Methods inherited from class java.lang.Object

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

Field Details

formatters

@Deprecated
protected final List<PatternFormatter> formatters

Deprecated.

Kept for binary backward compatibility.

Returns the list of formatters used to render the suffix.

effectiveLineSeparatorProvider

private final Function<LogEvent,String> effectiveLineSeparatorProvider

options

protected final ThrowableFormatOptions options

renderer

private final ThrowableRenderer renderer

Constructor Details

ThrowablePatternConverter

@Deprecated
protected ThrowablePatternConverter(String name,
 String style,
 @Nullable String[] options)

Deprecated.

Use ThrowablePatternConverter(String, String, String[], Configuration, ThrowablePropertyRendererFactory, ThrowableStackTraceRendererFactory) instead.

ThrowablePatternConverter

@Deprecated
protected ThrowablePatternConverter(String name,
 String style,
 @Nullable String[] options,
 @Nullable Configuration config)

Deprecated.

Use ThrowablePatternConverter(String, String, String[], Configuration, ThrowablePropertyRendererFactory, ThrowableStackTraceRendererFactory) instead.

ThrowablePatternConverter

ThrowablePatternConverter(String name,
 String style,
 @Nullable String[] options,
 @Nullable Configuration config,
 @Nullable ThrowablePropertyRendererFactory propertyRendererFactory,
 @Nullable ThrowableStackTraceRendererFactory stackTraceRendererFactory)

The canonical constructor.

Parameters:

name - name of the converter

style - CSS style for output

options - array of options

config - a configuration

stackTraceRendererFactory - a renderer factory

Since:

2.25.0

Method Details

newInstance

public static ThrowablePatternConverter newInstance(@Nullable Configuration config,
 @Nullable String[] options)

Creates an instance of the class.

Parameters:

config - a configuration

options - the pattern options

Returns:

a new instance

format

public void format(LogEvent event,
 StringBuilder buffer)

Formats an event into a string buffer.

Specified by:

format in class LogEventPatternConverter

Parameters:

event - event to format, may not be null.

buffer - string buffer to which the formatted event will be appended. May not be null.

handlesThrowable

public boolean handlesThrowable()

Indicates this converter handles Throwables.

Overrides:

handlesThrowable in class LogEventPatternConverter

Returns:

true

getOptions

public ThrowableFormatOptions getOptions()

createEffectiveLineSeparator

private static Function<LogEvent,String> createEffectiveLineSeparator(String separator,
 @Nullable String suffix,
 @Nullable Configuration config,
 List<PatternFormatter> suffixFormatters)

Creates a lambda that returns the effective line separator by concatenating the formatted suffix with the separator.

At the beginning, there was only separator used as a terminator at the end of every rendered line. Its content was rendered literally without any processing.

Later on, suffix was added in #61. suffix is functionally identical to separator with the exception that it contains a Pattern Layout conversion pattern. In an ideal world, separator should have been extended to accept patterns. But without giving it a second of thought, just like almost any other Log4j feature, we cheerfully accepted the feature.

Given two overlapping features, how do we determine the effective line separator?

 String effectiveLineSeparator(String separator, String suffix, LogEvent event) {
     String formattedSuffix = format(suffix, event);
     return isNotBlank(formattedSuffix)
            ? (' ' + formattedSuffix + lineSeparator)
            : lineSeparator;
 }
 

Parameters:

separator - the user-provided separator option

suffix - the user-provided suffix option containing a Pattern Layout conversion pattern

config - the configuration to create the Pattern Layout conversion pattern parser

suffixFormatters - the list of pattern formatters employed to format the suffix

Returns:

a lambda that returns the effective line separator by concatenating the formatted suffix with the separator

createEffectiveRenderer

private static ThrowableRenderer createEffectiveRenderer(String[] rawOptions,
 ThrowableFormatOptions options,
 @Nullable ThrowablePropertyRendererFactory propertyRendererFactory,
 @Nullable ThrowableStackTraceRendererFactory stackTraceRendererFactory)

getSuffix

@Deprecated
protected String getSuffix(LogEvent logEvent)

Deprecated.

Planned to be removed without a replacement

Returns the formatted suffix pattern.

Parameters:

logEvent - the log event to use while formatting the suffix pattern

Returns:

the formatted suffix