Interface BeanScope

All Superinterfaces:
AutoCloseable
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. Use the @External annotation.

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


  class CoffeeMaker {
    // tell the annotation processor Pump is provided externally at runtime
    // otherwise it thinks we have a missing dependency
    @External Pump pump;
  }

When building the BeanScope, the dependency must be provided manually 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
    List<BeanEntry>
    all()
    Return all the bean entries from the scope.
    static BeanScopeBuilder
    builder()
    Build a bean scope with options for shutdown hook and supplying external dependencies.
    void
    close()
    Close the scope firing any @PreDestroy lifecycle methods.
    boolean
    contains(Type type)
    Return true if the bean scope contains the given type.
    boolean
    contains(String type)
    Return true if the bean scope contains the given type.
    default Set<String>
    customScopeAnnotations()
    Return the custom scope annotations contained in this bean scope.
    <T> T
    get(Class<T> type)
    Return a single bean given the type.
    <T> T
    get(Class<T> type, @Nullable String name)
    Return a single bean given the type and name.
    default <T> T
    get(Type type)
    Return a single bean given the full generic type.
    <T> T
    get(Type type, @Nullable String name)
    Return a single bean given the full generic type and 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, @Nullable 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.
    <T> List<T>
    list(Type type, @Nullable String name)
    Return the list of beans for the given type and name.
    List<Object>
    listByAnnotation(Class<? extends Annotation> annotation)
    Return the list of beans that have an annotation.
    default <T> List<T>
    listByPriority(Class<T> type)
    Return the list of beans that implement the class sorting by priority.
    <T> List<T>
    listByPriority(Type type)
    Return the list of beans that implement the type sorting by priority.
    <T> Map<String,T>
    map(Type type)
    Return the beans for this type mapped by their qualifier name.

  • Method Details

    • 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

      default <T> T get(Type type)
      Return a single bean given the full generic type.
      Parameters:
      type - The generic type
      Throws:
      NoSuchElementException - When no matching bean is found

    • get

      <T> T get(Type type, @Nullable String name)
      Return a single bean given the full 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.

    • list

      <T> List<T> list(Type type, @Nullable String name)
      Return the list of beans for the given type and name.

    • listByPriority

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

    • listByPriority

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

    • 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

    • customScopeAnnotations

      default Set<String> customScopeAnnotations()
      Return the custom scope annotations contained in this bean scope.