[logging-log4j2] 02/03: Improve docs

[ma...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

mattsicker pushed a commit to branch mean-bean-machine
in repository https://gitbox.apache.org/repos/asf/logging-log4j2.git

commit 8000a004787b28f2c86fa7b3e1ad7479a836076b
Author: Matt Sicker <bo...@gmail.com>
AuthorDate: Sat Jul 10 18:59:19 2021 -0500

    Improve docs
---
 .../apache/logging/log4j/core/config/di/Bean.java  | 68 +++++++++++++++-------
 1 file changed, 48 insertions(+), 20 deletions(-)

diff --git a/log4j-core/src/main/java/org/apache/logging/log4j/core/config/di/Bean.java b/log4j-core/src/main/java/org/apache/logging/log4j/core/config/di/Bean.java
index 4b718ca..37c8795 100644
--- a/log4j-core/src/main/java/org/apache/logging/log4j/core/config/di/Bean.java
+++ b/log4j-core/src/main/java/org/apache/logging/log4j/core/config/di/Bean.java
@@ -24,31 +24,29 @@ import java.lang.annotation.Annotation;
 import java.lang.reflect.Type;
 import java.util.Collection;
 
+/**
+ * Provides lifecycle and dependency injection functionality to managed classes. A bean represents an injectable class
+ * via {@link org.apache.logging.log4j.plugins.di.Inject} or a producer field or method via
+ * {@link org.apache.logging.log4j.plugins.di.Produces} along with their annotation aliases. A bean has a
+ * {@linkplain #getName() name} which can be the empty string to indicate a default bean. Beans provide a
+ * {@linkplain #getTypes() type closure} of matching generic types to allow for injecting more complex types. The
+ * {@linkplain #getScopeType() scope} of a bean controls the lifecycle of instances
+ * {@linkplain #create(InitializationContext) created} and {@linkplain #destroy(Object, InitializationContext) destroyed}
+ * by this bean. Dependencies are injected based on metadata exposed through
+ * {@linkplain #getInjectionPoints() injection points}.
+ *
+ * @param <T> type of instance being managed by this bean
+ */
 public interface Bean<T> {
+
     /**
-     * Creates a new instance of this bean. The given {@link InitializationContext} should be used by implementations
-     * to track dependent objects.
-     *
-     * @param context the context in which the instance is being managed
-     * @return a managed, initialized instance
+     * Returns the name of this bean or an empty string to indicate a default bean.
      */
-    T create(final InitializationContext<T> context);
+    String getName();
 
     /**
-     * Destroys a managed instance in the given context. Implementations should call {@link InitializationContext#close()} to
-     * allow dependent objects to be destroyed.
-     *
-     * @param instance the managed instance to destroy
-     * @param context  the context in which the instance is being managed
+     * Returns the type closure of this bean.
      */
-    void destroy(final T instance, final InitializationContext<T> context);
-
-    Collection<InjectionPoint> getInjectionPoints();
-
-    // for a managed bean: that class
-    // for a producer field or producer method: the declaring class
-    Class<?> getDeclaringClass();
-
     Collection<Type> getTypes();
 
     default boolean hasMatchingType(final Type requiredType) {
@@ -60,11 +58,41 @@ public interface Bean<T> {
         return false;
     }
 
-    String getName();
+    /**
+     * Returns the declaring class that creates this bean. For injectable classes, this returns that class. For producing
+     * methods and fields, this returns their declaring class.
+     */
+    Class<?> getDeclaringClass();
 
+    /**
+     * Returns the scope type of this bean.
+     */
     Class<? extends Annotation> getScopeType();
 
     default boolean isDependentScoped() {
         return getScopeType() == DependentScoped.class;
     }
+
+    /**
+     * Creates a new instance of this bean. The given {@link InitializationContext} should be used by implementations
+     * to track dependent objects.
+     *
+     * @param context the context in which the instance is being managed
+     * @return a managed, initialized instance
+     */
+    T create(final InitializationContext<T> context);
+
+    /**
+     * Destroys a managed instance in the given context. Implementations should call {@link InitializationContext#close()} to
+     * allow dependent objects to be destroyed.
+     *
+     * @param instance the managed instance to destroy
+     * @param context  the context in which the instance is being managed
+     */
+    void destroy(final T instance, final InitializationContext<T> context);
+
+    /**
+     * Returns the collection of injection points to inject dependencies when constructing instances of this bean.
+     */
+    Collection<InjectionPoint> getInjectionPoints();
 }