logging-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From mattsic...@apache.org
Subject svn commit: r1615849 - /logging/log4j/log4j2/trunk/log4j-core/src/main/java/org/apache/logging/log4j/core/Appender.java
Date Tue, 05 Aug 2014 02:32:14 GMT
Author: mattsicker
Date: Tue Aug  5 02:32:14 2014
New Revision: 1615849

URL: http://svn.apache.org/r1615849
Log:
Expand on javadoc.

  - Provide some advice for implementors of Appender.
  - Some best practices that we follow (use of manager classes for shared resources, etc.)

Modified:
    logging/log4j/log4j2/trunk/log4j-core/src/main/java/org/apache/logging/log4j/core/Appender.java

Modified: logging/log4j/log4j2/trunk/log4j-core/src/main/java/org/apache/logging/log4j/core/Appender.java
URL: http://svn.apache.org/viewvc/logging/log4j/log4j2/trunk/log4j-core/src/main/java/org/apache/logging/log4j/core/Appender.java?rev=1615849&r1=1615848&r2=1615849&view=diff
==============================================================================
--- logging/log4j/log4j2/trunk/log4j-core/src/main/java/org/apache/logging/log4j/core/Appender.java
(original)
+++ logging/log4j/log4j2/trunk/log4j-core/src/main/java/org/apache/logging/log4j/core/Appender.java
Tue Aug  5 02:32:14 2014
@@ -19,14 +19,27 @@ package org.apache.logging.log4j.core;
 import java.io.Serializable;
 
 /**
- * Appends log events.
+ * Appends log events. An Appender can contain a {@link org.apache.logging.log4j.core.Layout}
if applicable as well
+ * as an {@link org.apache.logging.log4j.core.ErrorHandler}. Typical Appender implementations
coordinate with an
+ * implementation of {@link org.apache.logging.log4j.core.appender.AbstractManager} to handle
external resources
+ * such as streams, connections, and other shared state. As Appenders are plugins, concrete
implementations need to
+ * be annotated with {@link org.apache.logging.log4j.core.config.plugins.Plugin} and need
to provide a static
+ * factory method annotated with {@link org.apache.logging.log4j.core.config.plugins.PluginFactory}.
+ *
+ * <p>Most core plugins are written using a related Manager class that handle the actual
task of serializing a
+ * {@link org.apache.logging.log4j.core.LogEvent} to some output location. For instance,
many Appenders can take
+ * advantage of the {@link org.apache.logging.log4j.core.appender.OutputStreamManager} class.</p>
+ *
+ * <p>It is recommended that Appenders don't do any heavy lifting since there can be
many instances of the class
+ * being used at any given time. When resources require locking (e.g., through {@link java.nio.channels.FileLock}),
+ * it is important to isolate synchronized code to prevent concurrency issues.</p>
  */
 public interface Appender extends LifeCycle {
 
     /**
-     * Log in <code>Appender</code> specific way. When appropriate,
-     * Loggers will call the <code>doAppend</code> method of appender
-     * implementations in order to log.
+     * Logs a LogEvent using whatever logic this Appender wishes to use. It is typically
recommended to use a
+     * bridge pattern not only for the benefits from decoupling an Appender from its implementation,
but it is also
+     * handy for sharing resources which may require some form of locking.
      *
      * @param event The LogEvent.
      */
@@ -34,24 +47,24 @@ public interface Appender extends LifeCy
 
 
     /**
-     * Get the name of this appender.
+     * Get the name of this Appender.
      *
      * @return name, may be null.
      */
     String getName();
 
     /**
-     * Returns this appender's layout.
+     * Returns the Layout used by this Appender if applicable.
      *
-     * @return the Layout for the Appender or null if none is configured.
+     * @return the Layout for this Appender or {@code null} if none is configured.
      */
     Layout<? extends Serializable> getLayout();
 
     /**
-     * Some appenders need to propagate exceptions back to the application. When {@code ignoreExceptions}
is
+     * Some Appenders need to propagate exceptions back to the application. When {@code ignoreExceptions}
is
      * {@code false} the AppenderControl will allow the exception to percolate.
      *
-     * @return {@code true} if exceptions will be logged but now thrown, {@code false} otherwise.
+     * @return {@code true} if exceptions will be logged but not thrown, {@code false} otherwise.
      */
     boolean ignoreExceptions();
 



Mime
View raw message