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 2014/09/25 03:55:13 UTC
git commit: Add TypeConverter documentation and other updates.
Repository: logging-log4j2
Updated Branches:
refs/heads/master 22ada0a04 -> d46c6f7b7
Add TypeConverter documentation and other updates.
Project: http://git-wip-us.apache.org/repos/asf/logging-log4j2/repo
Commit: http://git-wip-us.apache.org/repos/asf/logging-log4j2/commit/d46c6f7b
Tree: http://git-wip-us.apache.org/repos/asf/logging-log4j2/tree/d46c6f7b
Diff: http://git-wip-us.apache.org/repos/asf/logging-log4j2/diff/d46c6f7b
Branch: refs/heads/master
Commit: d46c6f7b70999a6071da78716932be969332e1c6
Parents: 22ada0a
Author: Matt Sicker <ma...@apache.org>
Authored: Wed Sep 24 20:54:53 2014 -0500
Committer: Matt Sicker <ma...@apache.org>
Committed: Wed Sep 24 20:54:53 2014 -0500
----------------------------------------------------------------------
src/site/xdoc/manual/plugins.xml | 35 ++++++++++++++++++++++++++++++-----
1 file changed, 30 insertions(+), 5 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/logging-log4j2/blob/d46c6f7b/src/site/xdoc/manual/plugins.xml
----------------------------------------------------------------------
diff --git a/src/site/xdoc/manual/plugins.xml b/src/site/xdoc/manual/plugins.xml
index eae201f..2e3df83 100644
--- a/src/site/xdoc/manual/plugins.xml
+++ b/src/site/xdoc/manual/plugins.xml
@@ -114,19 +114,25 @@
<h4>Attribute Types</h4>
<dl>
<dt>PluginAttribute</dt>
- <dd>The parameter must resolve to a String, although it can be the String representation of a
- boolean, numeric value, or any other Object that can be created from a String value.</dd>
+ <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.</dd>
<dt>PluginElement</dt>
<dd>The parameter may represent a complex object that itself has parameters that can be configured.</dd>
<dt>PluginConfiguration</dt>
- <dd>The current Configuration object will be passed to the plugin as a parameter.</dd>
+ <dd>The current <code>Configuration</code> object will be passed to the plugin as a parameter.</dd>
+ <dt>PluginNode</dt>
+ <dd>The current <code>Node</code> being parsed will be passed to the plugin as a parameter.</dd>
+ <dt>Required</dt>
+ <dd>While not strictly an attribute, this annotation can be added to any plugin factory parameter to
+ make it automatically validated as non-<code>null</code> and non-empty.</dd>
</dl>
</subsection>
<subsection name="Converters">
<a name="Converters"/>
<p>
Converters are used by
- <a href="../log4j-core/apidocs/org/apache/logging/log4j/core/layout/PatternLayout.html">PatternLayout</a>
+ <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 type as
"Converter" on the Plugin attribute, have a static newInstance method that accepts an array of Strings as
its only parameter and returns an instance of the Converter, and must have a ConverterKeys annotation
@@ -156,7 +162,8 @@
<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 href="../log4j-core/apidocs/org/apache/logging/log4j/core/helpers/SecretKeyProvider.html">SecretKeyProvider</a>
+ implements the
+ <a class="javadoc" href="../log4j-core/apidocs/org/apache/logging/log4j/core/helpers/SecretKeyProvider.html">SecretKeyProvider</a>
interface.
</p>
</subsection>
@@ -171,6 +178,24 @@
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">TypeConverters</a>
+ 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>
</body>
</document>