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 Detail

      • 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

      • 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

      • 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

      • 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

      • 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

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

      • 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