Module io.avaje.inject
Package io.avaje.inject

Interface BeanScopeBuilder

All Known Subinterfaces:
BeanScopeBuilder.ForTesting
@NonNullApi public interface BeanScopeBuilder
Build a bean scope with options for shutdown hook and supplying external dependencies.

We can provide external dependencies that are then used in wiring the components. 



   // external dependencies
   Pump pump = ...

   BeanScope scope = BeanScope.builder()
     .bean(pump)
     .build();

   CoffeeMaker coffeeMaker = scope.get(CoffeeMaker.class);
   coffeeMaker.makeIt();

  • Method Details

    • shutdownHook

      BeanScopeBuilder shutdownHook(boolean shutdownHook)
      Create the bean scope registering a shutdown hook (defaults to false, no shutdown hook).

      With withShutdownHook(true) a shutdown hook will be registered with the Runtime and executed when the JVM initiates a shutdown. This then will run the preDestroy lifecycle methods. 

      

   // automatically closed via try with resources

   BeanScope scope = BeanScope.builder()
     .shutdownHook(true)
     .build());

   // on JVM shutdown the preDestroy lifecycle methods are executed
      Returns:
      This BeanScopeBuilder

    • withShutdownHook

      @Deprecated default BeanScopeBuilder withShutdownHook(boolean shutdownHook)
      Deprecated.
      Deprecated - migrate to shutdownHook().

    • modules

      BeanScopeBuilder modules(Module... modules)
      Specify the modules to include in dependency injection.

      Only beans related to the module are included in the BeanScope that is built.

      When we do not explicitly specify modules then all modules that are not "custom scoped" are found and used via service loading. 

      

   BeanScope scope = BeanScope.builder()
     .modules(new CustomModule())
     .build());

   CoffeeMaker coffeeMaker = scope.get(CoffeeMaker.class);
   coffeeMaker.makeIt();
      Parameters:
      modules - The modules that we want to include in dependency injection.
      Returns:
      This BeanScopeBuilder

    • withModules

      @Deprecated default BeanScopeBuilder withModules(Module... modules)
      Deprecated.
      Deprecated - migrate to modules()

    • beans

      BeanScopeBuilder beans(Object... beans)
      Supply a bean to the scope that will be used instead of any similar bean in the scope.

      This is typically expected to be used in tests and the bean supplied is typically a test double or mock. 

      

   // external dependencies
   Pump pump = ...
   Grinder grinder = ...

   BeanScope scope = BeanScope.builder()
     .beans(pump, grinder)
     .build();

   CoffeeMaker coffeeMaker = scope.get(CoffeeMaker.class);
   coffeeMaker.makeIt();
      Parameters:
      beans - Externally provided beans used when injecting a dependency for the bean or the interface(s) it implements
      Returns:
      This BeanScopeBuilder

    • withBeans

      @Deprecated default BeanScopeBuilder withBeans(Object... beans)
      Deprecated.
      Deprecated - migrate to beans().

    • bean

      <D> BeanScopeBuilder bean(Class<D> type, D bean)
      Add a supplied bean instance with the given injection type (typically an interface type). 
      

   Pump externalDependency = ...

   try (BeanScope scope = BeanScope.builder()
     .bean(Pump.class, externalDependency)
     .build()) {

     CoffeeMaker coffeeMaker = scope.get(CoffeeMaker.class);
     coffeeMaker.makeIt();

     Pump pump = scope.get(Pump.class);
     assertThat(pump).isSameAs(externalDependency);
   }
      Parameters:
      type - The dependency injection type this bean is target for
      bean - The supplied bean instance to use for injection

    • withBean

      @Deprecated default <D> BeanScopeBuilder withBean(Class<D> type, D bean)
      Deprecated.
      Deprecated - migrate to bean().

    • bean

      <D> BeanScopeBuilder bean(String name, Class<D> type, D bean)
      Add a supplied bean instance with the given name and injection type.
      Parameters:
      name - The name qualifier
      type - The dependency injection type this bean is target for
      bean - The supplied bean instance to use for injection

    • withBean

      @Deprecated default <D> BeanScopeBuilder withBean(String name, Class<D> type, D bean)
      Deprecated.
      Deprecated - migrate to bean().

    • bean

      <D> BeanScopeBuilder bean(String name, Type type, D bean)
      Add a supplied bean instance with the given name and generic type.
      Parameters:
      name - The name qualifier
      type - The dependency injection type this bean is target for
      bean - The supplied bean instance to use for injection

    • withBean

      @Deprecated default <D> BeanScopeBuilder withBean(String name, Type type, D bean)
      Deprecated.
      Deprecated - migrate to bean().

    • bean

      <D> BeanScopeBuilder bean(Type type, D bean)
      Add a supplied bean instance with a generic type.
      Parameters:
      type - The dependency injection type this bean is target for
      bean - The supplied bean instance to use for injection

    • provideDefault

      default <D> BeanScopeBuilder provideDefault(Type type, jakarta.inject.Provider<D> provider)
      Add a supplied bean provider that acts as a default fallback for a dependency.

      This provider is only called if nothing else provides the dependency. It effectively uses `@Secondary` priority.

      Parameters:
      type - The type of the dependency
      provider - The provider of the dependency.

    • provideDefault

      <D> BeanScopeBuilder provideDefault(@Nullable String name, Type type, jakarta.inject.Provider<D> provider)
      Add a supplied bean provider that acts as a default fallback for a dependency.

      This provider is only called if nothing else provides the dependency. It effectively uses `@Secondary` priority.

      Parameters:
      name - The name qualifier
      type - The type of the dependency
      provider - The provider of the dependency.

    • withBean

      @Deprecated default <D> BeanScopeBuilder withBean(Type type, D bean)
      Deprecated.
      Deprecated - migrate to bean().

    • classLoader

      BeanScopeBuilder classLoader(ClassLoader classLoader)
      Set the ClassLoader to use when loading modules.
      Parameters:
      classLoader - The ClassLoader to use

    • parent

      BeanScopeBuilder parent(BeanScope parent)
      Use the given BeanScope as the parent. This becomes an additional source of beans that can be wired and accessed in this scope.
      Parameters:
      parent - The BeanScope that acts as the parent

    • withParent

      @Deprecated default BeanScopeBuilder withParent(BeanScope parent)
      Deprecated.
      Deprecated - migrate to parent().

    • parent

      BeanScopeBuilder parent(BeanScope parent, boolean parentOverride)
      Use the given BeanScope as the parent additionally specifying if beans added will effectively override beans that exist in the parent scope.

      By default, child scopes will override a bean that exists in a parent scope. For testing purposes, parentOverride=false is used such that bean provided in parent test scopes are used (unless we mock() or spy() them).

      See TestBeanScope in avaje-inject-test which has helper methods to build BeanScopes for testing with the "Global test scope" as a parent scope.

      Parameters:
      parent - The BeanScope that acts as the parent
      parentOverride - When false do not add beans that already exist on the parent. When true add beans regardless of whether they exist in the parent scope.

    • withParent

      @Deprecated default BeanScopeBuilder withParent(BeanScope parent, boolean parentOverride)
      Deprecated.
      Deprecated - migrate to parent().

    • forTesting

      BeanScopeBuilder.ForTesting forTesting()
      Extend the builder to support testing using mockito with withMock() and withSpy() methods.
      Returns:
      The builder with extra testing support for mockito mocks and spies

    • build

      BeanScope build()
      Build and return the bean scope.

      The BeanScope is effectively immutable in that all components are created and all PostConstruct lifecycle methods have been invoked.

      The beanScope effectively contains eager singletons.

      Returns:
      The BeanScope