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 <[email protected]> Authored: Wed Sep 24 20:54:53 2014 -0500 Committer: Matt Sicker <[email protected]> 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>
