net.minecrell.terminalconsole

Class TerminalConsoleAppender

java.lang.Object

org.apache.logging.log4j.core.AbstractLifeCycle

org.apache.logging.log4j.core.filter.AbstractFilterable

org.apache.logging.log4j.core.appender.AbstractAppender

net.minecrell.terminalconsole.TerminalConsoleAppender

All Implemented Interfaces:

org.apache.logging.log4j.core.Appender, org.apache.logging.log4j.core.filter.Filterable, org.apache.logging.log4j.core.LifeCycle, org.apache.logging.log4j.core.LifeCycle2

@Plugin(name="TerminalConsole",
        category="Core",
        elementType="appender",
        printObject=true)
public final class TerminalConsoleAppender
extends org.apache.logging.log4j.core.appender.AbstractAppender

An Appender that uses the JLine 3.x Terminal to print messages to the console.

The JLine Terminal extends the regular console output with support for Ansi escape codes on Windows. Additionally, it's LineReader interface can be used to implement enhanced console input, with an persistent input line, as well as command history and command completion.

The TerminalConsole appender replaces the default Console appender in your log4j configuration.

Example usage:

  <TerminalConsole>
     <PatternLayout pattern="[%d{HH:mm:ss} %level]: %msg%n"/>
 </TerminalConsole>

To use the enhanced console input it is necessary to set the LineReader using setReader(LineReader). The appender will then automatically redraw the current prompt. When creating the LineReader it's important to use the Terminal returned by getTerminal().

By default, the JLine Terminal is enabled when the application is started with an attached terminal session. Usually, this is only the case if the application is started from the command line, not if it gets started by another application.

In some cases, it might be possible to support a subset of the features in these unsupported environments (e.g. only ANSI color codes). In these cases, the system properties may be used to override the default behaviour:

• JLINE_OVERRIDE_PROPERTY - To enable the extended JLine input. By default this will also enable the ANSI escape codes.
• ANSI_OVERRIDE_PROPERTY - To enable the output of ANSI escape codes. May be used to force the use of ANSI escape codes if JLine is disabled or to disable them if it is enabled.

Nested Class Summary

Nested classes/interfaces inherited from class org.apache.logging.log4j.core.appender.AbstractAppender

org.apache.logging.log4j.core.appender.AbstractAppender.Builder<B extends org.apache.logging.log4j.core.appender.AbstractAppender.Builder<B>>

Nested classes/interfaces inherited from interface org.apache.logging.log4j.core.LifeCycle

org.apache.logging.log4j.core.LifeCycle.State

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	ANSI_OVERRIDE_PROPERTY System property that allows overriding the use of ANSI escape codes for console formatting even though running in an unsupported environment.
static java.lang.String	JLINE_OVERRIDE_PROPERTY System property that allows overriding the default detection of the console to force enable or force disable the use of JLine.
static java.lang.String	PLUGIN_NAME

Fields inherited from class org.apache.logging.log4j.core.AbstractLifeCycle

DEFAULT_STOP_TIMEOUT, DEFAULT_STOP_TIMEUNIT, LOGGER

Fields inherited from interface org.apache.logging.log4j.core.Appender

ELEMENT_TYPE

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	TerminalConsoleAppender(java.lang.String name, org.apache.logging.log4j.core.Filter filter, org.apache.logging.log4j.core.Layout<? extends java.io.Serializable> layout, boolean ignoreExceptions) Constructs a new TerminalConsoleAppender.

Method Summary

Modifier and Type	Method and Description
void	append(org.apache.logging.log4j.core.LogEvent event)
static void	close() Closes the JLine Terminal (if available) and restores the original terminal settings.
static TerminalConsoleAppender	createAppender(java.lang.String name, org.apache.logging.log4j.core.Filter filter, @Nullable org.apache.logging.log4j.core.Layout<? extends java.io.Serializable> layout, boolean ignoreExceptions) Creates a new TerminalConsoleAppender.
static @Nullable org.jline.reader.LineReader	getReader() Returns the currently configured LineReader that is used to read input from the console.
static @Nullable org.jline.terminal.Terminal	getTerminal() Returns the Terminal that is used to print messages to the console.
static boolean	isAnsiSupported() Returns whether ANSI escapes codes should be written to the console output.
static void	setReader(@Nullable org.jline.reader.LineReader newReader) Sets the LineReader that is used to read input from the console.

Methods inherited from class org.apache.logging.log4j.core.appender.AbstractAppender

error, error, error, getHandler, getLayout, getName, ignoreExceptions, parseInt, setHandler, toString

Methods inherited from class org.apache.logging.log4j.core.filter.AbstractFilterable

addFilter, getFilter, hasFilter, isFiltered, removeFilter, start, stop, stop

Methods inherited from class org.apache.logging.log4j.core.AbstractLifeCycle

equalsImpl, getState, getStatusLogger, hashCodeImpl, initialize, isInitialized, isStarted, isStarting, isStopped, isStopping, setStarted, setStarting, setState, setStopped, setStopping, stop, stop

Methods inherited from class java.lang.Object

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

Methods inherited from interface org.apache.logging.log4j.core.LifeCycle

getState, initialize, isStarted, isStopped, start, stop

Field Detail

PLUGIN_NAME

public static final java.lang.String PLUGIN_NAME

See Also:

Constant Field Values

JLINE_OVERRIDE_PROPERTY

public static final java.lang.String JLINE_OVERRIDE_PROPERTY

System property that allows overriding the default detection of the console to force enable or force disable the use of JLine. In some environments the automatic detection might not work properly.

If this system property is not set, or set to an invalid value (neither true nor false) then we will attempt to detect the best option automatically.

See Also:

Constant Field Values

ANSI_OVERRIDE_PROPERTY

public static final java.lang.String ANSI_OVERRIDE_PROPERTY

System property that allows overriding the use of ANSI escape codes for console formatting even though running in an unsupported environment. By default, ANSI color codes are only enabled if JLine is enabled. Some systems might be able to handle ANSI escape codes but are not capable of JLine's extended input mechanism.

If this system property is not set, or set to an invalid value (neither true nor false) then we will attempt to detect the best option automatically.

See Also:

Constant Field Values

Constructor Detail

TerminalConsoleAppender

protected TerminalConsoleAppender(java.lang.String name,
                                  org.apache.logging.log4j.core.Filter filter,
                                  org.apache.logging.log4j.core.Layout<? extends java.io.Serializable> layout,
                                  boolean ignoreExceptions)

Constructs a new TerminalConsoleAppender.

Parameters:

name - The name of the appender

filter - The filter, can be null

layout - The layout to use

ignoreExceptions - If true exceptions encountered when appending events are logged, otherwise they are propagated to the caller

Method Detail

getTerminal

public static @Nullable org.jline.terminal.Terminal getTerminal()

Returns the Terminal that is used to print messages to the console. Returns null in unsupported environments, unless overridden using the JLINE_OVERRIDE_PROPERTY system property.

Returns:

The terminal, or null if not supported

See Also:

TerminalConsoleAppender

getReader

public static @Nullable org.jline.reader.LineReader getReader()

Returns the currently configured LineReader that is used to read input from the console. May be null if no LineReader was configured by the environment.

Returns:

The current line reader, or null if none

setReader

public static void setReader(@Nullable org.jline.reader.LineReader newReader)

Sets the LineReader that is used to read input from the console. Setting the LineReader will allow the appender to automatically redraw the input line when a new log message is added.

Note: The specified LineReader must be created with the terminal returned by getTerminal().

Parameters:

newReader - The new line reader

isAnsiSupported

public static boolean isAnsiSupported()

Returns whether ANSI escapes codes should be written to the console output.

The return value is true by default if the JLine terminal is enabled and false otherwise. It may be overridden using the ANSI_OVERRIDE_PROPERTY system property.

Returns:

true if ANSI escapes codes should be written to the console

append

public void append(org.apache.logging.log4j.core.LogEvent event)

close

public static void close()
                  throws java.io.IOException

Closes the JLine Terminal (if available) and restores the original terminal settings.

Throws:

java.io.IOException - If an I/O error occurs

createAppender

@PluginFactory
public static TerminalConsoleAppender createAppender(@Required(message="No name provided for TerminalConsoleAppender") @PluginAttribute(value="name")
                                                                    java.lang.String name,
                                                                    @PluginElement(value="Filter")
                                                                    org.apache.logging.log4j.core.Filter filter,
                                                                    @PluginElement(value="Layout")
                                                                    @Nullable org.apache.logging.log4j.core.Layout<? extends java.io.Serializable> layout,
                                                                    @PluginAttribute(value="ignoreExceptions",defaultBoolean=true)
                                                                    boolean ignoreExceptions)

Creates a new TerminalConsoleAppender.

Parameters:

name - The name of the appender

filter - The filter, can be null

layout - The layout, can be null

ignoreExceptions - If true exceptions encountered when appending events are logged, otherwise they are propagated to the caller

Returns:

The new appender