feat(dependency-injection): lifecycle — @PreDestroy, custom scopes, scope violation detection (#33)

Author: deer

.gitignore

@@ -5,3 +5,5 @@ target/
 # IntelliJ IDEA
 .idea/
 *.iml
+
+.build/

dependency-injection/src/main/java/build/codemodel/injection/Context.java

@@ -50,7 +50,7 @@
  * @since Oct-2024
  */
 public interface Context
-    extends Injector, Binder {
+    extends Injector, Binder, AutoCloseable {
 
     /**
      * Creates a {@link BindingBuilder} pre-loaded with the specified instance value, enabling
@@ -142,6 +142,14 @@ <T> T create(Dependency dependency)
      */
     Context initializeEagerSingletons();
 
+    /**
+     * Closes this {@link Context}, invoking any {@link PreDestroy} lifecycle methods on
+     * instantiated singleton instances in reverse dependency order (dependents are destroyed
+     * before their dependencies).
+     */
+    @Override
+    void close();
+
     /**
      * Creates a new {@link Context} with the this {@link Context} as a parent solver.
      *

dependency-injection/src/main/java/build/codemodel/injection/CustomScopedClassBinding.java

@@ -0,0 +1,108 @@
+package build.codemodel.injection;
+
+/*-
+ * #%L
+ * Dependency Injection
+ * %%
+ * Copyright (C) 2026 Workday, Inc.
+ * %%
+ * 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.
+ * #L%
+ */
+
+import java.lang.annotation.Annotation;
+import java.util.Objects;
+
+/**
+ * A {@link ClassBinding} whose instance lifecycle is managed by a custom {@link Scope} (i.e. any
+ * scope other than {@link jakarta.inject.Singleton} or prototype). Wraps the {@link ValueBinding}
+ * returned by {@link Scope#scope} and exposes the concrete class and scope annotation for
+ * introspection by {@link Context#validate()} and {@link BindingGraphContributor}.
+ *
+ * <p>Used by {@link InjectionContext} when {@link InjectionFramework#findScopeEntry} matches a
+ * registered custom scope on the concrete class. Instances are resolved via the delegate, which
+ * applies the scope's caching or sharing strategy.
+ *
+ * @param <T> the type produced by this binding
+ * @author reed.vonredwitz
+ * @see Scope
+ * @see ScopeAnnotation
+ * @since Apr-2026
+ */
+class CustomScopedClassBinding<T>
+    extends AbstractBinding<T>
+    implements ClassBinding<T>, ValueBinding<T> {
+
+    /**
+     * The concrete class to be instantiated by the scope.
+     */
+    private final Class<? extends T> concreteClass;
+
+    /**
+     * The scope annotation that governs this binding's lifecycle.
+     */
+    private final Class<? extends Annotation> scopeAnnotation;
+
+    /**
+     * The scoped {@link ValueBinding} returned by {@link Scope#scope}. Applies the scope's
+     * caching or sharing strategy on each {@link #value()} call.
+     */
+    private final ValueBinding<T> delegate;
+
+    /**
+     * Constructs a {@link CustomScopedClassBinding}.
+     *
+     * @param dependency      the {@link Dependency} this binding satisfies
+     * @param concreteClass   the concrete class whose instances the scope manages
+     * @param scopeAnnotation the scope annotation that governs the lifecycle
+     * @param scopedBinding   the {@link Binding} returned by {@link Scope#scope}; must implement
+     *                        {@link ValueBinding}
+     * @throws InjectionException if {@code scopedBinding} does not implement {@link ValueBinding}
+     */
+    @SuppressWarnings("unchecked")
+    CustomScopedClassBinding(final Dependency dependency,
+                             final Class<? extends T> concreteClass,
+                             final Class<? extends Annotation> scopeAnnotation,
+                             final Binding<?> scopedBinding) {
+
+        super(dependency);
+        this.concreteClass = Objects.requireNonNull(concreteClass, "The concrete class must not be null");
+        this.scopeAnnotation = Objects.requireNonNull(scopeAnnotation, "The scope annotation must not be null");
+
+        if (!(scopedBinding instanceof ValueBinding)) {
+            throw new InjectionException(
+                "Scope.scope() must return a ValueBinding for dependency [" + dependency + "]; "
+                    + "got: " + (scopedBinding == null ? "null" : scopedBinding.getClass().getName()));
+        }
+        this.delegate = (ValueBinding<T>) scopedBinding;
+    }
+
+    @Override
+    public Class<? extends T> concreteClass() {
+        return this.concreteClass;
+    }
+
+    /**
+     * The scope annotation that governs this binding's instance lifecycle.
+     *
+     * @return the scope annotation class
+     */
+    Class<? extends Annotation> scopeAnnotation() {
+        return this.scopeAnnotation;
+    }
+
+    @Override
+    public T value() {
+        return this.delegate.value();
+    }
+}

dependency-injection/src/main/java/build/codemodel/injection/InjectableDescriptor.java

@@ -9,9 +9,9 @@
  * 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.
@@ -54,16 +54,23 @@ public class InjectableDescriptor
      */
     private final ArrayList<MethodDescriptor> postInjectionMethods;
 
+    /**
+     * The {@link PreDestroy} {@link MethodDescriptor}s.
+     */
+    private final ArrayList<MethodDescriptor> preDestroyMethods;
+
     /**
      * Constructs a new {@link InjectableDescriptor} for the specified {@link JDKTypeDescriptor}.
      *
      * @param typeDescriptor       the {@link JDKTypeDescriptor}
      * @param injectionPoints      the {@link InjectionPoint}s
      * @param postInjectionMethods the {@link PostInject} annotated {@link MethodDescriptor}s
+     * @param preDestroyMethods    the {@link PreDestroy} annotated {@link MethodDescriptor}s
      */
     private InjectableDescriptor(final JDKTypeDescriptor typeDescriptor,
                                  final Stream<InjectionPoint> injectionPoints,
-                                 final Stream<MethodDescriptor> postInjectionMethods) {
+                                 final Stream<MethodDescriptor> postInjectionMethods,
+                                 final Stream<MethodDescriptor> preDestroyMethods) {
 
         this.typeDescriptor = Objects.requireNonNull(typeDescriptor, "The TypeDescriptor must not be null");
         this.injectionPoints = injectionPoints == null
@@ -72,6 +79,9 @@ private InjectableDescriptor(final JDKTypeDescriptor typeDescriptor,
         this.postInjectionMethods = postInjectionMethods == null
             ? new ArrayList<>()
             : postInjectionMethods.collect(Collectors.toCollection(ArrayList::new));
+        this.preDestroyMethods = preDestroyMethods == null
+            ? new ArrayList<>()
+            : preDestroyMethods.collect(Collectors.toCollection(ArrayList::new));
     }
 
     /**
@@ -110,17 +120,28 @@ public Stream<MethodDescriptor> postInjectionMethods() {
         return this.postInjectionMethods.stream();
     }
 
+    /**
+     * Obtains the {@link PreDestroy} annotated {@link MethodDescriptor}s defined for the {@link JDKTypeDescriptor}.
+     *
+     * @return the {@link Stream} of {@link PreDestroy} {@link MethodDescriptor}s
+     */
+    public Stream<MethodDescriptor> preDestroyMethods() {
+        return this.preDestroyMethods.stream();
+    }
+
     /**
      * Creates a new {@link InjectableDescriptor} for the specified {@link JDKTypeDescriptor}.
      *
      * @param typeDescriptor       the {@link JDKTypeDescriptor}
      * @param injectionPoints      the {@link InjectionPoint}s
      * @param postInjectionMethods the {@link PostInject} annotated {@link MethodDescriptor}s
+     * @param preDestroyMethods    the {@link PreDestroy} annotated {@link MethodDescriptor}s
      */
     public static InjectableDescriptor of(final JDKTypeDescriptor typeDescriptor,
                                           final Stream<InjectionPoint> injectionPoints,
-                                          final Stream<MethodDescriptor> postInjectionMethods) {
+                                          final Stream<MethodDescriptor> postInjectionMethods,
+                                          final Stream<MethodDescriptor> preDestroyMethods) {
 
-        return new InjectableDescriptor(typeDescriptor, injectionPoints, postInjectionMethods);
+        return new InjectableDescriptor(typeDescriptor, injectionPoints, postInjectionMethods, preDestroyMethods);
     }
 }

dependency-injection/src/main/java/build/codemodel/injection/InjectionContext.java

@@ -33,6 +33,7 @@
 import java.lang.reflect.InvocationTargetException;
 import java.util.ArrayList;
 import java.util.Collection;
+import java.util.Collections;
 import java.util.IdentityHashMap;
 import java.util.LinkedHashSet;
 import java.util.List;
@@ -134,6 +135,7 @@ public Binding<T> to(final T value) {
             }
 
             @Override
+            @SuppressWarnings("unchecked")
             public Binding<T> to(final Class<? extends T> concreteClass) {
                 Objects.requireNonNull(concreteClass, "The Binding Value Class must not be null");
 
@@ -145,6 +147,16 @@ public Binding<T> to(final Class<? extends T> concreteClass) {
                     .orElseThrow(() -> new IllegalArgumentException(
                         "Could not resolve a TypeDescriptor for " + concreteClass));
 
+                // check for a registered custom scope annotation on the concrete class
+                final var scopeEntry = this.injectionFramework.findScopeEntry(typeDescriptor).orElse(null);
+                if (scopeEntry != null) {
+                    final ValueBinding<T> factory = new SupplierBinding<>(
+                        dependency, () -> (T) InjectionContext.this.createUnscoped(concreteClass));
+                    final Binding<?> scoped = scopeEntry.getValue().scope(factory);
+                    return addBinding(dependency,
+                        new CustomScopedClassBinding<>(dependency, concreteClass, scopeEntry.getKey(), scoped));
+                }
+
                 return addBinding(dependency, this.injectionFramework.isSingleton(typeDescriptor)
                     ? new LazySingletonClassBinding<>(dependency, concreteClass)
                     : new NonSingletonClassBinding<T>(dependency, concreteClass));
@@ -462,13 +474,17 @@ public Context validate() {
                     + " required by [" + edge.from() + "]");
             }
 
-            // Scope violation: @Singleton depends on NonSingletonClassBinding (prototype)
+            // Scope violation: @Singleton depends on a narrower-scoped binding
             final var fromBinding = this.bindingsByDependency.get(edge.from());
             final var toBinding = this.bindingsByDependency.get(dep);
-            if (fromBinding instanceof LazySingletonClassBinding
-                && toBinding instanceof NonSingletonClassBinding) {
-                problems.add("Scope violation: singleton [" + edge.from()
-                    + "] depends on prototype-scoped [" + dep + "]");
+            if (fromBinding instanceof LazySingletonClassBinding) {
+                if (toBinding instanceof NonSingletonClassBinding) {
+                    problems.add("Scope violation: singleton [" + edge.from()
+                        + "] depends on prototype-scoped [" + dep + "]");
+                } else if (toBinding instanceof CustomScopedClassBinding<?> csb) {
+                    problems.add("Scope violation: singleton [" + edge.from()
+                        + "] depends on @" + csb.scopeAnnotation().getSimpleName() + "-scoped [" + dep + "]");
+                }
             }
         });
 
@@ -540,6 +556,90 @@ public Context initializeEagerSingletons() {
         return this;
     }
 
+    @Override
+    @SuppressWarnings("unchecked")
+    public void close() {
+        // Collect all instantiated singleton bindings
+        final var instantiatedSingletons = this.bindingsByDependency.values().stream()
+            .filter(LazySingletonClassBinding.class::isInstance)
+            .map(b -> (LazySingletonClassBinding<Object>) b)
+            .filter(b -> b.value().optional().isPresent())
+            .collect(Collectors.toList());
+
+        if (instantiatedSingletons.isEmpty()) {
+            return;
+        }
+
+        // Build a dependency graph over instantiated singletons only
+        final var singletonDeps = instantiatedSingletons.stream()
+            .map(Binding::dependency)
+            .collect(Collectors.toSet());
+
+        final var graphBuilder = Graph.<Dependency>directed();
+        instantiatedSingletons.forEach(b -> {
+            final var bindingDep = b.dependency();
+            graphBuilder.addVertex(bindingDep);
+            this.injectionFramework.getInjectableDescriptor(b.concreteClass())
+                .injectionPoints()
+                .flatMap(InjectionPoint::dependencies)
+                .filter(singletonDeps::contains)
+                .forEach(dep -> graphBuilder.addEdge(bindingDep, dep));
+        });
+
+        final var graph = graphBuilder.build();
+
+        // topologicalSort returns [leaf-first, root-last]; reverse for destruction (dependents first)
+        final var destroyOrder = new ArrayList<>(Graphs.topologicalSort(graph));
+        Collections.reverse(destroyOrder);
+
+        // Index bindings by dependency for lookup during destruction
+        final var depToBinding = instantiatedSingletons.stream()
+            .collect(Collectors.toMap(Binding::dependency, b -> b));
+
+        // Invoke @PreDestroy methods on each singleton in destruction order
+        destroyOrder.forEach(dep -> {
+            final var binding = depToBinding.get(dep);
+            if (binding == null) {
+                return;
+            }
+            final var instance = binding.value().optional().orElse(null);
+            if (instance == null) {
+                return;
+            }
+            this.injectionFramework.getInjectableDescriptor(binding.concreteClass())
+                .preDestroyMethods()
+                .map(md -> md.getTrait(MethodType.class).orElse(null))
+                .filter(Objects::nonNull)
+                .map(MethodType::method)
+                .forEach(method -> {
+                    try {
+                        method.setAccessible(true);
+                        method.invoke(instance);
+                    } catch (final IllegalAccessException | InvocationTargetException e) {
+                        throw new InjectionException(
+                            "Invoking @PreDestroy method " + method + " on " + instance.getClass(), e);
+                    }
+                });
+        });
+    }
+
+    /**
+     * Creates an instance of the specified class bypassing any registered {@link Binding}s by
+     * directly instantiating via {@link ResolvableClass}. Used by scope implementations to produce
+     * a fresh unscoped instance without recursing into the scoped binding.
+     *
+     * @param <T>           the type
+     * @param concreteClass the class to instantiate
+     * @return a new injected instance
+     */
+    @SuppressWarnings("unchecked")
+    private <T> T createUnscoped(final Class<? extends T> concreteClass) {
+        final var codeModel = this.injectionFramework.codeModel();
+        final var typeUsage = codeModel.getTypeUsage(concreteClass);
+        final var dependency = IndependentDependency.of(typeUsage, this.injectionFramework::getQualifierAnnotationTypes);
+        return (T) new ResolvableClass<>(Optional.empty(), dependency, concreteClass).resolve();
+    }
+
     @Override
     public Context newContext() {
         return this.injectionFramework.newContext(this.resolver());