#932 Support executable elements in reference conditions

Author: GuusLieben

hartshorn-inject-configurations/src/main/java/org/dockbox/hartshorn/inject/condition/Condition.java

@@ -27,7 +27,7 @@
  * 
  * @author Guus Lieben
  */
-public sealed interface Condition permits IntrospectionCondition, TypeReferenceCondition {
+public sealed interface Condition permits IntrospectionCondition, ReferenceCondition {
 
     /**
      * Returns a {@link ConditionResult} that describes whether the condition is matched.

hartshorn-inject-configurations/src/main/java/org/dockbox/hartshorn/inject/condition/ConditionContext.java

@@ -31,7 +31,7 @@
  * @author Guus Lieben
  */
 public sealed class ConditionContext extends DefaultContext
-permits IntrospectedConditionContext, TypeReferenceConditionContext {
+permits IntrospectedConditionContext, ReferenceConditionContext {
 
     private final ConditionDeclaration condition;
 

hartshorn-inject-configurations/src/main/java/org/dockbox/hartshorn/inject/condition/ConditionMatcher.java

@@ -23,16 +23,13 @@
 import org.dockbox.hartshorn.inject.InjectionCapableApplication;
 import org.dockbox.hartshorn.inject.ObjectFactory;
 import org.dockbox.hartshorn.inject.ReflectionObjectFactory;
-import org.dockbox.hartshorn.util.introspect.scan.ClassReference;
-import org.dockbox.hartshorn.util.introspect.scan.TypeReference;
 import org.dockbox.hartshorn.util.introspect.view.AnnotatedElementView;
 import org.dockbox.hartshorn.util.introspect.view.EnclosableView;
-import org.dockbox.hartshorn.util.introspect.view.TypeView;
 import org.dockbox.hartshorn.util.option.Option;
 import org.dockbox.hartshorn.util.types.ClassFileUtilities;
 
 import java.lang.classfile.Annotation;
-import java.lang.classfile.ClassModel;
+import java.lang.classfile.AttributedElement;
 import java.util.ArrayDeque;
 import java.util.LinkedList;
 import java.util.List;
@@ -117,10 +114,10 @@ public ConditionMatcher includeEnclosingConditions(boolean includeEnclosingCondi
      * enclosed element to the most enclosed element (the given element). This means that
      * class-level conditions are evaluated before method-level conditions.
      *
-     * <p>{@link TypeReferenceCondition reference conditions} are also matched for any type views
-     * encountered during the matching process. Note that this may cause issues with class loading
-     * if the type references point to classes that are not available at runtime. In such cases,
-     * {@link #match(TypeReference, ContextView...)} should be used directly to avoid class
+     * <p>{@link ReferenceCondition reference conditions} are also matched for any reference
+     * views encountered during the matching process. Note that this may cause issues with class
+     * loading if the references point to classes that are not available at runtime. In such cases,
+     * {@link #match(AttributedElement, ContextView...)} should be used directly to avoid class
      * loading.
      *
      * @param annotatedElementContext the annotated element to match against
@@ -149,8 +146,9 @@ public boolean match(AnnotatedElementView annotatedElementContext, ContextView..
                 return false;
             }
 
-            if (elementView instanceof TypeView<?> typeView
-                && !this.match(new ClassReference(typeView.type()), contexts)) {
+            if (!elementView.classFileElement()
+                    .ofType(AttributedElement.class)
+                    .test(element -> this.match(element, contexts), true)) {
                 return false;
             }
         }
@@ -159,35 +157,28 @@ public boolean match(AnnotatedElementView annotatedElementContext, ContextView..
 
     /**
      * Matches the {@link RequiresReferenceCondition} annotations of the given
-     * {@link TypeReference}, providing any additional {@link ContextView} instances to the
+     * {@link AttributedElement}, providing any additional {@link ContextView} instances to the
      * {@link ConditionContext} that is used to match the
      * {@link Condition condition implementations}. If any of the conditions do not match, this
      * method will return {@code false}. If all conditions match, this method will return
      * {@code true}.
      *
-     * @param typeReference the type reference to match against
+     * @param element the attributed element to match against
      * @param contexts the additional contexts to provide to the condition context
-     *
      * @return {@code true} if all conditions match, {@code false} otherwise
      */
-    public boolean match(TypeReference typeReference, ContextView... contexts) {
-        ClassModel classModel = ClassFileUtilities.getClassModel(
-            typeReference.qualifiedName()
-        ).orElseThrow(() -> new IllegalStateException(
-            "Could not load class model for type reference: " + typeReference
-        ));
+    public boolean match(AttributedElement element, ContextView... contexts) {
         List<Annotation> annotations = ClassFileUtilities.getMetaAnnotations(
-            classModel,
-            RequiresReferenceCondition.class
+                element,
+                RequiresReferenceCondition.class
         );
         for (Annotation annotation : annotations) {
             var declaration = ReferenceConditionDeclaration.createFromMetaAnnotation(annotation);
-            TypeReferenceConditionContext conditionContext =
-                new TypeReferenceConditionContext(
-                    declaration,
-                    typeReference,
-                    classModel
-                );
+            ReferenceConditionContext conditionContext =
+                    new ReferenceConditionContext(
+                            declaration,
+                            element
+                    );
             if (!this.matchConditionContext(conditionContext, declaration, contexts)) {
                 return false;
             }
@@ -251,7 +242,7 @@ private boolean matchConditionContext(
         // Application may still be starting, thus fallback should be used.
         final ObjectFactory objectFactory;
         if (application == null) {
-            assert context instanceof TypeReferenceConditionContext : """
+            assert context instanceof ReferenceConditionContext : """
                 Expected type reference condition context when application is starting.
                 Introspection-capable condition contexts require at least a partially
                 initialized application.

…ct/condition/TypeReferenceCondition.java …inject/condition/ReferenceCondition.javahartshorn-inject-configurations/src/main/java/org/dockbox/hartshorn/inject/condition/TypeReferenceCondition.java renamed to hartshorn-inject-configurations/src/main/java/org/dockbox/hartshorn/inject/condition/ReferenceCondition.java hartshorn-inject-configurations/src/main/java/org/dockbox/hartshorn/inject/condition/TypeReferenceCondition.java renamed to hartshorn-inject-configurations/src/main/java/org/dockbox/hartshorn/inject/condition/ReferenceCondition.java

@@ -17,18 +17,18 @@
 package org.dockbox.hartshorn.inject.condition;
 
 /**
- * A {@link Condition} that matches based on a type reference, without requiring the type to be
+ * A {@link Condition} that matches based on a reference, without requiring the element to be
  * loaded. This has the benefit of being able to evaluate conditions without causing class loading
  * early in the application lifecycle. The drawback is that the condition implementation must work
- * with type references with limited information (compared to loaded classes, which support full
+ * with references with limited information (compared to loaded elements, which support full
  * introspection).
  *
  * @since 0.7.0
  *
  * @author Guus Lieben
  */
 @FunctionalInterface
-public non-sealed interface TypeReferenceCondition extends Condition {
+public non-sealed interface ReferenceCondition extends Condition {
 
     /**
      * Returns a {@link ConditionResult} that describes whether the condition is matched.
@@ -39,11 +39,11 @@ public non-sealed interface TypeReferenceCondition extends Condition {
      */
     @Override
     default ConditionResult matches(ConditionContext context) {
-        if (context instanceof TypeReferenceConditionContext referenceConditionContext) {
+        if (context instanceof ReferenceConditionContext referenceConditionContext) {
             return this.matches(referenceConditionContext);
         }
         return ConditionResult.notMatched(
-                "ConditionContext is not an instance of TypeReferenceConditionContext"
+                "ConditionContext is not an instance of ReferenceConditionContext"
         );
     }
 
@@ -53,5 +53,5 @@ default ConditionResult matches(ConditionContext context) {
      * @param context the type reference condition context
      * @return the condition result
      */
-    ConditionResult matches(TypeReferenceConditionContext context);
+    ConditionResult matches(ReferenceConditionContext context);
 }

…ition/TypeReferenceConditionContext.java …condition/ReferenceConditionContext.javahartshorn-inject-configurations/src/main/java/org/dockbox/hartshorn/inject/condition/TypeReferenceConditionContext.java renamed to hartshorn-inject-configurations/src/main/java/org/dockbox/hartshorn/inject/condition/ReferenceConditionContext.java hartshorn-inject-configurations/src/main/java/org/dockbox/hartshorn/inject/condition/TypeReferenceConditionContext.java renamed to hartshorn-inject-configurations/src/main/java/org/dockbox/hartshorn/inject/condition/ReferenceConditionContext.java

@@ -17,45 +17,31 @@
 package org.dockbox.hartshorn.inject.condition;
 
 import java.lang.classfile.AttributedElement;
-import org.dockbox.hartshorn.util.introspect.scan.TypeReference;
 
 /**
- * A context that is used during the evaluation of a condition. This includes the type reference
- * that is being evaluated, and the {@link RequiresReferenceCondition} annotation that is used to
- * evaluate the condition.
+ * A context that is used during the evaluation of a condition. This context provides access to the
+ * {@link AttributedElement class file element} being evaluated. Unlike the
+ * {@link IntrospectedConditionContext}, this context does not ensure that the element is fully
+ * loaded by the JVM, and may therefore be used in earlier stages of the injection process.
  *
  * @see RequiresReferenceCondition
  *
  * @since 0.7.0
  *
  * @author Guus Lieben
  */
-public non-sealed class TypeReferenceConditionContext extends ConditionContext {
+public non-sealed class ReferenceConditionContext extends ConditionContext {
 
-    private final TypeReference typeReference;
     private final AttributedElement element;
 
-    public TypeReferenceConditionContext(
+    public ReferenceConditionContext(
             ConditionDeclaration condition,
-            TypeReference typeReference,
             AttributedElement element
     ) {
         super(condition);
-        this.typeReference = typeReference;
         this.element = element;
     }
 
-    /**
-     * Returns the type reference in which the condition is being evaluated. This may match the
-     * {@link #element()} if the element is a type, but may also represent a member or other
-     * annotated element within the type.
-     *
-     * @return the type reference being evaluated
-     */
-    public TypeReference typeReference() {
-        return this.typeReference;
-    }
-
     /**
      * Returns the element being evaluated. This may be the type itself, but may also be a member or
      * other annotated element within the type.

hartshorn-inject-configurations/src/main/java/org/dockbox/hartshorn/inject/condition/RequiresReferenceCondition.java

@@ -24,20 +24,16 @@
 import java.lang.annotation.Target;
 
 /**
- * A condition that requires conditions to be met based on type references. Unlike
- * {@link RequiresCondition}, this annotation is specifically designed to work with conditions that
- * evaluate type references, such as classes or interfaces, without needing to load the classes into
- * the JVM.
+ * A condition that requires conditions to be met based on
+ * {@link java.lang.classfile.AttributedElement class file elements}.
  *
- * <p>This approach has the benefit of avoiding class loading issues, such as
- * {@link ClassNotFoundException ClassNotFoundExceptions}, when checking for the presence of
- * classes that may not be available at runtime. By using type references, conditions can be
- * evaluated based on metadata alone, allowing for safer and more flexible condition checks. The
- * drawback is that the condition implementations cannot rely on loaded classes, and must
- * instead work with type metadata.
+ * <p>By using type references, conditions can be evaluated based on metadata alone, allowing for
+ * safer and more flexible condition checks. The drawback is that the condition implementations
+ * cannot rely on loaded classes, and must instead work with type metadata.
  *
- * <p>Due to the nature of type references, meta annotations of this annotation are supported, but
- * lack hierarchy support (i.e. meta-meta annotations and attribute aliases are not supported).
+ * <p>Due to the nature of type references, only meta annotations of this annotation are supported,
+ * but these lack hierarchy support (i.e. meta-meta annotations and attribute aliases are not
+ * supported).
  *
  * <pre>{@code
  * @RequiresReferenceCondition(condition  = SampleCondition.class)
@@ -62,7 +58,7 @@
      *
      * @return the condition that is required to be met
      */
-    Class<? extends TypeReferenceCondition> condition();
+    Class<? extends ReferenceCondition> condition();
 
     /**
      * Whether to fail on no match. If set to {@code true}, the operation will fail if the condition

hartshorn-inject-configurations/src/main/java/org/dockbox/hartshorn/inject/condition/support/ClassCondition.java

@@ -16,15 +16,16 @@
 
 package org.dockbox.hartshorn.inject.condition.support;
 
+import org.dockbox.hartshorn.inject.condition.ReferenceConditionContext;
+import org.dockbox.hartshorn.inject.condition.ConditionResult;
+import org.dockbox.hartshorn.inject.condition.ReferenceCondition;
+import org.dockbox.hartshorn.util.types.ClassFileUtilities;
+import org.dockbox.hartshorn.util.types.TypeUtils;
+
 import java.lang.classfile.Annotation;
 import java.lang.classfile.AnnotationValue;
 import java.lang.classfile.AttributedElement;
 import java.util.List;
-import org.dockbox.hartshorn.inject.condition.ConditionResult;
-import org.dockbox.hartshorn.inject.condition.TypeReferenceCondition;
-import org.dockbox.hartshorn.inject.condition.TypeReferenceConditionContext;
-import org.dockbox.hartshorn.util.types.ClassFileUtilities;
-import org.dockbox.hartshorn.util.types.TypeUtils;
 
 /**
  * A condition that matches when a class is present on the classpath.
@@ -35,10 +36,10 @@
  *
  * @author Guus Lieben
  */
-public class ClassCondition implements TypeReferenceCondition {
+public class ClassCondition implements ReferenceCondition {
 
     @Override
-    public ConditionResult matches(TypeReferenceConditionContext context) {
+    public ConditionResult matches(ReferenceConditionContext context) {
         AttributedElement element = context.element();
         Annotation annotation = ClassFileUtilities.getAnnotation(
                 element,

hartshorn-inject-configurations/src/main/java/org/dockbox/hartshorn/inject/condition/support/RequiresClass.java

@@ -16,14 +16,23 @@
 
 package org.dockbox.hartshorn.inject.condition.support;
 
+import org.dockbox.hartshorn.inject.condition.RequiresReferenceCondition;
+
 import java.lang.annotation.ElementType;
 import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
-import org.dockbox.hartshorn.inject.condition.RequiresReferenceCondition;
 
 /**
- * A condition that requires classes to be present in the classpath.
+ * A condition that requires classes to be present in the classpath. As this condition is evaluated
+ * early during the injection process, it does not require the classes to be loaded by the JVM, and
+ * can therefore be used to conditionally load configurations based on optional dependencies.
+ *
+ * <p><b>Note, for binding methods</b>, take into account that the JVM will have loaded the
+ * enclosing class, as well as the return type and any method references, before evaluating this
+ * condition. As such, this condition is best applied to configuration classes. If used on binding
+ * methods, ensure the return type and references do not depend on the checked classes. For such
+ * cases, use separate conditionally loaded configuration classes.
  *
  * @see ClassCondition
  * 

hartshorn-integration-tests/src/integration-test/java/test/org/dockbox/hartshorn/inject/conditions/ConditionTests.java

@@ -16,10 +16,6 @@
 
 package test.org.dockbox.hartshorn.inject.conditions;
 
-import java.lang.classfile.Annotation;
-import java.lang.classfile.ClassModel;
-import java.lang.classfile.MethodModel;
-import java.util.stream.Stream;
 import org.dockbox.hartshorn.inject.ComponentKey;
 import org.dockbox.hartshorn.inject.annotations.Inject;
 import org.dockbox.hartshorn.inject.binding.BindingHierarchy;
@@ -31,7 +27,7 @@
 import org.dockbox.hartshorn.inject.condition.IntrospectedConditionContext;
 import org.dockbox.hartshorn.inject.condition.ReferenceConditionDeclaration;
 import org.dockbox.hartshorn.inject.condition.RequiresCondition;
-import org.dockbox.hartshorn.inject.condition.TypeReferenceConditionContext;
+import org.dockbox.hartshorn.inject.condition.ReferenceConditionContext;
 import org.dockbox.hartshorn.inject.condition.support.ClassCondition;
 import org.dockbox.hartshorn.inject.condition.support.RequiresClass;
 import org.dockbox.hartshorn.launchpad.ApplicationContext;
@@ -40,7 +36,6 @@
 import org.dockbox.hartshorn.test.annotations.TestComponents;
 import org.dockbox.hartshorn.test.annotations.TestProperties;
 import org.dockbox.hartshorn.test.junit.HartshornIntegrationTest;
-import org.dockbox.hartshorn.util.introspect.scan.ClassReference;
 import org.dockbox.hartshorn.util.introspect.view.MethodView;
 import org.dockbox.hartshorn.util.introspect.view.TypeView;
 import org.dockbox.hartshorn.util.types.ClassFileUtilities;
@@ -49,6 +44,11 @@
 import org.junit.jupiter.params.provider.Arguments;
 import org.junit.jupiter.params.provider.MethodSource;
 
+import java.lang.classfile.Annotation;
+import java.lang.classfile.ClassModel;
+import java.lang.classfile.MethodModel;
+import java.util.stream.Stream;
+
 import static org.assertj.core.api.Assertions.assertThat;
 
 @SuppressWarnings("unused")
@@ -130,10 +130,9 @@ void classConditionOnPresentClass() {
         ).get();
         ReferenceConditionDeclaration declarationForPresent =
             ReferenceConditionDeclaration.createFromMetaAnnotation(annotationForPresent);
-        ConditionContext contextForPresent = new TypeReferenceConditionContext(
+        ConditionContext contextForPresent = new ReferenceConditionContext(
             declarationForPresent,
-            new ClassReference(ConditionTests.class),
-            requiresClass
+                requiresClass
         );
         assertThat(condition.matches(contextForPresent).matches()).isTrue();
     }
@@ -153,10 +152,9 @@ void classConditionOnAbsentClass() {
         ).get();
         ReferenceConditionDeclaration declarationForAbsent =
             ReferenceConditionDeclaration.createFromMetaAnnotation(annotationForAbsent);
-        ConditionContext contextForAbsent = new TypeReferenceConditionContext(
+        ConditionContext contextForAbsent = new ReferenceConditionContext(
             declarationForAbsent,
-            new ClassReference(ConditionTests.class),
-            requiresAbsentClass
+                requiresAbsentClass
         );
         assertThat(condition.matches(contextForAbsent).matches()).isFalse();
     }

hartshorn-introspect-reflection/src/main/java/org/dockbox/hartshorn/util/introspect/reflect/ReflectionExecutableParametersIntrospector.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2019-2025 the original author or authors.
+ * Copyright 2019-2026 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -147,4 +147,9 @@ private boolean matches(
         }
         return true;
     }
+
+    @Override
+    public int indexOf(ParameterView<?> parameter) {
+        return this.all().indexOf(parameter);
+    }
 }