Interface Context

All Superinterfaces:
AutoCloseable, Binder, Injector
public interface Context extends Injector, Binder, AutoCloseable
An Injector that manages zero or more Bindings to be used for injection into InjectionPoints.

Contexts are the preferred means by which applications perform Dependency Injection. Once established, applications typically use the following steps with a Context to perform injection:

  1. Invoke the Binder.bind(Class) method to create and register the Bindings, representing the Objects to be injected for specific Classes
  2. Invoke the Injector.inject(Object) method to perform injection into existing Objects
  3. Invoke the create(Class) method to instantiate an instance of Class, using constructor-based injection, and afterwards using field or setter-based injection
Since:
Oct-2024
Author:
brian.oliver
See Also:

  • Method Details

    • bind

      <T> BindingBuilder<T> bind(T value)
      Creates a BindingBuilder pre-loaded with the specified instance value, enabling BindingBuilder.asAllInterfaces() and BindingBuilder.asAllInterfaces(Predicate) to register the value against every interface in its type hierarchy in a single call.

      Example: 

      context.bind(myService).asAllInterfaces();
      Type Parameters:
      T - the type of the instance
      Parameters:
      value - the instance to bind
      Returns:
      a BindingBuilder loaded with the value

    • create

      <T> T create(Class<T> requiredClass) throws InjectionException
      Creates an instance of the specified class by locating and injecting a constructor annotated with Inject with values resolved from the Context. Should an injectable constructor not be found, an attempt will be made to use the default constructor.

      Should constructor injection succeed, the further injection of Inject-annotated fields and methods will be attempted.

      Type Parameters:
      T - the type of the Class
      Parameters:
      requiredClass - the required Class to create
      Returns:
      a new instance of the required Class
      Throws:
      NullPointerException - when the required class was null
      InjectionException - when injection fails

    • create

      <T> T create(build.codemodel.foundation.usage.TypeUsage typeUsage) throws InjectionException
      Creates an instance of the type represented by a TypeUsage with values resolved from the Context.
      Type Parameters:
      T - the type to create
      Parameters:
      typeUsage - the TypeUsage
      Returns:
      an instance of the type represented by the TypeUsage
      Throws:
      NullPointerException - when the TypeUsage was null
      InjectionException - when injection fails

    • create

      <T> T create(Dependency dependency) throws InjectionException
      Creates an instance of the type represented by the specified Dependency with values resolved from the Context.
      Type Parameters:
      T - the type to create
      Parameters:
      dependency - the Dependency
      Returns:
      an instance of the type represented by the Dependency
      Throws:
      NullPointerException - when the Dependency was null
      InjectionException - when injection fails

    • snapshot

      Context snapshot(Path outputPath)
      Builds a BindingGraphTrait from the current contributor state, attaches it to the framework's JDKCodeModel, and writes a human-readable wiring report to outputPath.

      No-ops immediately if no real BindingGraphContributor is installed (i.e. the BindingGraphContributor.NOOP is still in place). May be called at any point after bindings are registered.

      Parameters:
      outputPath - the path to write the wiring report to
      Returns:
      this Context for fluent chaining
      Throws:
      UncheckedIOException - if writing the report fails

    • validate

      Context validate()
      Validates the current set of registered bindings before any objects are created. Performs three checks:
      1. Cycle detection — throws CyclicDependencyException with the full cycle path if a dependency cycle is found among class bindings.
      2. Unsatisfied dependency detection — collects every class binding whose injected dependencies have no corresponding binding and throws ValidationException listing them all at once.
      3. Scope violation detection — flags edges where a wider-scoped binding (e.g. Singleton) depends on a narrower-scoped one (e.g. prototype).
      Returns:
      this Context for fluent chaining (e.g. context.validate().initializeEagerSingletons())
      Throws:
      CyclicDependencyException - if a dependency cycle is detected
      ValidationException - if unsatisfied dependencies or scope violations are found

    • initializeEagerSingletons

      Context initializeEagerSingletons()
      Pre-creates all Singleton-scoped class bindings in dependency order, using Graphs.parallelizableGroups(VertexGraph) to initialize independent groups in parallel.

      Typically called immediately after validate(): 

      context.validate().initializeEagerSingletons();
      Returns:
      this Context for fluent chaining

    • close

      void close()
      Closes this Context, invoking any PreDestroy lifecycle methods on instantiated singleton instances in reverse dependency order (dependents are destroyed before their dependencies).
      Specified by:
      close in interface AutoCloseable

    • newContext

      Context newContext()
      Creates a new Context with the this Context as a parent solver.
      Returns:
      a new Context

    • resolver

      Resolver<Object> resolver()
      Obtains a Resolver that can be used to resolve Dependencys based on this Context.
      Returns:
      a Resolver

    • addResolver

      Context addResolver(Resolver<?> resolver)
      Adds the specified Resolver
      Parameters:
      resolver - the Resolver
      Returns:
      this Context to permit fluent-style method invocation

    • addResolver

      Context addResolver(BiFunction<? super InjectionFramework, ? super Context, Resolver<?>> supplier)
      Adds a Resolver produced by the specified Function based on this Context.
      Parameters:
      supplier - the BiFunction to supply a Resolver based on the InjectionFramework and Context
      Returns:
      this Context to permit fluent-style method invocation