extend CI to run tests with JDK 21

This was previously blocked by our Gradle version being too old.
Now that we can run the tests with JDK 21 it shows though,
that the `Annotation` `toString()` behavior has changed again.
Unfortunately, this always either causes complexity on the production or test side.
If we want to test the `AnnotationProxy.toString()` behavior,
then either we have to add a workaround to the test code,
or we have to adjust the production code to produce the equivalent `toString()` value.
I opted for the latter in hopes that they will finally stop changing the `toString()` style every couple of versions.

Signed-off-by: Peter Gafert <peter.gafert@archunit.org>

.github/workflows/build.yml

@@ -8,7 +8,7 @@ on:
   pull_request:
 
 env:
-  build_java_version: 17
+  build_java_version: 21
 
 jobs:
   build:
@@ -47,6 +47,7 @@ jobs:
           - 8
           - 11
           - 17
+          - 21
     runs-on: ${{ matrix.os }}
     steps:
       - name: Checkout
@@ -96,6 +97,7 @@ jobs:
           - 8
           - 11
           - 17
+          - 21
     runs-on: ${{ matrix.os }}
     steps:
       - name: Checkout

archunit/src/jdk9main/java/com/tngtech/archunit/core/domain/Java9DomainPlugin.java

@@ -24,11 +24,13 @@
 @SuppressWarnings("unused")
 class Java9DomainPlugin implements DomainPlugin {
     @Override
-    public void plugInAnnotationPropertiesFormatter(InitialConfiguration<AnnotationPropertiesFormatter> propertiesFormatter) {
-        propertiesFormatter.set(AnnotationPropertiesFormatter.configure()
-                .formattingArraysWithCurlyBrackets()
-                .formattingTypesAsClassNames()
-                .quotingStrings()
-                .build());
+    public void plugInAnnotationFormatter(InitialConfiguration<AnnotationFormatter> propertiesFormatter) {
+        propertiesFormatter.set(
+                AnnotationFormatter.formatAnnotationType(JavaClass::getName)
+                        .formatProperties(config -> config
+                                .formattingArraysWithCurlyBrackets()
+                                .formattingTypesAsClassNames()
+                                .quotingStrings()
+                        ));
     }
 }

archunit/src/main/java/com/tngtech/archunit/core/PluginLoader.java

@@ -139,7 +139,8 @@ public Creator<T> load(String pluginClassName) {
     public enum JavaVersion {
 
         JAVA_9(9),
-        JAVA_14(14);
+        JAVA_14(14),
+        JAVA_21(21);
 
         private final int releaseVersion;
 

archunit/src/main/java/com/tngtech/archunit/core/domain/AnnotationFormatter.java

@@ -0,0 +1,157 @@
+/*
+ * Copyright 2014-2025 TNG Technology Consulting GmbH
+ *
+ * Licensed 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 com.tngtech.archunit.core.domain;
+
+import java.lang.reflect.Array;
+import java.util.List;
+import java.util.Map;
+import java.util.function.Consumer;
+import java.util.function.Function;
+import java.util.stream.IntStream;
+
+import com.google.common.base.Joiner;
+
+import static com.google.common.base.Preconditions.checkNotNull;
+import static java.util.function.Function.identity;
+import static java.util.stream.Collectors.joining;
+import static java.util.stream.Collectors.toList;
+
+class AnnotationFormatter {
+    private final Function<JavaClass, String> annotationTypeFormatter;
+    private final AnnotationPropertiesFormatter propertiesFormatter;
+
+    AnnotationFormatter(Function<JavaClass, String> annotationTypeFormatter, AnnotationPropertiesFormatter propertiesFormatter) {
+        this.annotationTypeFormatter = annotationTypeFormatter;
+        this.propertiesFormatter = propertiesFormatter;
+    }
+
+    String format(JavaClass annotationType, Map<String, Object> annotationProperties) {
+        return String.format("@%s(%s)", annotationTypeFormatter.apply(annotationType), propertiesFormatter.formatProperties(annotationProperties));
+    }
+
+    static Builder formatAnnotationType(Function<JavaClass, String> annotationTypeFormatter) {
+        return new Builder(annotationTypeFormatter);
+    }
+
+    static class Builder {
+        private final Function<JavaClass, String> annotationTypeFormatter;
+
+        private Builder(Function<JavaClass, String> annotationTypeFormatter) {
+            this.annotationTypeFormatter = annotationTypeFormatter;
+        }
+
+        AnnotationFormatter formatProperties(Consumer<AnnotationPropertiesFormatter.Builder> config) {
+            AnnotationPropertiesFormatter.Builder propertiesFormatterBuilder = AnnotationPropertiesFormatter.configure();
+            config.accept(propertiesFormatterBuilder);
+            return new AnnotationFormatter(annotationTypeFormatter, propertiesFormatterBuilder.build());
+        }
+    }
+
+    static class AnnotationPropertiesFormatter {
+        private final Function<List<String>, String> arrayFormatter;
+        private final Function<Class<?>, String> typeFormatter;
+        private final Function<String, String> stringFormatter;
+        private final boolean omitOptionalIdentifierForSingleElementAnnotations;
+
+        private AnnotationPropertiesFormatter(Builder builder) {
+            this.arrayFormatter = checkNotNull(builder.arrayFormatter);
+            this.typeFormatter = checkNotNull(builder.typeFormatter);
+            this.stringFormatter = checkNotNull(builder.stringFormatter);
+            this.omitOptionalIdentifierForSingleElementAnnotations = builder.omitOptionalIdentifierForSingleElementAnnotations;
+        }
+
+        String formatProperties(Map<String, Object> properties) {
+            // see Builder#omitOptionalIdentifierForSingleElementAnnotations() for documentation
+            if (properties.size() == 1 && properties.containsKey("value") && omitOptionalIdentifierForSingleElementAnnotations) {
+                return formatValue(properties.get("value"));
+            }
+
+            return properties.entrySet().stream()
+                    .map(entry -> entry.getKey() + "=" + formatValue(entry.getValue()))
+                    .collect(joining(", "));
+        }
+
+        String formatValue(Object input) {
+            if (input instanceof Class<?>) {
+                return typeFormatter.apply((Class<?>) input);
+            }
+            if (input instanceof String) {
+                return stringFormatter.apply((String) input);
+            }
+            if (!input.getClass().isArray()) {
+                return String.valueOf(input);
+            }
+
+            List<String> elemToString = IntStream.range(0, Array.getLength(input))
+                    .mapToObj(i -> formatValue(Array.get(input, i)))
+                    .collect(toList());
+            return arrayFormatter.apply(elemToString);
+        }
+
+        static Builder configure() {
+            return new Builder();
+        }
+
+        static class Builder {
+            private Function<List<String>, String> arrayFormatter;
+            private Function<Class<?>, String> typeFormatter;
+            private Function<String, String> stringFormatter = identity();
+            private boolean omitOptionalIdentifierForSingleElementAnnotations = false;
+
+            Builder formattingArraysWithSquareBrackets() {
+                arrayFormatter = input -> "[" + Joiner.on(", ").join(input) + "]";
+                return this;
+            }
+
+            Builder formattingArraysWithCurlyBrackets() {
+                arrayFormatter = input -> "{" + Joiner.on(", ").join(input) + "}";
+                return this;
+            }
+
+            Builder formattingTypesToString() {
+                typeFormatter = String::valueOf;
+                return this;
+            }
+
+            Builder formattingTypesAsClassNames() {
+                typeFormatter = input -> input.getName() + ".class";
+                return this;
+            }
+
+            Builder quotingStrings() {
+                stringFormatter = input -> "\"" + input + "\"";
+                return this;
+            }
+
+            /**
+             * Configures that the identifier is omitted if the annotation is a
+             * <a href="https://docs.oracle.com/javase/specs/jls/se11/html/jls-9.html#jls-9.7.3">single-element annotation</a>
+             * and the identifier of the only element is "value".
+             *
+             * <ul><li>Example with this configuration: {@code @Copyright("2020 Acme Corporation")}</li>
+             * <li>Example without this configuration: {@code @Copyright(value="2020 Acme Corporation")}</li></ul>
+             */
+            Builder omitOptionalIdentifierForSingleElementAnnotations() {
+                omitOptionalIdentifierForSingleElementAnnotations = true;
+                return this;
+            }
+
+            AnnotationPropertiesFormatter build() {
+                return new AnnotationPropertiesFormatter(this);
+            }
+        }
+    }
+}

archunit/src/main/java/com/tngtech/archunit/core/domain/AnnotationProxy.java

@@ -37,10 +37,10 @@
 
 @MayResolveTypesViaReflection(reason = "We depend on the classpath, if we proxy an annotation type")
 class AnnotationProxy {
-    private static final InitialConfiguration<AnnotationPropertiesFormatter> propertiesFormatter = new InitialConfiguration<>();
+    private static final InitialConfiguration<AnnotationFormatter> annotationFormatter = new InitialConfiguration<>();
 
     static {
-        DomainPlugin.Loader.loadForCurrentPlatform().plugInAnnotationPropertiesFormatter(propertiesFormatter);
+        DomainPlugin.Loader.loadForCurrentPlatform().plugInAnnotationFormatter(annotationFormatter);
     }
 
     public static <A extends Annotation> A of(Class<A> annotationType, JavaAnnotation<?> toProxy) {
@@ -277,12 +277,7 @@ private ToStringHandler(Class<?> annotationType, JavaAnnotation<?> toProxy, Conv
 
         @Override
         public Object handle(Object proxy, Method method, Object[] args) {
-            return String.format("@%s(%s)", toProxy.getRawType().getName(), propertiesString());
-        }
-
-        private String propertiesString() {
-            Map<String, Object> unwrappedProperties = unwrapProxiedProperties();
-            return propertiesFormatter.get().formatProperties(unwrappedProperties);
+            return annotationFormatter.get().format(toProxy.getRawType(), unwrapProxiedProperties());
         }
 
         private Map<String, Object> unwrapProxiedProperties() {