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 2022/06/07 22:21:36 UTC
[logging-log4j2] branch master updated: Add more docs
This is an automated email from the ASF dual-hosted git repository.
mattsicker pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/logging-log4j2.git
The following commit(s) were added to refs/heads/master by this push:
new 619e3cf26f Add more docs
619e3cf26f is described below
commit 619e3cf26f4b5fa42849d89e8948db2d468d7536
Author: Matt Sicker <ma...@apache.org>
AuthorDate: Tue Jun 7 17:19:20 2022 -0500
Add more docs
Signed-off-by: Matt Sicker <ma...@apache.org>
---
log4j-api/src/main/java/module-info.java | 12 ++++++++++++
log4j-plugins/src/main/java/module-info.java | 9 +++++++++
.../java/org/apache/logging/log4j/plugins/Inject.java | 14 +++++++-------
.../main/java/org/apache/logging/log4j/plugins/Node.java | 15 ++++++++++++++-
.../java/org/apache/logging/log4j/plugins/Plugin.java | 13 ++++++++++++-
.../org/apache/logging/log4j/plugins/PluginFactory.java | 2 +-
.../org/apache/logging/log4j/plugins/package-info.java | 1 +
7 files changed, 56 insertions(+), 10 deletions(-)
diff --git a/log4j-api/src/main/java/module-info.java b/log4j-api/src/main/java/module-info.java
index d2c9490465..75a4c92ddc 100644
--- a/log4j-api/src/main/java/module-info.java
+++ b/log4j-api/src/main/java/module-info.java
@@ -14,6 +14,18 @@
* See the license for the specific language governing permissions and
* limitations under the license.
*/
+
+/**
+ * <p>Log4j public API for libraries and applications. This module is provided as a portable
+ * {@linkplain org.apache.logging.log4j.Logger logging API} which supports independent
+ * {@linkplain org.apache.logging.log4j.spi.Provider logging provider} backends for configuring
+ * the underlying logging system. The {@link org.apache.logging.log4j} package contains the main APIs for loggers,
+ * markers, logging levels, thread context maps (aka MDC), and thread context stacks (aka NDC).</p>
+ *
+ * <p>Logging provider SPIs are located in {@link org.apache.logging.log4j.spi}. A reference implementation
+ * is given in {@link org.apache.logging.log4j.simple} which is used internally by the
+ * {@linkplain org.apache.logging.log4j.status.StatusLogger status logger API}.</p>
+ */
module org.apache.logging.log4j {
exports org.apache.logging.log4j;
exports org.apache.logging.log4j.message;
diff --git a/log4j-plugins/src/main/java/module-info.java b/log4j-plugins/src/main/java/module-info.java
index d6691ffe4b..b884b96944 100644
--- a/log4j-plugins/src/main/java/module-info.java
+++ b/log4j-plugins/src/main/java/module-info.java
@@ -14,6 +14,15 @@
* See the license for the specific language governing permissions and
* limitations under the license.
*/
+
+/**
+ * Log4j plugin annotations and dependency injection system.
+ *
+ * @see org.apache.logging.log4j.plugins.Inject
+ * @see org.apache.logging.log4j.plugins.Plugin
+ * @see org.apache.logging.log4j.plugins.PluginFactory
+ * @see org.apache.logging.log4j.plugins.Namespace
+ */
module org.apache.logging.log4j.plugins {
exports org.apache.logging.log4j.plugins;
exports org.apache.logging.log4j.plugins.condition;
diff --git a/log4j-plugins/src/main/java/org/apache/logging/log4j/plugins/Inject.java b/log4j-plugins/src/main/java/org/apache/logging/log4j/plugins/Inject.java
index f9d92ef935..5eabad73b4 100644
--- a/log4j-plugins/src/main/java/org/apache/logging/log4j/plugins/Inject.java
+++ b/log4j-plugins/src/main/java/org/apache/logging/log4j/plugins/Inject.java
@@ -24,22 +24,22 @@ import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
/**
- * Marks a constructor, field, or method for dependency injection. Constructors are injected first, followed by fields,
+ * <p>Marks a constructor, field, or method for dependency injection. Constructors are injected first, followed by fields,
* then methods. Superclasses are injected before subclasses. Note that zero-arg methods with this annotation are
- * considered initialization methods which are also invoked during dependency injection.
+ * considered initialization methods which are also invoked during dependency injection.</p>
*
* <h2>Constructors</h2>
- * A class can have at most one constructor annotated with {@code @Inject}. This constructor can have zero or more
+ * <p>A class can have at most one constructor annotated with {@code @Inject}. This constructor can have zero or more
* dependencies as arguments. If a class has no constructors annotated with {@code @Inject}, then its default
- * zero args constructor is used if available.
+ * zero args constructor is used if available.</p>
*
* <h2>Fields</h2>
- * Only non-final, non-static fields may be annotated with {@code @Inject}.
+ * <p>Only non-final, non-static fields may be annotated with {@code @Inject}.</p>
*
* <h2>Methods</h2>
- * Non-abstract, non-static methods may be annotated with {@code @Inject}. These methods must not
+ * <p>Non-abstract, non-static methods may be annotated with {@code @Inject}. These methods must not
* declare any type parameters of their own, take zero or more dependencies as arguments, and may return a value which
- * is ignored (e.g., for builder method chaining).
+ * is ignored (e.g., for builder method chaining).</p>
*
* @see Named
* @see Factory
diff --git a/log4j-plugins/src/main/java/org/apache/logging/log4j/plugins/Node.java b/log4j-plugins/src/main/java/org/apache/logging/log4j/plugins/Node.java
index 526dda0710..1596157801 100644
--- a/log4j-plugins/src/main/java/org/apache/logging/log4j/plugins/Node.java
+++ b/log4j-plugins/src/main/java/org/apache/logging/log4j/plugins/Node.java
@@ -26,7 +26,12 @@ import java.util.Map;
import java.util.Optional;
/**
- * A Configuration node.
+ * Configurations are represented as a tree of Node instances. Each Node may have
+ * {@linkplain #getAttributes() attributes}, {@linkplain #getChildren() children nodes},
+ * an {@linkplain #getValue() optional value} (which is a special kind of attribute for certain configuration file
+ * formats which support the concept), and a {@linkplain #getName() name} which corresponds to a
+ * {@link Plugin} class in the {@linkplain Configurable Core namespace}. Configuration factories parse a configuration
+ * resource into a tree of Nodes with a single root Node.
*/
public class Node {
@@ -62,12 +67,20 @@ public class Node {
this.type = type;
}
+ /**
+ * Constructs a root node. Root nodes have no defined type, name, or parent node.
+ */
public Node() {
this.parent = null;
this.name = null;
this.type = null;
}
+ /**
+ * Constructs a fresh copy of the provided Node.
+ *
+ * @param node original node to copy
+ */
public Node(final Node node) {
this.parent = node.parent;
this.name = node.name;
diff --git a/log4j-plugins/src/main/java/org/apache/logging/log4j/plugins/Plugin.java b/log4j-plugins/src/main/java/org/apache/logging/log4j/plugins/Plugin.java
index bdc905b6f8..b8ddf0c7fb 100644
--- a/log4j-plugins/src/main/java/org/apache/logging/log4j/plugins/Plugin.java
+++ b/log4j-plugins/src/main/java/org/apache/logging/log4j/plugins/Plugin.java
@@ -27,7 +27,18 @@ import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
/**
- * Annotation that identifies a Class as a Plugin.
+ * <p>Annotation that identifies a Class as a Plugin. Plugins are indexed classes with a name that can typically
+ * be used to refer to that plugin class in a configuration. Plugin names must be unique within a plugin
+ * {@link Namespace}. A plugin is identified by its namespace and name, though the type of the plugin may be
+ * used for dependency injection purposes.</p>
+ *
+ * <p>Plugins are indexed by the plugin annotation processor which generates
+ * {@link org.apache.logging.log4j.plugins.processor.PluginService} service provider classes containing essential
+ * plugin metadata. All plugin namespaces support dependency injection, though some namespaces use alternative
+ * factory strategies specific to their plugin types; these plugins will only have their members injected after
+ * that factory returns a new instance.</p>
+ *
+ * @see Inject
*/
@Documented
@Retention(RetentionPolicy.RUNTIME)
diff --git a/log4j-plugins/src/main/java/org/apache/logging/log4j/plugins/PluginFactory.java b/log4j-plugins/src/main/java/org/apache/logging/log4j/plugins/PluginFactory.java
index 64f2553077..cdca5f32c8 100644
--- a/log4j-plugins/src/main/java/org/apache/logging/log4j/plugins/PluginFactory.java
+++ b/log4j-plugins/src/main/java/org/apache/logging/log4j/plugins/PluginFactory.java
@@ -25,7 +25,7 @@ import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
/**
- * Identifies a static method as a factory to create a plugin or a
+ * Identifies a static method as a factory to create a {@link Configurable} plugin or a
* {@linkplain org.apache.logging.log4j.plugins.util.Builder builder class} for constructing a plugin.
* Factory methods should annotate their parameters with {@link PluginAttribute}, {@link PluginElement},
* {@link PluginValue}, or other plugin annotations annotated with {@link NodeVisitor.Kind}.
diff --git a/log4j-plugins/src/main/java/org/apache/logging/log4j/plugins/package-info.java b/log4j-plugins/src/main/java/org/apache/logging/log4j/plugins/package-info.java
index e49bd2db95..c55b37a650 100644
--- a/log4j-plugins/src/main/java/org/apache/logging/log4j/plugins/package-info.java
+++ b/log4j-plugins/src/main/java/org/apache/logging/log4j/plugins/package-info.java
@@ -21,6 +21,7 @@
* such as singleton and dependent instances.
*
* @see org.apache.logging.log4j.plugins.Plugin
+ * @see org.apache.logging.log4j.plugins.Namespace
* @see org.apache.logging.log4j.plugins.PluginFactory
* @see org.apache.logging.log4j.plugins.Inject
*/