////
    Licensed to the Apache Software Foundation (ASF) under one or more
    contributor license agreements. See the NOTICE file distributed with
    this work for additional information regarding copyright ownership.
    The ASF licenses this file to You under the Apache License, Version 2.0
    (the "License"); you may not use this file except in compliance with
    the License. You may obtain a copy of the License at

        https://www.apache.org/licenses/LICENSE-2.0

    Unless required by applicable law or agreed to in writing, software
    distributed under the License is distributed on an "AS IS" BASIS,
    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    See the License for the specific language governing permissions and
    limitations under the License.
////
= Plugins
Ralph Goers <rgoers@apache.org>; Matt Sicker <mattsicker@apache.org>

Log4j 1.x allowed for extension by requiring class attributes on most of
the configuration declarations. In the case of some elements, notably
the PatternLayout, the only way to add new pattern converters was to
extend the PatternLayout class and add them via code. One goal of Log4j
2 is to make extending it extremely easy through the use of plugins.

In Log4j 2 a plugin is declared by adding a
link:../log4j-core/apidocs/org/apache/logging/log4j/core/config/plugins/Plugin.html[`@Plugin`]
annotation to the class declaration. During initialization the
link:../log4j-core/apidocs/org/apache/logging/log4j/core/config/Configuration.html[`Configuration`]
will invoke the
link:../log4j-core/apidocs/org/apache/logging/log4j/core/config/plugins/util/PluginManager.html[`PluginManager`]
to load the built-in Log4j plugins as well as any custom plugins. The
`PluginManager` locates plugins by looking in five places:

1.  Serialized plugin listing files on the classpath. These files are
generated automatically during the build (more details below).
2.  (OSGi only) Serialized plugin listing files in each active OSGi
bundle. A `BundleListener` is added on activation to continue checking
new bundles after `log4j-core` has started.
3.  A comma-separated list of packages specified by the
`log4j.plugin.packages` system property.
4.  Packages passed to the static `PluginManager.addPackages` method
(before Log4j configuration occurs).
5.  The link:./configuration.html#ConfigurationSyntax[packages] declared
in your log4j2 configuration file.

If multiple Plugins specify the same (case-insensitive) `name`, then the
load order above determines which one will be used. For example, to
override the `File` plugin which is provided by the built-in
`FileAppender` class, you would need to place your plugin in a JAR file
in the CLASSPATH ahead of`log4j-core.jar`. This is not recommended;
plugin name collisions will cause a warning to be emitted. Note that in
an OSGi environment, the order that bundles are scanned for plugins
generally follows the same order that bundles were installed into the
framework. See
http://www.osgi.org/javadoc/r5/core/org/osgi/framework/BundleContext.html#getBundles()[`getBundles()`]
and
http://www.osgi.org/javadoc/r5/core/org/osgi/framework/SynchronousBundleListener.html[`SynchronousBundleListener`].
In short, name collisions are even more unpredictable in an OSGi environment.
////
TODO: in future, plugins will be able to be annotated with @Order which can override priorities
////

Serialized plugin listing files are generated by an annotation processor
contained in the log4j-core artifact which will automatically scan your
code for Log4j 2 plugins and output a metadata file in your processed
classes. There is nothing extra that needs to be done to enable this;
the Java compiler will automatically pick up the annotation processor on
the class path unless you explicitly disable it. In that case, it would
be important to add another compiler pass to your build process that
only handles annotation processing using the Log4j 2 annotation
processor class,
`org.apache.logging.log4j.core.config.plugins.processor.PluginProcessor`.
To do this using Apache Maven, add the following execution to your
_maven-compiler-plugin_ (version 2.2 or higher) build plugin:

[source,xml]
----
<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-compiler-plugin</artifactId>
  <version>3.1</version>
  <executions>
    <execution>
      <id>log4j-plugin-processor</id>
      <goals>
        <goal>compile</goal>
      </goals>
      <phase>process-classes</phase>
      <configuration>
        <proc>only</proc>
        <annotationProcessors>
          <annotationProcessor>org.apache.logging.log4j.core.config.plugins.processor.PluginProcessor</annotationProcessor>
        </annotationProcessors>
      </configuration>
    </execution>
  </executions>
</plugin>
----

As the configuration is processed the appropriate plugins will be
automatically configured and initialized. Log4j 2 utilizes a few
different categories of plugins which are described in the following
sections.

[#Core]
== Core

Core plugins are those that are directly represented by an element in a
configuration file, such as an Appender, Layout, Logger or Filter.
Custom plugins that conform to the rules laid out in the next paragraph
may simply be referenced in the configuration, provided they are
appropriate configured to be loaded by the PluginManager.

Every Core plugin must declare a static method annotated with
`@PluginFactory` or `@PluginBuilderFactory`. The former is used for
static factory methods that provide all options as method parameters,
and the latter is used to construct a new `Builder<T>` class whose
fields are used for injecting attributes and child nodes. To allow the
`Configuration` to pass the correct parameters to the method, every
parameter to the method must be annotated as one of the following
attribute types. Each attribute or element annotation must include the
name that must be present in the configuration in order to match the
configuration item to its respective parameter. For plugin builders, the
names of the fields will be used by default if no name is specified in
the annotation. There are dozens of plugins in Log4j Core that can be
used as examples for more complex scenarios including hierarchical
builder classes (e.g., see `FileAppender`). See
link:extending.html#Plugin_Builders[Extending Log4j with Plugin
Builders] for more details.

=== Attribute Types

link:../log4j-core/apidocs/org/apache/logging/log4j/core/config/plugins/PluginAttribute.html[`PluginAttribute`]::
  The parameter must be convertible from a String using a
  link:#TypeConverters[TypeConverter]. Most built-in types are already
  supported, but custom `TypeConverter` plugins may also be provided for
  more type support. Note that `PluginBuilderAttribute` can be used in
  builder class fields as an easier way to provide default values.
link:../log4j-core/apidocs/org/apache/logging/log4j/core/config/plugins/PluginElement.html[`PluginElement`]::
  The parameter may represent a complex object that itself has
  parameters that can be configured. This also supports injecting an
  array of elements.
link:../log4j-core/apidocs/org/apache/logging/log4j/core/config/plugins/PluginConfiguration.html[`PluginConfiguration`]::
  The current `Configuration` object will be passed to the plugin as a
  parameter.
link:../log4j-core/apidocs/org/apache/logging/log4j/core/config/plugins/PluginNode.html[`PluginNode`]::
  The current `Node` being parsed will be passed to the plugin as a
  parameter.
link:../log4j-core/apidocs/org/apache/logging/log4j/core/config/plugins/PluginValue.html[`PluginValue`]::
  The value of the current `Node` or its attribute named `value`.

=== Constraint Validators

Plugin factory fields and parameters can be automatically validated at
runtime using constraint validators inspired by the
http://beanvalidation.org/[Bean Validation spec]. The following
annotations are bundled in Log4j, but custom
link:../log4j-core/apidocs/org/apache/logging/log4j/core/config/plugins/validation/ConstraintValidator.html[`ConstraintValidators`]
can be created as well.

link:../log4j-core/apidocs/org/apache/logging/log4j/core/config/plugins/validation/constraints/Required.html[`Required`]::
  This annotation validates that a value is non-empty. This covers a
  check for `null` as well as several other scenarios: empty
  `CharSequence` objects, empty arrays, empty `Collection` instances,
  and empty `Map` instances.
link:../log4j-core/apidocs/org/apache/logging/log4j/core/config/plugins/validation/constraints/ValidHost.html[`ValidHost`]::
  This annotation validates that a value corresponds to a valid
  hostname. This uses the same validation as
  http://docs.oracle.com/javase/8/docs/api/java/net/InetAddress.html#getByName-java.lang.String-[`InetAddress::getByName`].
link:../log4j-core/apidocs/org/apache/logging/log4j/core/config/plugins/validation/constraints/ValidPort.html[`ValidPort`]::
  This annotation validates that a value corresponds to a valid port
  number between 0 and 65535.

[#Converters]
== Converters

Converters are used by
link:../log4j-core/apidocs/org/apache/logging/log4j/core/layout/PatternLayout.html[`PatternLayout`]
to render the elements identified by the conversion pattern. Every
converter must specify its category as "Converter" on the `@Plugin`
annotation, have a static `newInstance` method that accepts an array of
`String` as its only parameter and returns an instance of the
Converter, and must have a `@ConverterKeys` annotation present that
contains the array of converter patterns that will cause the Converter
to be selected. Converters that are meant to handle `LogEvent` must
extend the
link:../log4j-core/apidocs/org/apache/logging/log4j/core/layout/LogEventPatternConverter.html[`LogEventPatternConverter`]
class and must implement a format method that accepts a `LogEvent` and a
`StringBuilder` as arguments. The Converter should append the result of
its operation to the `StringBuilder`.

A second type of Converter is the FileConverter - which must have
"FileConverter" specified in the category attribute of the `@Plugin`
annotation. While similar to a `LogEventPatternConverter`, instead of a
single format method these Converters will have two variations; one that
takes an `Object` and one that takes an array of `Object` instead of
the `LogEvent`. Both append to the provided `StringBuilder` in the same
fashion as a `LogEventPatternConverter`. These Converters are typically
used by the `RollingFileAppender` to construct the name of the file to
log to.

If multiple Converters specify the same `ConverterKeys`, then the load
order above determines which one will be used. For example, to override
the `%date` converter which is provided by the built-in
`DatePatternConverter` class, you would need to place your plugin in a
JAR file in the CLASSPATH ahead of`log4j-core.jar`. This is not
recommended; pattern ConverterKeys collisions will cause a warning to be
emitted. Try to use unique ConverterKeys for your custom pattern
converters.

[#KeyProviders]
== KeyProviders

Some components within Log4j may provide the ability to perform data
encryption. These components require a secret key to perform the
encryption. Applications may provide the key by creating a class that
implements the
link:../log4j-core/apidocs/org/apache/logging/log4j/core/util/SecretKeyProvider.html[`SecretKeyProvider`]
interface.

[#Lookups]
== Lookups

Lookups are perhaps the simplest plugins of all. They must declare their
type as "Lookup" on the plugin annotation and must implement the
link:../log4j-core/apidocs/org/apache/logging/log4j/core/lookup/StrLookup.html[`StrLookup`]
interface. They will have two methods; a `lookup` method that accepts a
`String` key and returns a `String` value and a second `lookup` method that
accepts both a `LogEvent` and a `String` key and returns a `String`. Lookups
may be referenced by specifying $\{name:key} where name is the name
specified in the Plugin annotation and key is the name of the item to
locate.

[#TypeConverters]
== TypeConverters

link:../log4j-core/apidocs/org/apache/logging/log4j/core/config/plugins/convert/TypeConverter.html[`TypeConverter`]s
are a sort of meta-plugin used for converting strings into other types
in a plugin factory method parameter. Other plugins can already be
injected via the `@PluginElement` annotation; now, any type supported by
the type conversion system can be used in a `@PluginAttribute`
parameter. Conversion of enum types are supported on demand and do not
require custom `TypeConverter` classes. A large number of built-in Java
classes are already supported; see
link:../log4j-core/apidocs/org/apache/logging/log4j/core/config/plugins/convert/TypeConverters.html[`TypeConverters`]
for a more exhaustive listing.

Unlike other plugins, the plugin name of a `TypeConverter` is purely
cosmetic. Appropriate type converters are looked up via the `Type`
interface rather than via `Class<?>` objects only. Do note that
`TypeConverter` plugins must have a default constructor.

[#DeveloperNotes]
== Developer Notes

If a plugin class implements
http://docs.oracle.com/javase/6/docs/api/java/util/Collection.html[`Collection`]
or http://docs.oracle.com/javase/6/docs/api/java/util/Map.html[`Map`],
then no factory method is used. Instead, the class is instantiated using
the default constructor, and all child configuration nodes are added to
the `Collection` or `Map`.