You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@logging.apache.org by ma...@apache.org on 2018/04/08 21:03:44 UTC
[3/7] logging-log4j2 git commit: LOG4J2-1802: Convert plugins manual
page to asciidoc
LOG4J2-1802: Convert plugins manual page to asciidoc
Project: http://git-wip-us.apache.org/repos/asf/logging-log4j2/repo
Commit: http://git-wip-us.apache.org/repos/asf/logging-log4j2/commit/a6744a65
Tree: http://git-wip-us.apache.org/repos/asf/logging-log4j2/tree/a6744a65
Diff: http://git-wip-us.apache.org/repos/asf/logging-log4j2/diff/a6744a65
Branch: refs/heads/master
Commit: a6744a659cbbc2a0758fdade5fe3c2bc679fe34e
Parents: 8dea0f4
Author: Matt Sicker <bo...@gmail.com>
Authored: Sun Apr 8 15:04:57 2018 -0500
Committer: Matt Sicker <bo...@gmail.com>
Committed: Sun Apr 8 16:03:36 2018 -0500
----------------------------------------------------------------------
src/site/asciidoc/manual/plugins.adoc | 262 +++++++++++++++++++++++++++++
src/site/xdoc/manual/plugins.xml | 257 ----------------------------
2 files changed, 262 insertions(+), 257 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/logging-log4j2/blob/a6744a65/src/site/asciidoc/manual/plugins.adoc
----------------------------------------------------------------------
diff --git a/src/site/asciidoc/manual/plugins.adoc b/src/site/asciidoc/manual/plugins.adoc
new file mode 100644
index 0000000..5b3a988
--- /dev/null
+++ b/src/site/asciidoc/manual/plugins.adoc
@@ -0,0 +1,262 @@
+////
+ 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 <rg...@apache.org>; Matt Sicker <ma...@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`.
http://git-wip-us.apache.org/repos/asf/logging-log4j2/blob/a6744a65/src/site/xdoc/manual/plugins.xml
----------------------------------------------------------------------
diff --git a/src/site/xdoc/manual/plugins.xml b/src/site/xdoc/manual/plugins.xml
deleted file mode 100644
index c6addc8..0000000
--- a/src/site/xdoc/manual/plugins.xml
+++ /dev/null
@@ -1,257 +0,0 @@
-<?xml version="1.0"?>
-<!--
- 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
-
- http://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.
--->
-
-<document xmlns="http://maven.apache.org/XDOC/2.0"
- xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
- xsi:schemaLocation="http://maven.apache.org/XDOC/2.0 http://maven.apache.org/xsd/xdoc-2.0.xsd">
- <properties>
- <title>Log4j 2 Plugins</title>
- <author email="rgoers@apache.org">Ralph Goers</author>
- <author email="mattsicker@apache.org">Matt Sicker</author>
- </properties>
-
- <body>
- <section name="Plugins">
- <subsection name="Introduction">
- <a name="Introduction"/>
- <p>
- 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.
- </p>
- <p>
- In Log4j 2 a plugin is declared by adding a
- <a class="javadoc" href="../log4j-core/apidocs/org/apache/logging/log4j/core/config/plugins/Plugin.html">@Plugin</a>
- annotation to the class declaration. During initialization the
- <a class="javadoc" href="../log4j-core/apidocs/org/apache/logging/log4j/core/config/Configuration.html">Configuration</a>
- will invoke the
- <a class="javadoc" href="../log4j-core/apidocs/org/apache/logging/log4j/core/config/plugins/util/PluginManager.html">PluginManager</a>
- to load the built-in Log4j plugins as well as any custom plugins. The <code>PluginManager</code> locates
- plugins by looking in five places:
- </p>
- <ol>
- <li>Serialized plugin listing files on the classpath. These files are generated automatically during
- the build (more details below).</li>
- <li>(OSGi only) Serialized plugin listing files in each active OSGi bundle. A <code>BundleListener</code>
- is added on activation to continue checking new bundles after <code>log4j-core</code> has started.</li>
- <li>A comma-separated list of packages specified by the <code>log4j.plugin.packages</code>
- system property.</li>
- <li>Packages passed to the static <code>PluginManager.addPackages</code> method (before Log4j configuration
- occurs).</li>
- <li>The <a href="./configuration.html#ConfigurationSyntax">packages</a> declared in your log4j2
- configuration file.</li>
- </ol>
- <p>
- If multiple Plugins specify the same (case-insensitive) <code>name</code>, then the load order above
- determines which one will be used. For example, to override the <code>File</code> plugin which is provided
- by the built-in <code>FileAppender</code> class, you would need to place your plugin in a JAR file in the
- CLASSPATH ahead of<code>log4j-core.jar</code>. 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
- <a class="javadoc" href="http://www.osgi.org/javadoc/r5/core/org/osgi/framework/BundleContext.html#getBundles()">getBundles()</a>
- and
- <a class="javadoc" href="http://www.osgi.org/javadoc/r5/core/org/osgi/framework/SynchronousBundleListener.html">SynchronousBundleListener</a>.
- 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
- -->
- </p>
- <p>
- 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,
- <code>org.apache.logging.log4j.core.config.plugins.processor.PluginProcessor</code>. To do this using
- Apache Maven, add the following execution to your <i>maven-compiler-plugin</i> (version 2.2 or higher)
- build plugin:
- </p>
- <pre class="prettyprint linenums"><![CDATA[
-<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>
- ]]></pre>
- <p>
- 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.
- </p>
- </subsection>
- <subsection name="Core">
- <a name="Core"/>
- <p>
- 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.
- </p>
- <p>
- Every Core plugin must declare a static method annotated with <code>@PluginFactory</code> or
- <code>@PluginBuilderFactory</code>. The former is used for static factory methods that provide all options
- as method parameters, and the latter is used to construct a new <code>Builder<T></code> class whose
- fields are used for injecting attributes and child nodes. To allow the <code>Configuration</code> 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 <code>FileAppender</code>). See <a href="extending.html#Plugin_Builders">Extending
- Log4j with Plugin Builders</a> for more details.
- </p>
- <h4>Attribute Types</h4>
- <dl>
- <dt><a class="javadoc" href="../log4j-core/apidocs/org/apache/logging/log4j/core/config/plugins/PluginAttribute.html">PluginAttribute</a></dt>
- <dd>The parameter must be convertible from a String using a <a href="#TypeConverters">TypeConverter</a>.
- Most built-in types are already supported, but custom <code>TypeConverter</code> plugins may also be
- provided for more type support. Note that <code>PluginBuilderAttribute</code> can be used in builder class
- fields as an easier way to provide default values.</dd>
- <dt><a class="javadoc" href="../log4j-core/apidocs/org/apache/logging/log4j/core/config/plugins/PluginElement.html">PluginElement</a></dt>
- <dd>The parameter may represent a complex object that itself has parameters that can be configured.
- This also supports injecting an array of elements.</dd>
- <dt><a class="javadoc" href="../log4j-core/apidocs/org/apache/logging/log4j/core/config/plugins/PluginConfiguration.html">PluginConfiguration</a></dt>
- <dd>The current <code>Configuration</code> object will be passed to the plugin as a parameter.</dd>
- <dt><a class="javadoc" href="../log4j-core/apidocs/org/apache/logging/log4j/core/config/plugins/PluginNode.html">PluginNode</a></dt>
- <dd>The current <code>Node</code> being parsed will be passed to the plugin as a parameter.</dd>
- <dt><a class="javadoc" href="../log4j-core/apidocs/org/apache/logging/log4j/core/config/plugins/PluginValue.html">PluginValue</a></dt>
- <dd>The value of the current <code>Node</code> or its attribute named <code>value</code>.</dd>
- </dl>
- <h4>Constraint Validators</h4>
- <p>
- Plugin factory fields and parameters can be automatically validated at runtime using constraint validators
- inspired by the <a href="http://beanvalidation.org/">Bean Validation spec</a>. The following annotations
- are bundled in Log4j, but custom
- <a class="javadoc" href="../log4j-core/apidocs/org/apache/logging/log4j/core/config/plugins/validation/ConstraintValidator.html">ConstraintValidators</a>
- can be created as well.
- </p>
- <dl>
- <dt><a class="javadoc" href="../log4j-core/apidocs/org/apache/logging/log4j/core/config/plugins/validation/constraints/Required.html">Required</a></dt>
- <dd>This annotation validates that a value is non-empty. This covers a check for <code>null</code> as well
- as several other scenarios: empty <code>CharSequence</code> objects, empty arrays, empty <code>Collection</code>
- instances, and empty <code>Map</code> instances.</dd>
- <dt><a class="javadoc" href="../log4j-core/apidocs/org/apache/logging/log4j/core/config/plugins/validation/constraints/ValidHost.html">ValidHost</a></dt>
- <dd>This annotation validates that a value corresponds to a valid hostname. This uses the same validation as
- <a class="javadoc" href="http://docs.oracle.com/javase/8/docs/api/java/net/InetAddress.html#getByName-java.lang.String-">InetAddress::getByName</a>.</dd>
- <dt><a class="javadoc" href="../log4j-core/apidocs/org/apache/logging/log4j/core/config/plugins/validation/constraints/ValidPort.html">ValidPort</a></dt>
- <dd>This annotation validates that a value corresponds to a valid port number between 0 and 65535.</dd>
- </dl>
- </subsection>
- <subsection name="Converters">
- <a name="Converters"/>
- <p>
- Converters are used by
- <a class="javadoc" href="../log4j-core/apidocs/org/apache/logging/log4j/core/layout/PatternLayout.html">PatternLayout</a>
- to render the elements identified by the conversion pattern. Every converter must specify its category as
- "Converter" on the <code>@Plugin</code> annotation, have a static <code>newInstance</code> method that
- accepts an array of <code>String</code>s as its only parameter and returns an instance of the Converter, and
- must have a <code>@ConverterKeys</code> annotation present that contains the array of converter patterns
- that will cause the Converter to be selected. Converters that are meant to handle <code>LogEvent</code>s
- must extend the
- <a class="javadoc" href="../log4j-core/apidocs/org/apache/logging/log4j/core/layout/LogEventPatternConverter.html">LogEventPatternConverter</a>
- class and must implement a format method that accepts a <code>LogEvent</code> and a <code>StringBuilder</code>
- as arguments. The Converter should append the result of its operation to the <code>StringBuilder</code>.
- </p>
- <p>
- A second type of Converter is the FileConverter - which must have "FileConverter" specified in the
- category attribute of the <code>@Plugin</code> annotation. While similar to a <code>LogEventPatternConverter</code>,
- instead of a single format method these Converters will have two variations; one that takes an
- <code>Object</code> and one that takes an array of <code>Object</code>s instead of the <code>LogEvent</code>.
- Both append to the provided <code>StringBuilder</code> in the same fashion as a <code>LogEventPatternConverter</code>.
- These Converters are typically used by the <code>RollingFileAppender</code> to construct the name of the
- file to log to.
- </p>
- <p>
- If multiple Converters specify the same <code>ConverterKeys</code>, then the load order above determines
- which one will be used. For example, to override the <code>%date</code> converter which is provided by the
- built-in <code>DatePatternConverter</code> class, you would need to place your plugin in a JAR file in the
- CLASSPATH ahead of<code>log4j-core.jar</code>. This is not recommended; pattern ConverterKeys collisions
- will cause a warning to be emitted. Try to use unique ConverterKeys for your custom pattern converters.
- </p>
- </subsection>
- <subsection name="KeyProviders">
- <a name="KeyProviders"/>
- <p>
- 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
- <a class="javadoc" href="../log4j-core/apidocs/org/apache/logging/log4j/core/util/SecretKeyProvider.html">SecretKeyProvider</a>
- interface.
- </p>
- </subsection>
- <subsection name="Lookups">
- <a name="Lookups"/>
- <p>
- Lookups are perhaps the simplest plugins of all. They must declare their type as "Lookup" on the
- plugin annotation and must implement the
- <a class="javadoc" href="../log4j-core/apidocs/org/apache/logging/log4j/core/lookup/StrLookup.html">StrLookup</a>
- 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 ${<var>name</var>:key} where <var>name</var> is the name specified in the Plugin annotation and
- key is the name of the item to locate.
- </p>
- </subsection>
- <subsection name="TypeConverters">
- <a name="TypeConverters"/>
- <p>
- <a class="javadoc" href="../log4j-core/apidocs/org/apache/logging/log4j/core/config/plugins/convert/TypeConverter.html">TypeConverter</a>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 <code>@PluginElement</code> annotation; now, any
- type supported by the type conversion system can be used in a <code>@PluginAttribute</code> parameter.
- Conversion of enum types are supported on demand and do not require custom <code>TypeConverter</code>
- classes. A large number of built-in Java classes are already supported; see
- <a class="javadoc" href="../log4j-core/apidocs/org/apache/logging/log4j/core/config/plugins/convert/TypeConverters.html">TypeConverters</a>
- for a more exhaustive listing.
- </p>
- <p>
- Unlike other plugins, the plugin name of a <code>TypeConverter</code> is purely cosmetic. Appropriate
- type converters are looked up via the <code>Type</code> interface rather than via <code>Class<?></code>
- objects only. Do note that <code>TypeConverter</code> plugins must have a default constructor.
- </p>
- </subsection>
- </section>
- <section name="Developer Notes">
- <a name="DeveloperNotes"/>
- <p>
- If a plugin class implements
- <a class="javadoc" href="http://docs.oracle.com/javase/6/docs/api/java/util/Collection.html">Collection</a> or
- <a class="javadoc" href="http://docs.oracle.com/javase/6/docs/api/java/util/Map.html">Map</a>, then no
- factory method is used. Instead, the class is instantiated using the default constructor, and all child
- configuration nodes are added to the <code>Collection</code> or <code>Map</code>.
- </p>
- </section>
- </body>
-</document>