Deprecate legacy annotations and remove their usage

We deprecate for removal the old `o.a.l.l.c.plugins` annotations and
remove their usages.

Author: ppkarwasz

log4j-1.2-api/src/main/java/org/apache/log4j/layout/Log4j1SyslogLayout.java

@@ -26,14 +26,14 @@
 import org.apache.logging.log4j.core.LogEvent;
 import org.apache.logging.log4j.core.StringLayout;
 import org.apache.logging.log4j.core.config.Configuration;
-import org.apache.logging.log4j.core.config.plugins.PluginBuilderFactory;
 import org.apache.logging.log4j.core.layout.AbstractStringLayout;
 import org.apache.logging.log4j.core.net.Facility;
 import org.apache.logging.log4j.core.net.Priority;
 import org.apache.logging.log4j.core.pattern.DatePatternConverter;
 import org.apache.logging.log4j.core.pattern.LogEventPatternConverter;
 import org.apache.logging.log4j.core.util.NetUtils;
 import org.apache.logging.log4j.plugins.Configurable;
+import org.apache.logging.log4j.plugins.Factory;
 import org.apache.logging.log4j.plugins.Plugin;
 import org.apache.logging.log4j.plugins.PluginBuilderAttribute;
 import org.apache.logging.log4j.plugins.PluginElement;
@@ -58,10 +58,9 @@ public final class Log4j1SyslogLayout extends AbstractStringLayout {
      * <li>escapeNL: Pattern to use for replacing newlines.</li>
      * <li>charset: The character set.</li>
      * </ul>
-     * @param <B> the builder type
      */
-    public static class Builder<B extends Builder<B>> extends AbstractStringLayout.Builder<B>
-            implements org.apache.logging.log4j.core.util.Builder<Log4j1SyslogLayout> {
+    public static class Builder extends AbstractStringLayout.Builder<Builder>
+            implements org.apache.logging.log4j.plugins.util.Builder<Log4j1SyslogLayout> {
 
         public Builder() {
             setCharset(StandardCharsets.UTF_8);
@@ -105,30 +104,30 @@ public Layout getMessageLayout() {
             return messageLayout;
         }
 
-        public B setFacility(final Facility facility) {
+        public Builder setFacility(final Facility facility) {
             this.facility = facility;
             return asBuilder();
         }
 
-        public B setFacilityPrinting(final boolean facilityPrinting) {
+        public Builder setFacilityPrinting(final boolean facilityPrinting) {
             this.facilityPrinting = facilityPrinting;
             return asBuilder();
         }
 
-        public B setHeader(final boolean header) {
+        public Builder setHeader(final boolean header) {
             this.header = header;
             return asBuilder();
         }
 
-        public B setMessageLayout(final Layout messageLayout) {
+        public Builder setMessageLayout(final Layout messageLayout) {
             this.messageLayout = messageLayout;
             return asBuilder();
         }
     }
 
-    @PluginBuilderFactory
-    public static <B extends Builder<B>> B newBuilder() {
-        return new Builder<B>().asBuilder();
+    @Factory
+    public static Builder newBuilder() {
+        return new Builder().asBuilder();
     }
 
     /**

log4j-core-test/src/main/java/org/apache/logging/log4j/core/test/appender/FailOnceAppender.java

@@ -24,11 +24,11 @@
 import org.apache.logging.log4j.core.LogEvent;
 import org.apache.logging.log4j.core.appender.AbstractAppender;
 import org.apache.logging.log4j.core.config.Property;
-import org.apache.logging.log4j.core.config.plugins.PluginAttribute;
-import org.apache.logging.log4j.core.config.plugins.PluginFactory;
 import org.apache.logging.log4j.core.util.Throwables;
 import org.apache.logging.log4j.plugins.Configurable;
+import org.apache.logging.log4j.plugins.Factory;
 import org.apache.logging.log4j.plugins.Plugin;
+import org.apache.logging.log4j.plugins.PluginAttribute;
 import org.apache.logging.log4j.plugins.validation.constraints.Required;
 
 /**
@@ -72,7 +72,7 @@ public synchronized List<LogEvent> drainEvents() {
         return oldEvents;
     }
 
-    @PluginFactory
+    @Factory
     public static FailOnceAppender createAppender(
             @PluginAttribute("name") @Required(message = "A name for the Appender must be specified") final String name,
             @PluginAttribute("throwableClassName") final String throwableClassName) {

log4j-core-test/src/test/java/org/apache/logging/log4j/core/config/ReconfigurationDeadlockTest.java

@@ -32,12 +32,12 @@
 import org.apache.logging.log4j.core.Layout;
 import org.apache.logging.log4j.core.LogEvent;
 import org.apache.logging.log4j.core.appender.AbstractAppender;
-import org.apache.logging.log4j.core.config.plugins.PluginAttribute;
-import org.apache.logging.log4j.core.config.plugins.PluginElement;
-import org.apache.logging.log4j.core.config.plugins.PluginFactory;
 import org.apache.logging.log4j.core.test.junit.LoggerContextSource;
 import org.apache.logging.log4j.plugins.Configurable;
+import org.apache.logging.log4j.plugins.Factory;
 import org.apache.logging.log4j.plugins.Plugin;
+import org.apache.logging.log4j.plugins.PluginAttribute;
+import org.apache.logging.log4j.plugins.PluginElement;
 import org.apache.logging.log4j.plugins.validation.constraints.Required;
 import org.junit.jupiter.api.AfterEach;
 import org.junit.jupiter.api.Assertions;
@@ -138,7 +138,7 @@ private TestAppender(
             this.logger = LogManager.getRootLogger();
         }
 
-        @PluginFactory
+        @Factory
         public static TestAppender createAppender(
                 @PluginAttribute("name") @Required(message = "A name for the Appender must be specified")
                         final String name,

log4j-core/pom.xml

@@ -112,6 +112,11 @@
               <artifactId>log4j-plugin-processor</artifactId>
               <version>${project.version}</version>
             </path>
+            <path>
+              <groupId>org.apache.logging.log4j</groupId>
+              <artifactId>log4j-docgen</artifactId>
+              <version>0.8.0-SNAPSHOT</version>
+            </path>
           </annotationProcessorPaths>
         </configuration>
       </plugin>

log4j-core/src/main/java/org/apache/logging/log4j/core/appender/AbstractAppender.java

@@ -47,11 +47,26 @@ public abstract class AbstractAppender extends AbstractFilterable implements App
      */
     public abstract static class Builder<B extends Builder<B>> extends AbstractFilterable.Builder<B> {
 
+        /**
+         * Determines whether to propagate logging exceptions
+         * <p>
+         *     If set to {@code true} (default), exceptions that occur during logging will appear in the status logger.
+         * </p>
+         * <p>
+         *     If set to {@code false}, exceptions will be propagates to the caller.
+         * </p>
+         */
         @PluginBuilderAttribute
         private boolean ignoreExceptions = true;
-
+        /**
+         * Formats the log events
+         */
         private Layout layout;
+        /**
+         * Name of the appender to use in references
+         */
         private String name;
+
         private Configuration configuration;
 
         public String getName() {

log4j-core/src/main/java/org/apache/logging/log4j/core/appender/AbstractOutputStreamAppender.java

@@ -16,6 +16,7 @@
  */
 package org.apache.logging.log4j.core.appender;
 
+import java.io.OutputStream;
 import java.util.concurrent.TimeUnit;
 import org.apache.logging.log4j.core.Filter;
 import org.apache.logging.log4j.core.Layout;
@@ -38,12 +39,34 @@ public abstract class AbstractOutputStreamAppender<M extends OutputStreamManager
      */
     public abstract static class Builder<B extends Builder<B>> extends AbstractAppender.Builder<B> {
 
+        /**
+         * Determines whether to use a buffered {@code OutputStream}
+         * <p>
+         *     If set to {@code true} (default) the appender will buffer messages before sending them. This attribute is
+         *     ignored if {@code immediateFlush} is set to {@code true}.
+         * </p>
+         */
         @PluginBuilderAttribute
         private boolean bufferedIo = true;
 
+        /**
+         * Size of the buffer in bytes
+         */
         @PluginBuilderAttribute
         private int bufferSize = Constants.ENCODER_BYTE_BUFFER_SIZE;
 
+        /**
+         * Flushes the underlying {@code OutputStream} after each event
+         * <p>
+         *     The effects of this setting depend on the output stream implementation (see {@link OutputStream#flush()}.
+         *     In the case of files, for example, setting this attribute to {@code true}, guarantees that all bytes
+         *     written are passed to the operating system, but it <strong>does not</strong> guarantee that they are
+         *     actually written to a physical device.
+         * </p>
+         * <p>
+         *     Setting this to {@code true} automatically disables buffering.
+         * </p>
+         */
         @PluginBuilderAttribute
         private boolean immediateFlush = true;
 

log4j-core/src/main/java/org/apache/logging/log4j/core/appender/AsyncAppender.java

@@ -38,10 +38,10 @@
 import org.apache.logging.log4j.core.config.Configuration;
 import org.apache.logging.log4j.core.config.ConfigurationException;
 import org.apache.logging.log4j.core.config.Property;
-import org.apache.logging.log4j.core.config.plugins.PluginBuilderFactory;
 import org.apache.logging.log4j.core.config.plugins.PluginConfiguration;
 import org.apache.logging.log4j.core.filter.AbstractFilterable;
 import org.apache.logging.log4j.plugins.Configurable;
+import org.apache.logging.log4j.plugins.Factory;
 import org.apache.logging.log4j.plugins.Plugin;
 import org.apache.logging.log4j.plugins.PluginAliases;
 import org.apache.logging.log4j.plugins.PluginBuilderAttribute;
@@ -252,13 +252,13 @@ private void logToErrorAppenderIfNecessary(final boolean appendSuccessful, final
         }
     }
 
-    @PluginBuilderFactory
+    @Factory
     public static Builder newBuilder() {
         return new Builder();
     }
 
-    public static class Builder<B extends Builder<B>> extends AbstractFilterable.Builder<B>
-            implements org.apache.logging.log4j.core.util.Builder<AsyncAppender> {
+    public static class Builder extends AbstractFilterable.Builder<Builder>
+            implements org.apache.logging.log4j.plugins.util.Builder<AsyncAppender> {
 
         @PluginElement("AppenderRef")
         @Required(message = "No appender references provided to AsyncAppender")
@@ -277,6 +277,9 @@ public static class Builder<B extends Builder<B>> extends AbstractFilterable.Bui
         @PluginBuilderAttribute
         private int bufferSize = DEFAULT_QUEUE_SIZE;
 
+        /**
+         * Name of the appender to use in references
+         */
         @PluginBuilderAttribute
         @Required(message = "No name provided for AsyncAppender")
         private String name;

log4j-core/src/main/java/org/apache/logging/log4j/core/appender/FailoverAppender.java

@@ -181,8 +181,13 @@ public String toString() {
      * @param retryIntervalSeconds The retry interval in seconds.
      * @param config The current Configuration (passed by the Configuration when the appender is created).
      * @param filter A Filter (optional).
-     * @param ignoreExceptions If {@code "true"} (default) exceptions encountered when appending events are logged; otherwise
-     *               they are propagated to the caller.
+     * @param ignoreExceptions Determines whether to propagate logging exceptions
+     *        <p>
+     *            If set to {@code true} (default), exceptions that occur during logging will appear in the status logger.
+     *        </p>
+     *        <p>
+     *            If set to {@code false}, exceptions will be propagates to the caller.
+     *        </p>
      * @return The FailoverAppender that was created.
      */
     @PluginFactory

log4j-core/src/main/java/org/apache/logging/log4j/core/config/arbiters/ClassArbiter.java

@@ -17,8 +17,8 @@
 package org.apache.logging.log4j.core.config.arbiters;
 
 import org.apache.logging.log4j.core.config.plugins.PluginBuilderAttribute;
-import org.apache.logging.log4j.core.config.plugins.PluginBuilderFactory;
 import org.apache.logging.log4j.plugins.Configurable;
+import org.apache.logging.log4j.plugins.Factory;
 import org.apache.logging.log4j.plugins.Plugin;
 import org.apache.logging.log4j.util.LoaderUtil;
 
@@ -40,7 +40,7 @@ public boolean isCondition() {
         return LoaderUtil.isClassAvailable(className);
     }
 
-    @PluginBuilderFactory
+    @Factory
     public static ClassArbiter.Builder newBuilder() {
         return new ClassArbiter.Builder();
     }

log4j-core/src/main/java/org/apache/logging/log4j/core/config/arbiters/DefaultArbiter.java

@@ -16,8 +16,8 @@
  */
 package org.apache.logging.log4j.core.config.arbiters;
 
-import org.apache.logging.log4j.core.config.plugins.PluginBuilderFactory;
 import org.apache.logging.log4j.plugins.Configurable;
+import org.apache.logging.log4j.plugins.Factory;
 import org.apache.logging.log4j.plugins.Plugin;
 
 /**
@@ -35,7 +35,7 @@ public boolean isCondition() {
         return true;
     }
 
-    @PluginBuilderFactory
+    @Factory
     public static Builder newBuilder() {
         return new Builder();
     }