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

    • 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

    • propertyPlugin

      void propertyPlugin(PropertyRequiresPlugin propertyRequiresPlugin)
      Set the PropertyPlugin used for this scope. This is serviceloaded automatically of not set
      Parameters:
      propertyRequiresPlugin - The plugin for conditions based on properties

    • propertyPlugin

      PropertyRequiresPlugin propertyPlugin()
      Return the PropertyPlugin used for this scope. This is useful for plugins that want to use the scopes wiring properties.

    • 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.

      If using this to provide a missing bean into the scope, Avaje will fail compilation unless it detects an @InjectModule(requires) including the missing class, or it detects a @Nullable annotation where the bean is wired. 

      
 // 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

    • bean

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

      If using this to provide a missing bean into the scope, Avaje will fail compilation unless it detects an @InjectModule(requires) including the missing class, or it detects a @Nullable annotation where the bean is wired. 

      
 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

    • bean

      <D> BeanScopeBuilder bean(String name, Class<D> type, D bean)
      Add a supplied bean instance with the given name and injection type.

      If using this to provide a missing bean into the scope, Avaje will fail compilation unless it detects an @InjectModule(requires) including the missing class, or it detects a @Nullable annotation where the bean is wired.

      Parameters:
      name - The name qualifier
      type - The dependency injection type this bean is target for
      bean - The supplied bean instance to use for injection

    • bean

      <D> BeanScopeBuilder bean(String name, Type type, D bean)
      Add a supplied bean instance with the given name and generic type.

      If using this to provide a missing bean into the scope, Avaje will fail compilation unless it detects an @InjectModule(requires) including the missing class, or it detects a @Nullable annotation where the bean is wired.

      Parameters:
      name - The name qualifier
      type - The dependency injection type this bean is target for
      bean - The supplied bean instance to use for injection

    • bean

      <D> BeanScopeBuilder bean(Type type, D bean)
      Add a supplied bean instance with a generic type.

      If using this to provide a missing bean into the scope, Avaje will fail compilation unless it detects an @InjectModule(requires) including the missing class, or it detects a @Nullable annotation where the bean is wired.

      Parameters:
      type - The dependency injection type this bean is target for
      bean - The supplied bean instance to use for injection

    • profiles

      BeanScopeBuilder profiles(String... profiles)
      Set the explicit profiles to use when building the scope.

      If profiles are not set explicitly here they are read from the properties plugin.

    • provideDefault

      default <D> BeanScopeBuilder provideDefault(Type type, Supplier<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, Supplier<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.

    • addPostConstruct

      BeanScopeBuilder addPostConstruct(Runnable postConstructHook)
      Adds hooks that will execute after this scope is built.

    • addPostConstruct

      BeanScopeBuilder addPostConstruct(Consumer<BeanScope> postConstructHook)
      Adds hook that will execute after this scope is built.

    • addPreDestroy

      BeanScopeBuilder addPreDestroy(AutoCloseable preDestroyHook)
      Add hook that will execute before this scope is destroyed.

    • addPreDestroy

      BeanScopeBuilder addPreDestroy(AutoCloseable preDestroyHook, int priority)
      Add hook with a priority that will execute before this scope is destroyed.

      Specify the priority of the destroy method to control its execution order relative to other destroy methods.

      Low values for priority execute earlier than high values. All destroy methods without any explicit priority are given a value of 1000.

    • 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

    • 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.

    • 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