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 <[email protected]> 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(); }
