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.



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

   @InjectModule(requires=Pump.class)

 

When we build the BeanScope provide the dependency via BeanScopeBuilder.bean(Class, Object).



   // provide external dependencies ...
   Pump pump = ...

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

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

 
  • Method Summary

    Modifier and Type
    Method
    Description
    all()
    Return all the bean entries from the scope.
    Build a bean scope with options for shutdown hook and supplying external dependencies.
    void
    Close the scope firing any @PreDestroy lifecycle methods.
    boolean
    contains(Type type)
    Return true if the bean scope contains the given type.
    boolean
    Return true if the bean scope contains the given type.
    <T> T
    get(Class<T> type)
    Return a single bean given the type.
    <T> T
    get(Class<T> type, String name)
    Return a single bean given the type and name.
    <T> T
    get(Type type, String name)
    Return a single bean given the generic type and name.
    default <T> T
    getGen(Class<T> type, String name)
     
    <T> Optional<T>
    getOptional(Class<T> type)
    Optionally return a single bean given the type and empty if it is not found.
    <T> Optional<T>
    getOptional(Type type, String name)
    Optionally return a single bean given the type and name and empty if it is not found.
    <T> List<T>
    list(Class<T> type)
    Return the list of beans for a given type.
    <T> List<T>
    list(Type type)
    Return the list of beans that implement the given type.
    listByAnnotation(Class<? extends Annotation> annotation)
    Return the list of beans that have an annotation.
    <T> List<T>
    Return the list of beans that implement the interface sorting by priority.
    <T> List<T>
    listByPriority(Class<T> type, Class<? extends Annotation> priority)
    Return the beans that implement the interface sorting by the priority annotation used.
    <T> Map<String,T>
    map(Type type)
    Return the beans for this type mapped by their qualifier name.
  • Method Details

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

      default <T> T getGen(Class<T> type, @Nullable String name)
    • 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<? extends Annotation> annotation)
      Return the list of beans that have an annotation. The annotation must have a @Retention policy of RUNTIME
      
      
         // 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

      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