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 cd461f1596ca3c026f0787fac567f67c4d6873a1 Author: Matt Sicker <[email protected]> AuthorDate: Sat Jun 12 13:51:19 2021 -0500 Add more DI API docs with some renames --- .../core/config/di/api/bean/InjectionTarget.java | 35 +++++++++++++-- .../log4j/core/config/di/api/bean/Producer.java | 45 ++++++++++++++++--- .../core/config/di/api/bean/ProviderFactory.java | 2 +- .../core/config/di/api/bean/ScopeContext.java | 2 +- .../core/config/di/api/model/ElementManager.java | 10 ++--- .../core/config/di/api/model/InjectionPoint.java | 4 +- .../core/config/di/api/model/MetaElement.java | 2 +- .../log4j/core/config/di/api/model/Qualifiers.java | 4 +- .../log4j/core/config/di/api/model/Variable.java | 2 +- .../config/di/impl/bean/DefaultBeanManager.java | 10 ++--- .../di/impl/bean/DefaultInjectionTarget.java | 6 +-- .../impl/bean/DefaultInjectionTargetFactory.java | 6 +-- .../core/config/di/impl/bean/DefaultInjector.java | 2 +- .../config/di/impl/bean/DependentScopeContext.java | 2 +- .../core/config/di/impl/bean/OptionalBean.java | 2 +- .../core/config/di/impl/bean/ProviderBean.java | 2 +- .../di/impl/model/DefaultElementManager.java | 14 +++--- .../di/impl/model/DefaultMetaAnnotation.java | 4 +- .../di/impl/bean/DefaultBeanManagerTest.java | 16 +++---- .../apache/logging/log4j/plugins/api/Produces.java | 32 ------------- .../log4j/plugins/{api => di}/AnnotationAlias.java | 2 +- .../logging/log4j/plugins/{api => di}/Default.java | 6 ++- .../log4j/plugins/{api => di}/DependentScoped.java | 2 +- .../log4j/plugins/{api => di}/Disposes.java | 10 ++++- .../logging/log4j/plugins/{api => di}/Ignore.java | 2 +- .../logging/log4j/plugins/{api => di}/Inject.java | 2 +- .../logging/log4j/plugins/{api => di}/Named.java | 2 +- .../log4j/plugins/{api => di}/PostConstruct.java | 2 +- .../log4j/plugins/{api => di}/PreDestroy.java | 2 +- .../apache/logging/log4j/plugins/di/Produces.java | 52 ++++++++++++++++++++++ .../log4j/plugins/{api => di}/Provider.java | 2 +- .../log4j/plugins/{api => di}/QualifierType.java | 2 +- .../log4j/plugins/{api => di}/ScopeType.java | 12 ++++- .../log4j/plugins/{api => di}/SingletonScoped.java | 2 +- .../log4j/plugins/{api => di}/package-info.java | 2 +- .../plugins/name/NamedQualifierNameProvider.java | 2 +- log4j-plugins/src/main/java9/module-info.java | 1 + 37 files changed, 202 insertions(+), 105 deletions(-) diff --git a/log4j-core/src/main/java/org/apache/logging/log4j/core/config/di/api/bean/InjectionTarget.java b/log4j-core/src/main/java/org/apache/logging/log4j/core/config/di/api/bean/InjectionTarget.java index 7faae9a..837e99e 100644 --- a/log4j-core/src/main/java/org/apache/logging/log4j/core/config/di/api/bean/InjectionTarget.java +++ b/log4j-core/src/main/java/org/apache/logging/log4j/core/config/di/api/bean/InjectionTarget.java @@ -17,16 +17,45 @@ package org.apache.logging.log4j.core.config.di.api.bean; +import org.apache.logging.log4j.plugins.di.Inject; +import org.apache.logging.log4j.plugins.di.PostConstruct; +import org.apache.logging.log4j.plugins.di.PreDestroy; + +/** + * Provides lifecycle and dependency injection operations for instances of a specified type. + * + * @param <T> type of instance managed by this injection target + */ public interface InjectionTarget<T> extends Producer<T> { - // sets values of injected fields and calls initializer methods + + /** + * Performs dependency injection on the provided instance in the given initialization context. This sets the values + * of injected fields and calls initializer methods (i.e., fields and methods annotated with {@link Inject}). + * + * @param instance instance upon which to perform dependency injection + * @param context initialization context to perform injection in + */ void inject(final T instance, final InitializationContext<T> context); - // calls @PostConstruct from top to bottom + /** + * Invokes the {@link PostConstruct} methods of the provided instance. + * Post construct methods are invoked starting with the highest level method and continue down the type hierarchy. + * + * @param instance instance upon which to invoke post construct methods + */ void postConstruct(final T instance); - // calls @PreDestroy from bottom to top + /** + * Invokes the {@link PreDestroy} methods of the provided instance. + * Pre destroy methods are invoked starting with the lowest level method and continue up the type hierarchy. + * + * @param instance instance upone which to invoke pre destroy methods + */ void preDestroy(final T instance); + /** + * Does nothing. This method only applies to producers. + */ @Override default void dispose(T instance) { // @Disposes only applies to @Produces methods and fields diff --git a/log4j-core/src/main/java/org/apache/logging/log4j/core/config/di/api/bean/Producer.java b/log4j-core/src/main/java/org/apache/logging/log4j/core/config/di/api/bean/Producer.java index cc0ca49..3665e64 100644 --- a/log4j-core/src/main/java/org/apache/logging/log4j/core/config/di/api/bean/Producer.java +++ b/log4j-core/src/main/java/org/apache/logging/log4j/core/config/di/api/bean/Producer.java @@ -18,20 +18,51 @@ package org.apache.logging.log4j.core.config.di.api.bean; import org.apache.logging.log4j.core.config.di.api.model.InjectionPoint; +import org.apache.logging.log4j.plugins.di.Disposes; +import org.apache.logging.log4j.plugins.di.Inject; +import org.apache.logging.log4j.plugins.di.Produces; import java.util.Collection; +/** + * Provides lifecycle operations for producing instances of a specified type. Producers represent three different ways + * to manage instances: injectable classes, producer methods, and producer fields. + * + * @param <T> type of instance managed by this producer + * @see Inject + * @see Produces + */ public interface Producer<T> { - // for a class: calls @Inject constructor or default constructor - // for a producer method, this is invoked on that instance - // for a producer field, the value is gotten from that instance + + /** + * Creates an instance in the given initialization context. When this represents a class, this calls the + * constructor annotated with {@link Inject} or the default constructor. + * When this represents a producer method, this invokes the producer method. When this represents a producer + * field, this obtains the value of the field. + * + * @param context initialization context to use to create the instance + * @return produced instance + * @see Produces + */ T produce(InitializationContext<T> context); - // for a class, no-op (preDestroy is relevant there instead) - // for a producer method or producer field, calls the disposer method + /** + * Destroys the provided instance. When this represents a class, this does nothing. When this represents a + * producer method or field, then this invokes the corresponding disposer method. + * + * @param instance instance to dispose + * @see Disposes + */ void dispose(T instance); - // for a class: injected fields, @Inject constructor parameters, and initializer method params - // for a producer method: method params + /** + * Returns all the injection points of this producer. For a class, this returns all injected fields, bean + * constructor parameters, and initialization method parameters. For a producer method, this returns the + * parameters to that method. + * + * @return all injection points for this producer + * @see Inject + * @see Produces + */ Collection<InjectionPoint> getInjectionPoints(); } diff --git a/log4j-core/src/main/java/org/apache/logging/log4j/core/config/di/api/bean/ProviderFactory.java b/log4j-core/src/main/java/org/apache/logging/log4j/core/config/di/api/bean/ProviderFactory.java index 11bc2f4..a557ed1 100644 --- a/log4j-core/src/main/java/org/apache/logging/log4j/core/config/di/api/bean/ProviderFactory.java +++ b/log4j-core/src/main/java/org/apache/logging/log4j/core/config/di/api/bean/ProviderFactory.java @@ -17,7 +17,7 @@ package org.apache.logging.log4j.core.config.di.api.bean; -import org.apache.logging.log4j.plugins.api.Provider; +import org.apache.logging.log4j.plugins.di.Provider; public interface ProviderFactory<T> { Provider<T> getProvider(final InitializationContext<?> context); diff --git a/log4j-core/src/main/java/org/apache/logging/log4j/core/config/di/api/bean/ScopeContext.java b/log4j-core/src/main/java/org/apache/logging/log4j/core/config/di/api/bean/ScopeContext.java index 4e12f4f..2670d04 100644 --- a/log4j-core/src/main/java/org/apache/logging/log4j/core/config/di/api/bean/ScopeContext.java +++ b/log4j-core/src/main/java/org/apache/logging/log4j/core/config/di/api/bean/ScopeContext.java @@ -17,7 +17,7 @@ package org.apache.logging.log4j.core.config.di.api.bean; -import org.apache.logging.log4j.plugins.api.ScopeType; +import org.apache.logging.log4j.plugins.di.ScopeType; import java.lang.annotation.Annotation; import java.util.Optional; diff --git a/log4j-core/src/main/java/org/apache/logging/log4j/core/config/di/api/model/ElementManager.java b/log4j-core/src/main/java/org/apache/logging/log4j/core/config/di/api/model/ElementManager.java index 5744396..bab1036 100644 --- a/log4j-core/src/main/java/org/apache/logging/log4j/core/config/di/api/model/ElementManager.java +++ b/log4j-core/src/main/java/org/apache/logging/log4j/core/config/di/api/model/ElementManager.java @@ -17,11 +17,11 @@ package org.apache.logging.log4j.core.config.di.api.model; -import org.apache.logging.log4j.plugins.api.Default; -import org.apache.logging.log4j.plugins.api.Inject; -import org.apache.logging.log4j.plugins.api.Named; -import org.apache.logging.log4j.plugins.api.Produces; -import org.apache.logging.log4j.plugins.api.QualifierType; +import org.apache.logging.log4j.plugins.di.Default; +import org.apache.logging.log4j.plugins.di.Inject; +import org.apache.logging.log4j.plugins.di.Named; +import org.apache.logging.log4j.plugins.di.Produces; +import org.apache.logging.log4j.plugins.di.QualifierType; import org.apache.logging.log4j.core.config.di.api.bean.Bean; import java.lang.annotation.Annotation; diff --git a/log4j-core/src/main/java/org/apache/logging/log4j/core/config/di/api/model/InjectionPoint.java b/log4j-core/src/main/java/org/apache/logging/log4j/core/config/di/api/model/InjectionPoint.java index fa2d2f7..7fd6856 100644 --- a/log4j-core/src/main/java/org/apache/logging/log4j/core/config/di/api/model/InjectionPoint.java +++ b/log4j-core/src/main/java/org/apache/logging/log4j/core/config/di/api/model/InjectionPoint.java @@ -33,8 +33,8 @@ public interface InjectionPoint { Type getType(); /** - * Gets the qualifiers of this point. If no qualifiers other than {@link org.apache.logging.log4j.plugins.api.Named} - * are present, then these qualifiers will also include {@link org.apache.logging.log4j.plugins.api.Default}. + * Gets the qualifiers of this point. If no qualifiers other than {@link org.apache.logging.log4j.plugins.di.Named} + * are present, then these qualifiers will also include {@link org.apache.logging.log4j.plugins.di.Default}. */ Qualifiers getQualifiers(); diff --git a/log4j-core/src/main/java/org/apache/logging/log4j/core/config/di/api/model/MetaElement.java b/log4j-core/src/main/java/org/apache/logging/log4j/core/config/di/api/model/MetaElement.java index 6d2e726..7962c6e 100644 --- a/log4j-core/src/main/java/org/apache/logging/log4j/core/config/di/api/model/MetaElement.java +++ b/log4j-core/src/main/java/org/apache/logging/log4j/core/config/di/api/model/MetaElement.java @@ -17,7 +17,7 @@ package org.apache.logging.log4j.core.config.di.api.model; -import org.apache.logging.log4j.plugins.api.AnnotationAlias; +import org.apache.logging.log4j.plugins.di.AnnotationAlias; import org.apache.logging.log4j.plugins.util.TypeUtil; import java.lang.annotation.Annotation; diff --git a/log4j-core/src/main/java/org/apache/logging/log4j/core/config/di/api/model/Qualifiers.java b/log4j-core/src/main/java/org/apache/logging/log4j/core/config/di/api/model/Qualifiers.java index 8010540..f80ce68 100644 --- a/log4j-core/src/main/java/org/apache/logging/log4j/core/config/di/api/model/Qualifiers.java +++ b/log4j-core/src/main/java/org/apache/logging/log4j/core/config/di/api/model/Qualifiers.java @@ -17,7 +17,7 @@ package org.apache.logging.log4j.core.config.di.api.model; -import org.apache.logging.log4j.plugins.api.Default; +import org.apache.logging.log4j.plugins.di.Default; import org.apache.logging.log4j.util.StringBuilders; import java.lang.annotation.Annotation; @@ -28,7 +28,7 @@ import java.util.Set; import java.util.stream.Collectors; /** - * Represents a normalized set of {@linkplain org.apache.logging.log4j.plugins.api.QualifierType qualifier annotations}. + * Represents a normalized set of {@linkplain org.apache.logging.log4j.plugins.di.QualifierType qualifier annotations}. */ public final class Qualifiers { diff --git a/log4j-core/src/main/java/org/apache/logging/log4j/core/config/di/api/model/Variable.java b/log4j-core/src/main/java/org/apache/logging/log4j/core/config/di/api/model/Variable.java index 40eb33a..0b43c30 100644 --- a/log4j-core/src/main/java/org/apache/logging/log4j/core/config/di/api/model/Variable.java +++ b/log4j-core/src/main/java/org/apache/logging/log4j/core/config/di/api/model/Variable.java @@ -17,7 +17,7 @@ package org.apache.logging.log4j.core.config.di.api.model; -import org.apache.logging.log4j.plugins.api.DependentScoped; +import org.apache.logging.log4j.plugins.di.DependentScoped; import org.apache.logging.log4j.plugins.util.TypeUtil; import java.lang.annotation.Annotation; diff --git a/log4j-core/src/main/java/org/apache/logging/log4j/core/config/di/impl/bean/DefaultBeanManager.java b/log4j-core/src/main/java/org/apache/logging/log4j/core/config/di/impl/bean/DefaultBeanManager.java index d75ea9d..f9e3e43 100644 --- a/log4j-core/src/main/java/org/apache/logging/log4j/core/config/di/impl/bean/DefaultBeanManager.java +++ b/log4j-core/src/main/java/org/apache/logging/log4j/core/config/di/impl/bean/DefaultBeanManager.java @@ -41,11 +41,11 @@ import org.apache.logging.log4j.core.config.di.api.model.MetaParameter; import org.apache.logging.log4j.core.config.di.api.model.Qualifiers; import org.apache.logging.log4j.core.config.di.api.model.Variable; import org.apache.logging.log4j.core.config.di.impl.model.DefaultElementManager; -import org.apache.logging.log4j.plugins.api.DependentScoped; -import org.apache.logging.log4j.plugins.api.Disposes; -import org.apache.logging.log4j.plugins.api.Produces; -import org.apache.logging.log4j.plugins.api.Provider; -import org.apache.logging.log4j.plugins.api.SingletonScoped; +import org.apache.logging.log4j.plugins.di.DependentScoped; +import org.apache.logging.log4j.plugins.di.Disposes; +import org.apache.logging.log4j.plugins.di.Produces; +import org.apache.logging.log4j.plugins.di.Provider; +import org.apache.logging.log4j.plugins.di.SingletonScoped; import org.apache.logging.log4j.plugins.util.LazyValue; import org.apache.logging.log4j.plugins.util.TypeUtil; diff --git a/log4j-core/src/main/java/org/apache/logging/log4j/core/config/di/impl/bean/DefaultInjectionTarget.java b/log4j-core/src/main/java/org/apache/logging/log4j/core/config/di/impl/bean/DefaultInjectionTarget.java index bf1ec0c..38cbea2 100644 --- a/log4j-core/src/main/java/org/apache/logging/log4j/core/config/di/impl/bean/DefaultInjectionTarget.java +++ b/log4j-core/src/main/java/org/apache/logging/log4j/core/config/di/impl/bean/DefaultInjectionTarget.java @@ -17,9 +17,9 @@ package org.apache.logging.log4j.core.config.di.impl.bean; -import org.apache.logging.log4j.plugins.api.Disposes; -import org.apache.logging.log4j.plugins.api.Inject; -import org.apache.logging.log4j.plugins.api.Produces; +import org.apache.logging.log4j.plugins.di.Disposes; +import org.apache.logging.log4j.plugins.di.Inject; +import org.apache.logging.log4j.plugins.di.Produces; import org.apache.logging.log4j.core.config.di.api.bean.InitializationContext; import org.apache.logging.log4j.core.config.di.api.bean.InjectionTarget; import org.apache.logging.log4j.core.config.di.api.bean.Injector; diff --git a/log4j-core/src/main/java/org/apache/logging/log4j/core/config/di/impl/bean/DefaultInjectionTargetFactory.java b/log4j-core/src/main/java/org/apache/logging/log4j/core/config/di/impl/bean/DefaultInjectionTargetFactory.java index 94f379c..a0de95b 100644 --- a/log4j-core/src/main/java/org/apache/logging/log4j/core/config/di/impl/bean/DefaultInjectionTargetFactory.java +++ b/log4j-core/src/main/java/org/apache/logging/log4j/core/config/di/impl/bean/DefaultInjectionTargetFactory.java @@ -17,9 +17,9 @@ package org.apache.logging.log4j.core.config.di.impl.bean; -import org.apache.logging.log4j.plugins.api.Inject; -import org.apache.logging.log4j.plugins.api.PostConstruct; -import org.apache.logging.log4j.plugins.api.PreDestroy; +import org.apache.logging.log4j.plugins.di.Inject; +import org.apache.logging.log4j.plugins.di.PostConstruct; +import org.apache.logging.log4j.plugins.di.PreDestroy; import org.apache.logging.log4j.core.config.di.DefinitionException; import org.apache.logging.log4j.core.config.di.api.bean.Bean; import org.apache.logging.log4j.core.config.di.api.bean.InjectionTarget; diff --git a/log4j-core/src/main/java/org/apache/logging/log4j/core/config/di/impl/bean/DefaultInjector.java b/log4j-core/src/main/java/org/apache/logging/log4j/core/config/di/impl/bean/DefaultInjector.java index e3473a1..fde8c96 100644 --- a/log4j-core/src/main/java/org/apache/logging/log4j/core/config/di/impl/bean/DefaultInjector.java +++ b/log4j-core/src/main/java/org/apache/logging/log4j/core/config/di/impl/bean/DefaultInjector.java @@ -17,7 +17,7 @@ package org.apache.logging.log4j.core.config.di.impl.bean; -import org.apache.logging.log4j.plugins.api.Disposes; +import org.apache.logging.log4j.plugins.di.Disposes; import org.apache.logging.log4j.core.config.di.api.bean.BeanManager; import org.apache.logging.log4j.core.config.di.api.bean.InitializationContext; import org.apache.logging.log4j.core.config.di.api.bean.Injector; diff --git a/log4j-core/src/main/java/org/apache/logging/log4j/core/config/di/impl/bean/DependentScopeContext.java b/log4j-core/src/main/java/org/apache/logging/log4j/core/config/di/impl/bean/DependentScopeContext.java index 4fab1c0..c0394bc 100644 --- a/log4j-core/src/main/java/org/apache/logging/log4j/core/config/di/impl/bean/DependentScopeContext.java +++ b/log4j-core/src/main/java/org/apache/logging/log4j/core/config/di/impl/bean/DependentScopeContext.java @@ -17,7 +17,7 @@ package org.apache.logging.log4j.core.config.di.impl.bean; -import org.apache.logging.log4j.plugins.api.DependentScoped; +import org.apache.logging.log4j.plugins.di.DependentScoped; import org.apache.logging.log4j.core.config.di.api.bean.Bean; import org.apache.logging.log4j.core.config.di.api.bean.InitializationContext; import org.apache.logging.log4j.core.config.di.api.bean.ScopeContext; diff --git a/log4j-core/src/main/java/org/apache/logging/log4j/core/config/di/impl/bean/OptionalBean.java b/log4j-core/src/main/java/org/apache/logging/log4j/core/config/di/impl/bean/OptionalBean.java index ee23a73..aa73480 100644 --- a/log4j-core/src/main/java/org/apache/logging/log4j/core/config/di/impl/bean/OptionalBean.java +++ b/log4j-core/src/main/java/org/apache/logging/log4j/core/config/di/impl/bean/OptionalBean.java @@ -17,7 +17,7 @@ package org.apache.logging.log4j.core.config.di.impl.bean; -import org.apache.logging.log4j.plugins.api.DependentScoped; +import org.apache.logging.log4j.plugins.di.DependentScoped; import org.apache.logging.log4j.core.config.di.api.bean.Bean; import org.apache.logging.log4j.core.config.di.api.bean.InitializationContext; import org.apache.logging.log4j.core.config.di.api.model.InjectionPoint; diff --git a/log4j-core/src/main/java/org/apache/logging/log4j/core/config/di/impl/bean/ProviderBean.java b/log4j-core/src/main/java/org/apache/logging/log4j/core/config/di/impl/bean/ProviderBean.java index 77bd7b0..80c519b 100644 --- a/log4j-core/src/main/java/org/apache/logging/log4j/core/config/di/impl/bean/ProviderBean.java +++ b/log4j-core/src/main/java/org/apache/logging/log4j/core/config/di/impl/bean/ProviderBean.java @@ -17,7 +17,7 @@ package org.apache.logging.log4j.core.config.di.impl.bean; -import org.apache.logging.log4j.plugins.api.Provider; +import org.apache.logging.log4j.plugins.di.Provider; import org.apache.logging.log4j.core.config.di.api.bean.InitializationContext; import org.apache.logging.log4j.core.config.di.api.bean.ProviderFactory; import org.apache.logging.log4j.core.config.di.api.model.Variable; diff --git a/log4j-core/src/main/java/org/apache/logging/log4j/core/config/di/impl/model/DefaultElementManager.java b/log4j-core/src/main/java/org/apache/logging/log4j/core/config/di/impl/model/DefaultElementManager.java index 705c3cc..ed8da5c 100644 --- a/log4j-core/src/main/java/org/apache/logging/log4j/core/config/di/impl/model/DefaultElementManager.java +++ b/log4j-core/src/main/java/org/apache/logging/log4j/core/config/di/impl/model/DefaultElementManager.java @@ -17,13 +17,13 @@ package org.apache.logging.log4j.core.config.di.impl.model; -import org.apache.logging.log4j.plugins.api.AnnotationAlias; -import org.apache.logging.log4j.plugins.api.Default; -import org.apache.logging.log4j.plugins.api.DependentScoped; -import org.apache.logging.log4j.plugins.api.Ignore; -import org.apache.logging.log4j.plugins.api.Named; -import org.apache.logging.log4j.plugins.api.QualifierType; -import org.apache.logging.log4j.plugins.api.ScopeType; +import org.apache.logging.log4j.plugins.di.AnnotationAlias; +import org.apache.logging.log4j.plugins.di.Default; +import org.apache.logging.log4j.plugins.di.DependentScoped; +import org.apache.logging.log4j.plugins.di.Ignore; +import org.apache.logging.log4j.plugins.di.Named; +import org.apache.logging.log4j.plugins.di.QualifierType; +import org.apache.logging.log4j.plugins.di.ScopeType; import org.apache.logging.log4j.plugins.internal.util.BeanUtils; import org.apache.logging.log4j.core.config.di.api.bean.Bean; import org.apache.logging.log4j.core.config.di.api.model.ElementManager; diff --git a/log4j-core/src/main/java/org/apache/logging/log4j/core/config/di/impl/model/DefaultMetaAnnotation.java b/log4j-core/src/main/java/org/apache/logging/log4j/core/config/di/impl/model/DefaultMetaAnnotation.java index aa01a25..62d8636 100644 --- a/log4j-core/src/main/java/org/apache/logging/log4j/core/config/di/impl/model/DefaultMetaAnnotation.java +++ b/log4j-core/src/main/java/org/apache/logging/log4j/core/config/di/impl/model/DefaultMetaAnnotation.java @@ -17,8 +17,8 @@ package org.apache.logging.log4j.core.config.di.impl.model; -import org.apache.logging.log4j.plugins.api.AnnotationAlias; -import org.apache.logging.log4j.plugins.api.Named; +import org.apache.logging.log4j.plugins.di.AnnotationAlias; +import org.apache.logging.log4j.plugins.di.Named; import org.apache.logging.log4j.core.config.di.InitializationException; import org.apache.logging.log4j.core.config.di.api.model.MetaAnnotation; import org.apache.logging.log4j.core.config.di.api.model.MetaAnnotationElement; diff --git a/log4j-core/src/test/java/org/apache/logging/log4j/core/config/di/impl/bean/DefaultBeanManagerTest.java b/log4j-core/src/test/java/org/apache/logging/log4j/core/config/di/impl/bean/DefaultBeanManagerTest.java index 2cee816..32a328f 100644 --- a/log4j-core/src/test/java/org/apache/logging/log4j/core/config/di/impl/bean/DefaultBeanManagerTest.java +++ b/log4j-core/src/test/java/org/apache/logging/log4j/core/config/di/impl/bean/DefaultBeanManagerTest.java @@ -19,14 +19,14 @@ package org.apache.logging.log4j.core.config.di.impl.bean; import org.apache.logging.log4j.core.test.junit.BeanJUnit4Runner; import org.apache.logging.log4j.core.test.junit.WithBeans; -import org.apache.logging.log4j.plugins.api.Default; -import org.apache.logging.log4j.plugins.api.Inject; -import org.apache.logging.log4j.plugins.api.Named; -import org.apache.logging.log4j.plugins.api.PostConstruct; -import org.apache.logging.log4j.plugins.api.Produces; -import org.apache.logging.log4j.plugins.api.Provider; -import org.apache.logging.log4j.plugins.api.QualifierType; -import org.apache.logging.log4j.plugins.api.SingletonScoped; +import org.apache.logging.log4j.plugins.di.Default; +import org.apache.logging.log4j.plugins.di.Inject; +import org.apache.logging.log4j.plugins.di.Named; +import org.apache.logging.log4j.plugins.di.PostConstruct; +import org.apache.logging.log4j.plugins.di.Produces; +import org.apache.logging.log4j.plugins.di.Provider; +import org.apache.logging.log4j.plugins.di.QualifierType; +import org.apache.logging.log4j.plugins.di.SingletonScoped; import org.junit.Test; import org.junit.runner.RunWith; diff --git a/log4j-plugins/src/main/java/org/apache/logging/log4j/plugins/api/Produces.java b/log4j-plugins/src/main/java/org/apache/logging/log4j/plugins/api/Produces.java deleted file mode 100644 index 5c46c56..0000000 --- a/log4j-plugins/src/main/java/org/apache/logging/log4j/plugins/api/Produces.java +++ /dev/null @@ -1,32 +0,0 @@ -/* - * Licensed to the Apache Software Foundation (ASF) under one or more - * contributor license agreements. See the NOTICE file distributed with - * this work for additional information regarding copyright ownership. - * The ASF licenses this file to You under the Apache license, Version 2.0 - * (the "License"); you may not use this file except in compliance with - * the License. You may obtain a copy of the License at - * - * http://www.apache.org/licenses/LICENSE-2.0 - * - * Unless required by applicable law or agreed to in writing, software - * distributed under the License is distributed on an "AS IS" BASIS, - * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - * See the license for the specific language governing permissions and - * limitations under the license. - */ - -package org.apache.logging.log4j.plugins.api; - -import java.lang.annotation.Documented; -import java.lang.annotation.ElementType; -import java.lang.annotation.Retention; -import java.lang.annotation.RetentionPolicy; -import java.lang.annotation.Target; - -// https://docs.jboss.org/cdi/api/2.0/javax/enterprise/inject/Produces.html -// https://docs.spring.io/spring-framework/docs/current/javadoc-api/org/springframework/context/annotation/Bean.html -@Target({ElementType.METHOD, ElementType.FIELD}) -@Retention(RetentionPolicy.RUNTIME) -@Documented -public @interface Produces { -} diff --git a/log4j-plugins/src/main/java/org/apache/logging/log4j/plugins/api/AnnotationAlias.java b/log4j-plugins/src/main/java/org/apache/logging/log4j/plugins/di/AnnotationAlias.java similarity index 97% rename from log4j-plugins/src/main/java/org/apache/logging/log4j/plugins/api/AnnotationAlias.java rename to log4j-plugins/src/main/java/org/apache/logging/log4j/plugins/di/AnnotationAlias.java index d97830d..f522b3a 100644 --- a/log4j-plugins/src/main/java/org/apache/logging/log4j/plugins/api/AnnotationAlias.java +++ b/log4j-plugins/src/main/java/org/apache/logging/log4j/plugins/di/AnnotationAlias.java @@ -15,7 +15,7 @@ * limitations under the license. */ -package org.apache.logging.log4j.plugins.api; +package org.apache.logging.log4j.plugins.di; import java.lang.annotation.Annotation; import java.lang.annotation.Documented; diff --git a/log4j-plugins/src/main/java/org/apache/logging/log4j/plugins/api/Default.java b/log4j-plugins/src/main/java/org/apache/logging/log4j/plugins/di/Default.java similarity index 88% rename from log4j-plugins/src/main/java/org/apache/logging/log4j/plugins/api/Default.java rename to log4j-plugins/src/main/java/org/apache/logging/log4j/plugins/di/Default.java index 6578f65..0087d5f 100644 --- a/log4j-plugins/src/main/java/org/apache/logging/log4j/plugins/api/Default.java +++ b/log4j-plugins/src/main/java/org/apache/logging/log4j/plugins/di/Default.java @@ -15,17 +15,19 @@ * limitations under the license. */ -package org.apache.logging.log4j.plugins.api; +package org.apache.logging.log4j.plugins.di; import java.lang.annotation.Documented; import java.lang.annotation.Inherited; import java.lang.annotation.Retention; import java.lang.annotation.RetentionPolicy; +/** + * Default {@linkplain QualifierType qualifier type} when no other qualifiers are present. + */ @QualifierType @Retention(RetentionPolicy.RUNTIME) @Documented @Inherited -// default qualifier unless qualifier besides @Named is present public @interface Default { } diff --git a/log4j-plugins/src/main/java/org/apache/logging/log4j/plugins/api/DependentScoped.java b/log4j-plugins/src/main/java/org/apache/logging/log4j/plugins/di/DependentScoped.java similarity index 97% rename from log4j-plugins/src/main/java/org/apache/logging/log4j/plugins/api/DependentScoped.java rename to log4j-plugins/src/main/java/org/apache/logging/log4j/plugins/di/DependentScoped.java index b6f058c..45ffeaf 100644 --- a/log4j-plugins/src/main/java/org/apache/logging/log4j/plugins/api/DependentScoped.java +++ b/log4j-plugins/src/main/java/org/apache/logging/log4j/plugins/di/DependentScoped.java @@ -15,7 +15,7 @@ * limitations under the license. */ -package org.apache.logging.log4j.plugins.api; +package org.apache.logging.log4j.plugins.di; import java.lang.annotation.Documented; import java.lang.annotation.ElementType; diff --git a/log4j-plugins/src/main/java/org/apache/logging/log4j/plugins/api/Disposes.java b/log4j-plugins/src/main/java/org/apache/logging/log4j/plugins/di/Disposes.java similarity index 63% rename from log4j-plugins/src/main/java/org/apache/logging/log4j/plugins/api/Disposes.java rename to log4j-plugins/src/main/java/org/apache/logging/log4j/plugins/di/Disposes.java index d89873a..220775b 100644 --- a/log4j-plugins/src/main/java/org/apache/logging/log4j/plugins/api/Disposes.java +++ b/log4j-plugins/src/main/java/org/apache/logging/log4j/plugins/di/Disposes.java @@ -15,7 +15,7 @@ * limitations under the license. */ -package org.apache.logging.log4j.plugins.api; +package org.apache.logging.log4j.plugins.di; import java.lang.annotation.Documented; import java.lang.annotation.ElementType; @@ -23,7 +23,13 @@ import java.lang.annotation.Retention; import java.lang.annotation.RetentionPolicy; import java.lang.annotation.Target; -// TODO: validate this is not allowed on static methods +/** + * Marks a parameter of a method to be used for disposing a {@linkplain Produces produced instance}. A disposer method + * more generally is a non-abstract method in a bean class with one argument annotated with {@code @Disposes} to indicate + * the injection point for the produced bean for disposal along with any other normal injectable parameters if desired. + * A bean can have more than one disposer method, but each disposer method can only dispose of one produced type. + * Disposer methods can be static or non-static. Disposer methods are <em>not inherited</em> by subclasses. + */ @Retention(RetentionPolicy.RUNTIME) @Target(ElementType.PARAMETER) @Documented diff --git a/log4j-plugins/src/main/java/org/apache/logging/log4j/plugins/api/Ignore.java b/log4j-plugins/src/main/java/org/apache/logging/log4j/plugins/di/Ignore.java similarity index 96% rename from log4j-plugins/src/main/java/org/apache/logging/log4j/plugins/api/Ignore.java rename to log4j-plugins/src/main/java/org/apache/logging/log4j/plugins/di/Ignore.java index 3c97846..f060fc3 100644 --- a/log4j-plugins/src/main/java/org/apache/logging/log4j/plugins/api/Ignore.java +++ b/log4j-plugins/src/main/java/org/apache/logging/log4j/plugins/di/Ignore.java @@ -15,7 +15,7 @@ * limitations under the license. */ -package org.apache.logging.log4j.plugins.api; +package org.apache.logging.log4j.plugins.di; import java.lang.annotation.Documented; import java.lang.annotation.ElementType; diff --git a/log4j-plugins/src/main/java/org/apache/logging/log4j/plugins/api/Inject.java b/log4j-plugins/src/main/java/org/apache/logging/log4j/plugins/di/Inject.java similarity index 96% rename from log4j-plugins/src/main/java/org/apache/logging/log4j/plugins/api/Inject.java rename to log4j-plugins/src/main/java/org/apache/logging/log4j/plugins/di/Inject.java index 343df0c..b25e7f6 100644 --- a/log4j-plugins/src/main/java/org/apache/logging/log4j/plugins/api/Inject.java +++ b/log4j-plugins/src/main/java/org/apache/logging/log4j/plugins/di/Inject.java @@ -15,7 +15,7 @@ * limitations under the license. */ -package org.apache.logging.log4j.plugins.api; +package org.apache.logging.log4j.plugins.di; import java.lang.annotation.Documented; import java.lang.annotation.ElementType; diff --git a/log4j-plugins/src/main/java/org/apache/logging/log4j/plugins/api/Named.java b/log4j-plugins/src/main/java/org/apache/logging/log4j/plugins/di/Named.java similarity index 96% rename from log4j-plugins/src/main/java/org/apache/logging/log4j/plugins/api/Named.java rename to log4j-plugins/src/main/java/org/apache/logging/log4j/plugins/di/Named.java index b4f67e7..bff71ca 100644 --- a/log4j-plugins/src/main/java/org/apache/logging/log4j/plugins/api/Named.java +++ b/log4j-plugins/src/main/java/org/apache/logging/log4j/plugins/di/Named.java @@ -15,7 +15,7 @@ * limitations under the license. */ -package org.apache.logging.log4j.plugins.api; +package org.apache.logging.log4j.plugins.di; import org.apache.logging.log4j.plugins.name.NameProvider; import org.apache.logging.log4j.plugins.name.NamedQualifierNameProvider; diff --git a/log4j-plugins/src/main/java/org/apache/logging/log4j/plugins/api/PostConstruct.java b/log4j-plugins/src/main/java/org/apache/logging/log4j/plugins/di/PostConstruct.java similarity index 96% rename from log4j-plugins/src/main/java/org/apache/logging/log4j/plugins/api/PostConstruct.java rename to log4j-plugins/src/main/java/org/apache/logging/log4j/plugins/di/PostConstruct.java index ad5263a..d70bbf3 100644 --- a/log4j-plugins/src/main/java/org/apache/logging/log4j/plugins/api/PostConstruct.java +++ b/log4j-plugins/src/main/java/org/apache/logging/log4j/plugins/di/PostConstruct.java @@ -15,7 +15,7 @@ * limitations under the license. */ -package org.apache.logging.log4j.plugins.api; +package org.apache.logging.log4j.plugins.di; import java.lang.annotation.Documented; import java.lang.annotation.ElementType; diff --git a/log4j-plugins/src/main/java/org/apache/logging/log4j/plugins/api/PreDestroy.java b/log4j-plugins/src/main/java/org/apache/logging/log4j/plugins/di/PreDestroy.java similarity index 96% rename from log4j-plugins/src/main/java/org/apache/logging/log4j/plugins/api/PreDestroy.java rename to log4j-plugins/src/main/java/org/apache/logging/log4j/plugins/di/PreDestroy.java index 4d6abaa..acf9f65 100644 --- a/log4j-plugins/src/main/java/org/apache/logging/log4j/plugins/api/PreDestroy.java +++ b/log4j-plugins/src/main/java/org/apache/logging/log4j/plugins/di/PreDestroy.java @@ -15,7 +15,7 @@ * limitations under the license. */ -package org.apache.logging.log4j.plugins.api; +package org.apache.logging.log4j.plugins.di; import java.lang.annotation.Documented; import java.lang.annotation.ElementType; diff --git a/log4j-plugins/src/main/java/org/apache/logging/log4j/plugins/di/Produces.java b/log4j-plugins/src/main/java/org/apache/logging/log4j/plugins/di/Produces.java new file mode 100644 index 0000000..ba641dd --- /dev/null +++ b/log4j-plugins/src/main/java/org/apache/logging/log4j/plugins/di/Produces.java @@ -0,0 +1,52 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You under the Apache license, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the license for the specific language governing permissions and + * limitations under the license. + */ + +package org.apache.logging.log4j.plugins.di; + +import java.lang.annotation.Documented; +import java.lang.annotation.ElementType; +import java.lang.annotation.Retention; +import java.lang.annotation.RetentionPolicy; +import java.lang.annotation.Target; + +/** + * Marks a method or field as a producer for bean instances. Producer methods are essentially bean factories, while + * producer fields are bean factories that only depend on its containing bean state. This annotation works similarly + * to the {@code @Produces} annotation in CDI or the {@code @Bean} annotation in Spring. + * There are a few rules related to producers: + * + * <ul> + * <li>Producer methods must be non-abstract methods of a bean class (static or not).</li> + * <li>Producer fields must be from a bean class.</li> + * <li>If the bean class's scope is different from the produced bean, then it must be a larger scope.</li> + * <li>If producer methods return a nullable value, then it must be {@link DependentScoped}.</li> + * <li>Producer method return type and producer field type must not be a type variable.</li> + * <li>Producer method return type and producer field type may be parameterized only if it specifies actual types + * or a type variable for each parameter, the latter case also required to be {@link DependentScoped}.</li> + * <li>Beans may declare multiple producer methods and fields.</li> + * <li>Producers are <em>not inherited</em> by subclasses.</li> + * </ul> + * + * @see Disposes + * @see <a href="https://docs.jboss.org/cdi/api/2.0/javax/enterprise/inject/Produces.html";>CDI @Produces API Docs</a> + * @see <a href="https://docs.spring.io/spring-framework/docs/current/javadoc-api/org/springframework/context/annotation/Bean.html";>Spring @Bean API Docs</a> + */ +@Target({ElementType.METHOD, ElementType.FIELD}) +@Retention(RetentionPolicy.RUNTIME) +@Documented +public @interface Produces { +} diff --git a/log4j-plugins/src/main/java/org/apache/logging/log4j/plugins/api/Provider.java b/log4j-plugins/src/main/java/org/apache/logging/log4j/plugins/di/Provider.java similarity index 94% rename from log4j-plugins/src/main/java/org/apache/logging/log4j/plugins/api/Provider.java rename to log4j-plugins/src/main/java/org/apache/logging/log4j/plugins/di/Provider.java index 0407c5c..18b71dc 100644 --- a/log4j-plugins/src/main/java/org/apache/logging/log4j/plugins/api/Provider.java +++ b/log4j-plugins/src/main/java/org/apache/logging/log4j/plugins/di/Provider.java @@ -15,7 +15,7 @@ * limitations under the license. */ -package org.apache.logging.log4j.plugins.api; +package org.apache.logging.log4j.plugins.di; public interface Provider<T> { T get(); diff --git a/log4j-plugins/src/main/java/org/apache/logging/log4j/plugins/api/QualifierType.java b/log4j-plugins/src/main/java/org/apache/logging/log4j/plugins/di/QualifierType.java similarity index 96% rename from log4j-plugins/src/main/java/org/apache/logging/log4j/plugins/api/QualifierType.java rename to log4j-plugins/src/main/java/org/apache/logging/log4j/plugins/di/QualifierType.java index 9fc160a..a5d0821 100644 --- a/log4j-plugins/src/main/java/org/apache/logging/log4j/plugins/api/QualifierType.java +++ b/log4j-plugins/src/main/java/org/apache/logging/log4j/plugins/di/QualifierType.java @@ -15,7 +15,7 @@ * limitations under the license. */ -package org.apache.logging.log4j.plugins.api; +package org.apache.logging.log4j.plugins.di; import java.lang.annotation.Documented; import java.lang.annotation.ElementType; diff --git a/log4j-plugins/src/main/java/org/apache/logging/log4j/plugins/api/ScopeType.java b/log4j-plugins/src/main/java/org/apache/logging/log4j/plugins/di/ScopeType.java similarity index 73% rename from log4j-plugins/src/main/java/org/apache/logging/log4j/plugins/api/ScopeType.java rename to log4j-plugins/src/main/java/org/apache/logging/log4j/plugins/di/ScopeType.java index ce3a8d4..2afcad7 100644 --- a/log4j-plugins/src/main/java/org/apache/logging/log4j/plugins/api/ScopeType.java +++ b/log4j-plugins/src/main/java/org/apache/logging/log4j/plugins/di/ScopeType.java @@ -15,7 +15,7 @@ * limitations under the license. */ -package org.apache.logging.log4j.plugins.api; +package org.apache.logging.log4j.plugins.di; import java.lang.annotation.Documented; import java.lang.annotation.ElementType; @@ -23,7 +23,15 @@ import java.lang.annotation.Retention; import java.lang.annotation.RetentionPolicy; import java.lang.annotation.Target; -// essentially the same as @Scope and @NormalScope combined; no distinction necessary here +/** + * Marks an annotation as a scope type. The scope of a bean determines its lifecycle and the visibility of its + * instances. In particular, this controls: + * <ul> + * <li>when new instances of a bean are created,</li> + * <li>when existing instances of a bean are destroyed, and</li> + * <li>which injected references refer to any instance of the bean.</li> + * </ul> + */ @Target(ElementType.ANNOTATION_TYPE) // on an annotation typically with @Target(TYPE), but we use static factory methods @Retention(RetentionPolicy.RUNTIME) @Documented diff --git a/log4j-plugins/src/main/java/org/apache/logging/log4j/plugins/api/SingletonScoped.java b/log4j-plugins/src/main/java/org/apache/logging/log4j/plugins/di/SingletonScoped.java similarity index 96% rename from log4j-plugins/src/main/java/org/apache/logging/log4j/plugins/api/SingletonScoped.java rename to log4j-plugins/src/main/java/org/apache/logging/log4j/plugins/di/SingletonScoped.java index 5d8f967..5aef475 100644 --- a/log4j-plugins/src/main/java/org/apache/logging/log4j/plugins/api/SingletonScoped.java +++ b/log4j-plugins/src/main/java/org/apache/logging/log4j/plugins/di/SingletonScoped.java @@ -15,7 +15,7 @@ * limitations under the license. */ -package org.apache.logging.log4j.plugins.api; +package org.apache.logging.log4j.plugins.di; import java.lang.annotation.Documented; import java.lang.annotation.ElementType; diff --git a/log4j-plugins/src/main/java/org/apache/logging/log4j/plugins/api/package-info.java b/log4j-plugins/src/main/java/org/apache/logging/log4j/plugins/di/package-info.java similarity index 95% rename from log4j-plugins/src/main/java/org/apache/logging/log4j/plugins/api/package-info.java rename to log4j-plugins/src/main/java/org/apache/logging/log4j/plugins/di/package-info.java index cbddbbf..2e075fe 100644 --- a/log4j-plugins/src/main/java/org/apache/logging/log4j/plugins/api/package-info.java +++ b/log4j-plugins/src/main/java/org/apache/logging/log4j/plugins/di/package-info.java @@ -22,4 +22,4 @@ * * @since 3.0 */ -package org.apache.logging.log4j.plugins.api; +package org.apache.logging.log4j.plugins.di; diff --git a/log4j-plugins/src/main/java/org/apache/logging/log4j/plugins/name/NamedQualifierNameProvider.java b/log4j-plugins/src/main/java/org/apache/logging/log4j/plugins/name/NamedQualifierNameProvider.java index 3f7301f..803263d 100644 --- a/log4j-plugins/src/main/java/org/apache/logging/log4j/plugins/name/NamedQualifierNameProvider.java +++ b/log4j-plugins/src/main/java/org/apache/logging/log4j/plugins/name/NamedQualifierNameProvider.java @@ -17,7 +17,7 @@ package org.apache.logging.log4j.plugins.name; -import org.apache.logging.log4j.plugins.api.Named; +import org.apache.logging.log4j.plugins.di.Named; import org.apache.logging.log4j.util.Strings; import java.util.Optional; diff --git a/log4j-plugins/src/main/java9/module-info.java b/log4j-plugins/src/main/java9/module-info.java index 147c65b..b4144dc 100644 --- a/log4j-plugins/src/main/java9/module-info.java +++ b/log4j-plugins/src/main/java9/module-info.java @@ -17,6 +17,7 @@ module org.apache.logging.log4j.plugins { exports org.apache.logging.log4j.plugins; exports org.apache.logging.log4j.plugins.convert; + exports org.apache.logging.log4j.plugins.di; exports org.apache.logging.log4j.plugins.processor; exports org.apache.logging.log4j.plugins.util; exports org.apache.logging.log4j.plugins.validation;
