Log4j2研究之Converters

按照log4j2的设计——配置文件中的任何内容都属于一类plugin，所以Converters依然属于plugin——类型（category）为“Converter”的plugin。

1. 概述

“Converters are used by PatternLayout to render the elements identified by the conversion pattern.”
1. 以上内容依然是复制于log4j2的官方文档Converters - Office Site。
2. 从这句话中我们明了：Converters是用来处理节点的pattern属性所配置值的渲染问题。

2. 继承链

依然是让我们先来看看log4j2对于Converters的继承链的设计。

由以上类层次结构图中：
1. log4j2提供了种类繁多的默认Converter。
2. 我们配置pattern时的常用标记均可在其中找到相应的实现类。例如 从MDC中取值的 %X{xxx}对应的则是MdcPatternConverter；换行符%n对应的LineSeparatorPatternConverter；%d对应的DatePatternConverter；%p对应的LevelPatternConverter等等。

3. 自定义Converter

下面我们将实现一个自定义的PatternConveter。

// 1. 必须将category属性的值指定为"Converter"
@Plugin(name = "LqPatternConverter", category = PatternConverter.CATEGORY)
// 2. 必须有一个@ConverterKeys的注解修饰，以便我们可以在配置时使用 %lq 进行选择。  
@ConverterKeys({ "lq", "luoqi" })
@PerformanceSensitive("allocation")
public final class LqPatternConverter extends NamePatternConverter {
    /**
     * Singleton.
     */
    private static final LqPatternConverter INSTANCE =
        new LqPatternConverter(null);

    /**
     * Private constructor.
     *
     * @param options options, may be null.
     */
    private LqPatternConverter(final String[] options) {
        super("Lq", "lq", options);
    }

    // 3. 内部必须有一个满足特定签名约定的名为"newInstance"的静态public方法
    //    此项约定的源码位置位于 PatternParser 类的私有方法 createConverter 中。
    /**
     * Obtains an instance of pattern converter.
     *
     * @param options options, may be null.
     * @return instance of pattern converter.
     */
    public static LqPatternConverter newInstance(
        final String[] options) {
        if (options == null || options.length == 0) {
            return INSTANCE;
        }

        return new LqPatternConverter(options);
    }

    @Override
    public void format(final LogEvent event, final StringBuilder toAppendTo) {
        toAppendTo.append("LQ~18");
    }
}

接下来我们就需要进行一些配置工作，让log4j2知道如何使用该Converter。

<Configuration status="TRACE" monitorInterval="5"
    packages="slf4j._log4j2.classes.core.pattern">    
    
    
    <PatternLayout pattern="[%p];[%tn];[%lq];[%luoqi] %n %msg %n %n" /> 
Configuration>

相应的日志输出如下：

最后依然附上一张执行堆栈图：

4. Links

1. Converters - Office Site
2. Patterns - Office Site - 默认的pattern格式