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

Interface BeanScope

  • All Superinterfaces:
    AutoCloseable
    @NonNullApi
public interface BeanScope
extends AutoCloseable
    Holds beans created by dependency injection.

    The beans have singleton scope, support lifecycle methods for postConstruct and preDestroy and are created (wired) via dependency injection.

    Create a BeanScope

    We can programmatically create a BeanScope via BeanScope.builder(). 

    

   // create a BeanScope ...

   try (BeanScope scope = BeanScope.builder()
     .build()) {

     CoffeeMaker coffeeMaker = context.get(CoffeeMaker.class);
     coffeeMaker.makeIt()
   }

    External dependencies

    We can supporting external dependencies when creating the BeanScope. We need to do 2 things. we need to specify these via

    • 1. Specify the external dependency via @InjectModule(requires=...). Otherwise at compile time the annotation processor detects it as a missing dependency and we can't compile.
    • 2. Provide the dependency when creating the BeanScope

    For example, given we have Pump as an externally provided dependency. 

    {@code

   // tell the annotation processor Pump is provided externally
   // otherwise it thinks we have a missing dependency

    • Method Detail

      • builder

        static BeanScopeBuilder builder()
        Build a bean scope with options for shutdown hook and supplying external dependencies.

        We can optionally:

        • Provide external dependencies
        • Specify a parent BeanScope
        • Specify specific modules to wire
        • Specify to include a shutdown hook (to fire preDestroy lifecycle methods)
        • Use forTesting() to specify mocks and spies to use when wiring tests
        

   // create a BeanScope ...

   try (BeanScope scope = BeanScope.builder()
     .build()) {

     CoffeeMaker coffeeMaker = context.get(CoffeeMaker.class);
     coffeeMaker.makeIt()
   }

      • get

        <T> T get​(Class<T> type)
        Return a single bean given the type. 
        

   CoffeeMaker coffeeMaker = beanScope.get(CoffeeMaker.class);
   coffeeMaker.brew();
        Parameters:
        type - an interface or bean type
        Throws:
        NoSuchElementException - When no matching bean is found

      • get

        <T> T get​(Class<T> type,
          @Nullable
          String name)
        Return a single bean given the type and name. 
        

   Heater heater = beanScope.get(Heater.class, "electric");
   heater.heat();
        Parameters:
        type - an interface or bean type
        name - the name qualifier of a specific bean
        Throws:
        NoSuchElementException - When no matching bean is found

      • get

        <T> T get​(Type type,
          @Nullable
          String name)
        Return a single bean given the generic type and name.
        Parameters:
        type - The generic type
        name - the name qualifier of a specific bean
        Throws:
        NoSuchElementException - When no matching bean is found

      • getOptional

        <T> Optional<T> getOptional​(Class<T> type)
        Optionally return a single bean given the type and empty if it is not found.
        Parameters:
        type - an interface or bean type

      • getOptional

        <T> Optional<T> getOptional​(Type type,
                            @Nullable
                            String name)
        Optionally return a single bean given the type and name and empty if it is not found.
        Parameters:
        type - an interface or bean type
        name - the name qualifier of a specific bean

      • listByAnnotation

        List<Object> listByAnnotation​(Class<?> annotation)
        Return the list of beans that have an annotation. 
        

   // e.g. register all controllers with web a framework
   // .. where Controller is an annotation on the beans

   List<Object> controllers = beanScope.listByAnnotation(Controller.class);
        Parameters:
        annotation - An annotation class.

      • list

        <T> List<T> list​(Class<T> type)
        Return the list of beans for a given type. 
        

   // e.g. register all routes for a web framework

   List<WebRoute> routes = beanScope.list(WebRoute.class);
        Parameters:
        type - The type of beans to return.

      • list

        <T> List<T> list​(Type type)
        Return the list of beans that implement the given type.

      • listByPriority

        <T> List<T> listByPriority​(Class<T> type)
        Return the list of beans that implement the interface sorting by priority.

      • listByPriority

        <T> List<T> listByPriority​(Class<T> type,
                           Class<? extends Annotation> priority)
        Return the beans that implement the interface sorting by the priority annotation used.

        The priority annotation will typically be either javax.annotation.Priority or jakarta.annotation.Priority.

        Parameters:
        type - The interface type of the beans to return
        priority - The priority annotation used to sort the beans

      • map

        <T> Map<String,​T> map​(Type type)
        Return the beans for this type mapped by their qualifier name.

        Beans with no qualifier name get a generated unique key to use instead.

      • all

        List<BeanEntry> all()
        Return all the bean entries from the scope.

        The bean entries include entries from the parent scope if it has one.

        Returns:
        All bean entries from the scope.

      • contains

        boolean contains​(Type type)
        Return true if the bean scope contains the given type.

      • contains

        boolean contains​(String type)
        Return true if the bean scope contains the given type.

      • close

        void close()
        Close the scope firing any @PreDestroy lifecycle methods.
        Specified by:
        close in interface AutoCloseable