logging-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From mattsic...@apache.org
Subject svn commit: r1611524 - /logging/log4j/log4j2/trunk/src/site/xdoc/manual/plugins.xml
Date Fri, 18 Jul 2014 01:38:03 GMT
Author: mattsicker
Date: Fri Jul 18 01:38:03 2014
New Revision: 1611524

URL: http://svn.apache.org/r1611524
Log:
Clarify current custom plugin processing in manual.

Modified:
    logging/log4j/log4j2/trunk/src/site/xdoc/manual/plugins.xml

Modified: logging/log4j/log4j2/trunk/src/site/xdoc/manual/plugins.xml
URL: http://svn.apache.org/viewvc/logging/log4j/log4j2/trunk/src/site/xdoc/manual/plugins.xml?rev=1611524&r1=1611523&r2=1611524&view=diff
==============================================================================
--- logging/log4j/log4j2/trunk/src/site/xdoc/manual/plugins.xml (original)
+++ logging/log4j/log4j2/trunk/src/site/xdoc/manual/plugins.xml Fri Jul 18 01:38:03 2014
@@ -35,9 +35,39 @@
             goals 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 Plugin annotation to the class declaration.
During
-            initialization the Configuration will invoke the PluginManager to locate all
the Log4j plugins
-            that are located in the declared <a href="./configuration.html#ConfigurationSyntax">packages</a>.
+            In Log4j 2 a plugin is declared by adding a <code>@Plugin</code>
annotation to the class declaration. During
+            initialization the Configuration will invoke the PluginManager to load all the
serialized plugin listing
+            files on the class path. These 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>
build plugin:
+          </p>
+          <pre class="prettyprint linenums"><![CDATA[
+<plugin>
+  <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>
+        <process>only</process>
+        <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.
@@ -60,9 +90,9 @@
           </p>
           <h4>Attribute Types</h4>
             <dl>
-              <dt>PluginAttr</dt>
+              <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>
+              boolean, numeric value, or any other Object that can be created from a String
value.</dd>
               <dt>PluginElement</dt>
               <dd>The parameter may represent a complex object that itself has parameters
that can be configured.</dd>
               <dt>PluginConfiguration</dt>
@@ -111,44 +141,6 @@
             key is the name of the item to locate.
           </p>
         </subsection>
-        <subsection name="Plugin Preloading">
-          <a name="PluginPreloading"/>
-          <!-- FIXME: this documentation could probably be simplified quite a bit thanks
to LOG4J2-595 -->
-          <p>
-          Scanning for annotated classes dynamically takes a bit of time during application
initialization. Log4j
-          avoids this by scanning its classes during the build. In the Maven build, the PluginManager
is invoked as
-          shown below and then the resulting Map is stored in a file in the jar being constructed.
Log4j will locate
-          all the files created this way and and preload them, which shortens startup time
considerably. Adding the
-          following plugin definition to your project's pom.xml will cause the plugin manager
to be called during the
-          build. It will store the resulting file in the correct location under the directory
specified in the first
-          argument after scanning all the components located under the package specified
in the second argument.
-          </p>
-          <pre class="prettyprint linenums"><![CDATA[<plugin>
-  <groupId>org.codehaus.mojo</groupId>
-  <artifactId>exec-maven-plugin</artifactId>
-  <version>1.2.1</version>
-  <executions>
-    <execution>
-      <phase>process-classes</phase>
-      <goals>
-        <goal>java</goal>
-      </goals>
-    </execution>
-  </executions>
-  <configuration>
-    <mainClass>org.apache.logging.log4j.core.config.plugins.util.PluginManager</mainClass>
-    <arguments>
-      <argument>${project.build.outputDirectory}</argument>
-      <argument>org.myorg.myproject.log4j</argument>
-    </arguments>
-  </Configuration>
-</plugin>]]></pre>
-          <h4>Using the Java annotation processor</h4>
-          <p>
-            Annotated classes marked with <code>@Plugin</code> or <code>@PluginAliases</code>
are now automatically
-            preloaded when you include the log4j-core artifact.
-          </p>
-        </subsection>
       </section>
     </body>
 </document>



Mime
View raw message