Simplify name and alias annotation processing #3877

jvz · 2025-08-11T16:18:02Z

This fixes #3870

ppkarwasz · 2025-08-13T21:15:03Z

Hi @jvz,

Don't worry, I have seen your PR, but until the end of the week I don't really have the time to review it.

jvz · 2025-08-13T22:44:54Z

I'm trying to get the build to work 😆

ppkarwasz · 2025-08-14T05:24:39Z

The MacOS failure is due to a problem in the Maven Wrapper script.
It was fixed in #3676 for 2.x, but never ported.

jvz · 2025-08-18T17:01:31Z

Now it seems there's a Windows-specific build issue related to TLS settings.

vy

@jvz, +93/-615 LoC is impressive! 💯 I've some questions that I will appreciate it if you can help with.

vy · 2025-08-19T07:38:25Z

log4j-plugins/src/main/java/org/apache/logging/log4j/plugins/NameProvider.java

+/**
+ * Marks another annotation as one providing a name for an object. The name is obtained from
+ * the annotation element named {@code value}. This element can be a {@code String} or {@code String[]}.
+ * When specified as an array, the first element is used.
+ */


Marks another annotation as one providing a name for an object.

Oookay... PluginElement, PluginValue, etc. are NameProviders. Got it.

The name is obtained from the annotation element named value.
This element can be a String or String[].
When specified as an array, the first element is used.

I am totally lost here. Would you mind elaborating on this.

I can try. The idea here is that an annotation like @Named(String[] value) can specify both the name (the first element of the array) and additional aliases (the rest of the array). However, some annotations like @PluginAliases(String[] value) use the whole array.

Right! Got it!

Suggested change

/**

* Marks another annotation as one providing a name for an object. The name is obtained from

* the annotation element named {@code value}. This element can be a {@code String} or {@code String[]}.

* When specified as an array, the first element is used.

*/

/**

* Marks another annotation as one providing a name for an object.

* The name is obtained from the annotation element named {@code value}.

* This element can be a {@code String} or {@code String[]}.

* When specified as an array, the first element is used.

* <h2>Examples:</h2>

* <ul>

* <li>{@code @NameProvider @Named(String value)} - {@code value} will be used as the name

* <li>{@code @NameProvider @PluginAliases(String[] value)} - {@code value[0]} will be used as the name

* </ul>

*/

vy · 2025-08-19T07:39:32Z

log4j-plugins/src/main/java/org/apache/logging/log4j/plugins/Named.java

-@NameProvider(NamedQualifierNameProvider.class)
-@AliasesProvider(NamedQualifierNameProvider.class)
+@NameProvider
+@AliasesProvider(offset = 1)


I'm confused by offset and its function. (Yes, I've read its Javadoc.) Would you mind explaining it a little bit more, please?

vy · 2025-08-19T07:41:13Z

log4j-plugins/src/main/java/org/apache/logging/log4j/plugins/Namespace.java

@@ -23,7 +23,7 @@
 import java.lang.annotation.Target;

 /**
- * Annotations to separate {@link org.apache.logging.log4j.plugins.name.NameProvider} names into namespaces.
+ * Annotations to separate {@link NameProvider} names into namespaces.


What does "NameProvider names" mean? "Names provided by NameProviders"?

vy · 2025-08-19T07:42:00Z

log4j-plugins/src/main/java/org/apache/logging/log4j/plugins/Namespace.java

 * For example, the {@linkplain Configurable Core namespace} is used with the {@link Node} API, while the TypeConverter
 * namespace is used with the {@link org.apache.logging.log4j.plugins.convert.TypeConverter} API.


I think this example needs to be explained more.

vy · 2025-08-19T07:44:30Z

src/site/antora/modules/ROOT/pages/manual/dependencyinjection.adoc

@@ -53,7 +53,7 @@ Injection points are injectable fields or parameters where a dependency should b
 _Injectable fields_ are fields annotated with `@Inject` or a qualifier annotation.
 _Injectable methods_ are methods annotated with `@Inject` or are not annotated with a factory annotation and have at least one parameter annotated with a qualifier annotation.
 _Injectable constructors_ are constructors annotated with `@Inject`; only one such constructor should exist per class.
-When a field or parameter is annotated with a name-providing annotation (i.e., an annotation annotated with `@org.apache.logging.log4j.plugins.name.NameProvider`), then the provided name or name of the field or parameter are included in the `Key<T>` for the injection point.
+When a field or parameter is annotated with a name-providing annotation (i.e., an annotation annotated with `@org.apache.logging.log4j.plugins.NameProvider`), then the provided name or name of the field or parameter are included in the `Key<T>` for the injection point.


Suggested change

When a field or parameter is annotated with a name-providing annotation (i.e., an annotation annotated with `@org.apache.logging.log4j.plugins.NameProvider`), then the provided name or name of the field or parameter are included in the `Key<T>` for the injection point.

When a field or parameter is annotated with `@NameProvider`, then the provided name or name of the field or parameter are included in the `Key<T>` for the injection point.

vy · 2025-08-19T07:51:53Z

src/site/antora/modules/ROOT/pages/manual/dependencyinjection.adoc

... Lastly, no-arg methods annotated with @Inject are invoked which can be useful for post-injection initialization logic. Additional strategies for resolving factories for unbound keys may be registered which are consulted first before falling back to this @Inject reflection logic.

Do we have a use case for every single logic described above? For instance, I was not able to find a single usage of @Inject on a no-arg method. In a follow-up PR, can we remove and all other functionalities that do not (yet) serve a purpose?

It's there for a sort of @PostConstruct type of thing.

Yes, but without any usage. I am not keen on growing the public API, knowing that not even ourselves using it.

This doesn't "grow" the public API; it has been in the plugin DI system for multiple 3.0.0 releases already. If you're suggesting we can review old code that's already in main, then I don't see the point of reviewing PRs since it could be reviewed directly from main as demonstrated.

I'm not suggesting to address this (or any other remark of mine applying to old text) in this PR. I will create a separate issue for this.

vy · 2025-08-19T07:55:49Z

src/site/antora/modules/ROOT/pages/manual/dependencyinjection.adoc

as bundles which are instances or injectable Class<T> instances that contain one or more annotated factory methods.

"Bundle" is a very convoluted term in the Java ecosystem. Above statement literally describes a "factory collection/set", which we can consider replacing bundle with as a more self-explanatory term.

I called it "module" before as the concept is borrowed from Guice, but that gets confusing with Java modules. They're similar to spring @Configuration.

I'll leave the decision to you. You can resolve this conversation as you wish.

src/site/antora/modules/ROOT/pages/manual/dependencyinjection.adoc

Simplify name and alias annotation processing

af74f15

jvz added this to the 3.0.0-beta4 milestone Aug 11, 2025

jvz requested a review from ppkarwasz August 11, 2025 16:18

jvz added plugins Affects the plugin system minor API change labels Aug 11, 2025

jvz closed this Aug 11, 2025

jvz reopened this Aug 11, 2025

jvz closed this Aug 13, 2025

jvz reopened this Aug 13, 2025

Merge branch 'main' into feature/3.x/simplify-name-alias-processing

d20b7a2

vy reviewed Aug 19, 2025

View reviewed changes

		* For example, the {@linkplain Configurable Core namespace} is used with the {@link Node} API, while the TypeConverter
		* namespace is used with the {@link org.apache.logging.log4j.plugins.convert.TypeConverter} API.

	When a field or parameter is annotated with a name-providing annotation (i.e., an annotation annotated with `@org.apache.logging.log4j.plugins.NameProvider`), then the provided name or name of the field or parameter are included in the `Key<T>` for the injection point.
	When a field or parameter is annotated with `@NameProvider`, then the provided name or name of the field or parameter are included in the `Key<T>` for the injection point.

Uh oh!

Simplify name and alias annotation processing #3877

Are you sure you want to change the base?

Simplify name and alias annotation processing #3877

Uh oh!

Conversation

jvz commented Aug 11, 2025

Uh oh!

ppkarwasz commented Aug 13, 2025

Uh oh!

jvz commented Aug 13, 2025

Uh oh!

ppkarwasz commented Aug 14, 2025

Uh oh!

jvz commented Aug 18, 2025

Uh oh!

vy left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!