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 2021/06/20 00:17:22 UTC
[logging-log4j2] 01/04: Add more DI API docs with some renames
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 <bo...@gmail.com>
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;