#258 - ENH: Add Plugin API for 'default providers' and BeanScopeBuilder.provideDefault() methods

Author: rbygrave

inject-generator/src/main/java/io/avaje/inject/generator/MetaDataOrdering.java

@@ -29,9 +29,9 @@ final class MetaDataOrdering {
         queue.add(metaData);
       }
       // register into map keyed by provider
-      providers.computeIfAbsent(metaData.getType(), s -> new ProviderList()).add(metaData);
+      providerAdd(metaData.getType()).add(metaData);
       for (String provide : metaData.getProvides()) {
-        providers.computeIfAbsent(provide, s -> new ProviderList()).add(metaData);
+        providerAdd(provide).add(metaData);
       }
     }
     externallyRequiredDependencies();
@@ -42,8 +42,15 @@ final class MetaDataOrdering {
    */
   private void externallyRequiredDependencies() {
     for (String requireType : scopeInfo.requires()) {
-      providers.computeIfAbsent(requireType, s -> new ProviderList());
+      providerAdd(requireType);
     }
+    for (String requireType : scopeInfo.pluginProvided()) {
+      providerAdd(requireType);
+    }
+  }
+
+  private ProviderList providerAdd(String requireType) {
+    return providers.computeIfAbsent(requireType, s -> new ProviderList());
   }
 
   int processQueue() {

inject-generator/src/main/java/io/avaje/inject/generator/Processor.java

@@ -4,6 +4,7 @@
 import io.avaje.inject.Factory;
 import io.avaje.inject.InjectModule;
 import io.avaje.inject.Prototype;
+import io.avaje.inject.spi.Plugin;
 import io.avaje.inject.spi.Proxy;
 import jakarta.inject.Scope;
 import jakarta.inject.Singleton;
@@ -18,6 +19,7 @@
 import javax.lang.model.element.TypeElement;
 import javax.lang.model.util.Elements;
 import java.util.LinkedHashSet;
+import java.util.ServiceLoader;
 import java.util.Set;
 
 public final class Processor extends AbstractProcessor {
@@ -43,6 +45,19 @@ public synchronized void init(ProcessingEnvironment processingEnv) {
     this.elementUtils = processingEnv.getElementUtils();
     this.allScopes = new AllScopes(context);
     this.defaultScope = allScopes.defaultScope();
+    registerPluginProvidedTypes();
+  }
+
+  /**
+   * Register types provided by the plugin so no compiler error when we have a dependency
+   * on these types and the only thing providing them is the plugin.
+   */
+  private void registerPluginProvidedTypes() {
+    for (Plugin plugin : ServiceLoader.load(Plugin.class)) {
+      for (Class<?> provide : plugin.provides()) {
+        defaultScope.pluginProvided(provide.getCanonicalName());
+      }
+    }
   }
 
   @Override

inject-generator/src/main/java/io/avaje/inject/generator/ScopeInfo.java

@@ -45,6 +45,7 @@ String type() {
   private final List<BeanReader> beanReaders = new ArrayList<>();
   private final Set<String> readBeans = new HashSet<>();
   private final ProcessingContext context;
+  private final Set<String> pluginProvided = new HashSet<>();
   private final Set<String> requires = new LinkedHashSet<>();
   private final Set<String> provides = new LinkedHashSet<>();
   private final Set<String> requiresPackages = new LinkedHashSet<>();
@@ -90,6 +91,10 @@ public String toString() {
       '}';
   }
 
+  void pluginProvided(String pluginProvides) {
+    pluginProvided.add(pluginProvides);
+  }
+
   boolean includeSingleton() {
     return !ignoreSingleton;
   }
@@ -172,6 +177,10 @@ Set<String> requires() {
     return requires;
   }
 
+  Set<String> pluginProvided() {
+    return pluginProvided;
+  }
+
   void writeBeanHelpers() {
     for (BeanReader beanReader : beanReaders) {
       try {
@@ -453,7 +462,7 @@ private boolean providesDependencyRecursive(String dependency) {
    * Return true if this module provides the dependency (non-recursive, local only).
    */
   boolean providesDependencyLocally(String dependency) {
-    if (requires.contains(dependency)) {
+    if (requires.contains(dependency) || pluginProvided.contains(dependency)) {
       return true;
     }
     for (MetaData meta : metaData.values()) {

inject-generator/src/main/java/module-info.java

@@ -3,5 +3,7 @@
   requires java.compiler;
   requires io.avaje.inject;
 
+  uses io.avaje.inject.spi.Plugin;
+
   provides javax.annotation.processing.Processor with io.avaje.inject.generator.Processor;
 }

inject/src/main/java/io/avaje/inject/BeanScopeBuilder.java

@@ -2,6 +2,8 @@
 
 import io.avaje.inject.spi.Module;
 import io.avaje.lang.NonNullApi;
+import io.avaje.lang.Nullable;
+import jakarta.inject.Provider;
 
 import java.lang.reflect.Type;
 import java.util.function.Consumer;
@@ -204,6 +206,31 @@ default <D> BeanScopeBuilder withBean(String name, Type type, D bean) {
    */
   <D> BeanScopeBuilder bean(Type type, D bean);
 
+  /**
+   * Add a supplied bean provider that acts as a default fallback for a dependency.
+   * <p>
+   * This provider is only called if nothing else provides the dependency. It effectively
+   * uses `@Secondary` priority.
+   *
+   * @param type     The type of the dependency
+   * @param provider The provider of the dependency.
+   */
+  default <D> BeanScopeBuilder provideDefault(Type type, Provider<D> provider) {
+    return provideDefault(null, type, provider);
+  }
+
+  /**
+   * Add a supplied bean provider that acts as a default fallback for a dependency.
+   * <p>
+   * This provider is only called if nothing else provides the dependency. It effectively
+   * uses `@Secondary` priority.
+   *
+   * @param name     The name qualifier
+   * @param type     The type of the dependency
+   * @param provider The provider of the dependency.
+   */
+  <D> BeanScopeBuilder provideDefault(@Nullable String name, Type type, Provider<D> provider);
+
   /**
    * Deprecated - migrate to bean().
    */
@@ -314,7 +341,7 @@ interface ForTesting extends BeanScopeBuilder {
      */
     @Deprecated
     default BeanScopeBuilder.ForTesting withMock(Class<?> type) {
-      return  mock(type);
+      return mock(type);
     }
 
     /**

inject/src/main/java/io/avaje/inject/DBeanScopeBuilder.java

@@ -1,12 +1,11 @@
 package io.avaje.inject;
 
 import io.avaje.applog.AppLog;
-import io.avaje.inject.spi.Builder;
-import io.avaje.inject.spi.EnrichBean;
+import io.avaje.inject.spi.*;
 import io.avaje.inject.spi.Module;
-import io.avaje.inject.spi.SuppliedBean;
 import io.avaje.lang.NonNullApi;
 import io.avaje.lang.Nullable;
+import jakarta.inject.Provider;
 
 import java.lang.System.Logger.Level;
 import java.lang.reflect.Type;
@@ -17,11 +16,10 @@
  * Build a bean scope with options for shutdown hook and supplying test doubles.
  */
 @NonNullApi
-class DBeanScopeBuilder implements BeanScopeBuilder.ForTesting {
+final class DBeanScopeBuilder implements BeanScopeBuilder.ForTesting {
 
   private static final System.Logger log = AppLog.getLogger("io.avaje.inject");
 
-  @SuppressWarnings("rawtypes")
   private final List<SuppliedBean> suppliedBeans = new ArrayList<>();
   @SuppressWarnings("rawtypes")
   private final List<EnrichBean> enrichBeans = new ArrayList<>();
@@ -84,6 +82,12 @@ public <D> BeanScopeBuilder bean(@Nullable String name, Type type, D bean) {
     return this;
   }
 
+  @Override
+  public <D> BeanScopeBuilder provideDefault(String name, Type type, Provider<D> provider) {
+    suppliedBeans.add(SuppliedBean.secondary(name, type, provider));
+    return this;
+  }
+
   @Override
   public BeanScopeBuilder classLoader(ClassLoader classLoader) {
     this.classLoader = classLoader;
@@ -143,10 +147,12 @@ private <D> BeanScopeBuilder.ForTesting spy(Class<D> type, @Nullable String name
 
   @Override
   public BeanScope build() {
+    // load and apply plugins first
+    var loader = classLoader != null ? classLoader : Thread.currentThread().getContextClassLoader();
+    ServiceLoader.load(Plugin.class, loader).forEach(plugin -> plugin.apply(this));
     // sort factories by dependsOn
     FactoryOrder factoryOrder = new FactoryOrder(parent, includeModules, !suppliedBeans.isEmpty());
     if (factoryOrder.isEmpty()) {
-      var loader = classLoader != null ? classLoader : Thread.currentThread().getContextClassLoader();
       ServiceLoader.load(Module.class, loader).forEach(factoryOrder::add);
     }
 

inject/src/main/java/io/avaje/inject/spi/DBeanMap.java

@@ -51,7 +51,7 @@ void add(List<SuppliedBean> suppliedBeans) {
 
   private void addSuppliedBean(SuppliedBean supplied) {
     Type suppliedType = supplied.type();
-    DContextEntryBean entryBean = DContextEntryBean.of(supplied.source(), supplied.name(), supplied.priority());
+    DContextEntryBean entryBean = DContextEntryBean.supplied(supplied.source(), supplied.name(), supplied.priority());
     beans.computeIfAbsent(suppliedType.getTypeName(), s -> new DContextEntry()).add(entryBean);
     for (Class<?> anInterface : supplied.interfaces()) {
       beans.computeIfAbsent(anInterface.getTypeName(), s -> new DContextEntry()).add(entryBean);

inject/src/main/java/io/avaje/inject/spi/DContextEntryBean.java

@@ -12,10 +12,6 @@ class DContextEntryBean {
 
   /**
    * Create taking into account if it is a Provider or the bean itself.
-   *
-   * @param source The bean itself or provider of the bean
-   * @param name The optional name for the bean
-   * @param flag The flag for primary, secondary or normal
    */
   static DContextEntryBean of(Object source, String name, int flag) {
     if (source instanceof Provider) {
@@ -25,6 +21,17 @@ static DContextEntryBean of(Object source, String name, int flag) {
     }
   }
 
+  /**
+   * Create an entry with supplied Providers using a 'Once' / 'one instance' provider.
+   */
+  static DContextEntryBean supplied(Object source, String name, int flag) {
+    if (source instanceof Provider) {
+      return new OnceProvider((Provider<?>)source, name, flag);
+    } else {
+      return new DContextEntryBean(source, name, flag);
+    }
+  }
+
   static DContextEntryBean provider(boolean prototype, Provider<?> provider, String name, int flag) {
     return prototype ? new ProtoProvider(provider, name, flag) : new OnceProvider(provider, name, flag);
   }

inject/src/main/java/io/avaje/inject/spi/Plugin.java

@@ -0,0 +1,24 @@
+package io.avaje.inject.spi;
+
+import io.avaje.inject.BeanScopeBuilder;
+import jakarta.inject.Provider;
+
+import java.lang.reflect.Type;
+
+/**
+ * A Plugin that can be applied when creating a bean scope.
+ * <p>
+ * Typically, a plugin might provide a default dependency via {@link BeanScopeBuilder#provideDefault(Type, Provider)}.
+ */
+public interface Plugin {
+
+  /**
+   * Return the classes that the plugin provides.
+   */
+  Class<?>[] provides();
+
+  /**
+   * Apply the plugin to the scope builder.
+   */
+  void apply(BeanScopeBuilder builder);
+}

inject/src/main/java/io/avaje/inject/spi/SuppliedBean.java

@@ -50,6 +50,14 @@ public static SuppliedBean ofType(String name, Type type, Object source) {
     return new SuppliedBean(BeanEntry.SUPPLIED, name, type, source);
   }
 
+  /**
+   * Create a supplied bean with SECONDARY priority as a default fallback dependency that is
+   * only used when no other matching one is provided.
+   */
+  public static SuppliedBean secondary(String name, Type type, Object source) {
+    return new SuppliedBean(BeanEntry.SECONDARY, name, type, source);
+  }
+
   private SuppliedBean(int priority, String name, Type type, Object source) {
     this.priority = priority;
     this.name = name;

inject/src/main/java/module-info.java

@@ -10,5 +10,6 @@
   requires static org.mockito;
 
   uses io.avaje.inject.spi.Module;
+  uses io.avaje.inject.spi.Plugin;
 
 }