Interface InjectionLayer<I extends Injector>

Type Parameters:
I - the type of injector this layer uses.
All Superinterfaces:
AutoCloseable, Named
All Known Implementing Classes:
DefaultInjectionLayer, UncloseableInjectionLayer
public sealed interface InjectionLayer<I extends Injector> extends Named, AutoCloseable permits DefaultInjectionLayer<I>, UncloseableInjectionLayer<I>
Represents the current layer of injection which is being worked on.
Since:
4.0

  • Field Details

    • AUTO_CONFIGURE_FILE_NAME_FORMAT

      static final String AUTO_CONFIGURE_FILE_NAME_FORMAT
      The file name format for the autoconfigure files. This format will be used when calling installAutoConfigureBindings and gets formatted with the given component name to the method.
      See Also:

  • Method Details

    • boot

      @NonNull static @NonNull InjectionLayer<Injector> boot()
      Returns the singleton boot injection layer. That layer contains all bindings which were used during the current runtime component initialization and contains all core bindings.
      Returns:
      the singleton boot injection layer.

    • ext

      @NonNull static @NonNull InjectionLayer<Injector> ext()
      Returns the singleton injection layer which should be used for all kinds of external component injection (like plugins). The ext layer has all bindings of the boot layer present.
      Returns:
      the singleton ext injection layer.

    • fresh

      @NonNull static @NonNull InjectionLayer<Injector> fresh(@NonNull @NonNull String name)
      Provides a fresh injection layer, with no bindings configured to the returned injector, except for a binding to the layer itself with the provided name.
      Parameters:
      name - the name of the new injection layer.
      Returns:
      a new injection layer with no configured bindings.
      Throws:
      NullPointerException - if the given name is null.
      IllegalArgumentException - if the given name is invalid.

    • child

      @NonNull static @NonNull InjectionLayer<Injector> child(@NonNull @NonNull InjectionLayer<Injector> parent, @NonNull @NonNull String name)
      Constructs a new child layer for the given parent layer. All bindings from the parent layer are still visible to the child layer, but not vise-versa.

      The new layer has a binding for the layer type with the given name in order to request injection of the given layer. Note that injecting the injector of a layer still results in the child layer injector, even if no name is present.

      Parameters:
      parent - the parent layer to construct the child from.
      name - the name of the child layer.
      Returns:
      a new layer with the given parent layer.
      Throws:
      NullPointerException - if the given parent layer or name is null.
      IllegalArgumentException - if the given name is invalid.

    • specifiedChild

      @NonNull static @NonNull InjectionLayer<Injector> specifiedChild(@NonNull @NonNull InjectionLayer<? extends Injector> parent, @NonNull @NonNull String name, @NonNull @NonNull Consumer<TargetedInjectorBuilder> configurator)
      Constructs a new child layer for the given parent layer. All bindings from the parent layer are still visible to the child layer, but not vise-versa. The returned child layer uses a specified injector and passes it to the given configurator in order to precisely configure bindings.

      The new layer has a binding for the layer type with the given name in order to request injection of the given layer. Note that injecting the injector of a layer still results in the child layer injector, even if no name is present.

      This type of layer should be used in a context when the constructed bindings of classes should be visible to the parent layer, while some bindings need to be specifically overridden. This can for example be a modular context, where the module description should only be visible to the current module, not to all modules.

      Parameters:
      parent - the parent layer to construct the child from.
      name - the name of the child layer.
      configurator - the configurator for the layer, for convince it also provides the specified injector.
      Returns:
      a new specified layer with the given parent layer.
      Throws:
      NullPointerException - if the given parent layer, name or configurator is null.
      IllegalArgumentException - if the given name is invalid or the parent layer is the boot layer.

    • findLayerOf

      @NonNull static @NonNull InjectionLayer<?> findLayerOf(@NonNull @NonNull Object object)
      Finds the injection layer associated with the given object or returns the default ext() injection layer. The following search rules apply (in order):
      1. If the given object is an InjectionLayerHolder, the layer stored in the holder is returned.
      2. If the given object has a layer associated in the layer registry, that layer is returned.
      3. If the given object is a class the associated class loader of the given class is checked.
      4. If the given object is not a class loader the loader of the object class is checked.
      5. If none of the above rules matches the the default ext() layer is returned.
      Parameters:
      object - the object to get the associated injection layer of.
      Returns:
      the injection layer associated with the given object or the default ext() layer.
      Throws:
      NullPointerException - if the given object is null.

    • findLayerOf

      @NonNull static @NonNull InjectionLayer<?> findLayerOf(@NonNull @NonNull Object object, @NonNull @NonNull InjectionLayer<?> def)
      Finds the injection layer associated with the given object or returns the given default injection layer. The following search rules apply (in order):
      1. If the given object is an InjectionLayerHolder, the layer stored in the holder is returned.
      2. If the given object has a layer associated in the layer registry, that layer is returned.
      3. If the given object is a class the associated class loader of the given class is checked.
      4. If the given object is not a class loader the loader of the object class is checked.
      5. If none of the above rules matches the given default layer is returned.
      Parameters:
      object - the object to get the associated injection layer of.
      def - the default layer to return if no layer can be found.
      Returns:
      the injection layer associated with the given object or the given default layer.
      Throws:
      NullPointerException - if the given object or default layer is null.

    • name

      @NonNull @NonNull String name()
      Get the name of this injection layer, for identification purposes. The names boot and ext are reserved for internal use only.
      Specified by:
      name in interface Named
      Returns:
      the name of this layer.

    • injector

      @NonNull I injector()
      Gets the underlying injector of this layer.
      Returns:
      the underlying injector of this layer.

    • instance

      <T> @UnknownNullability T instance(@NonNull @NonNull Class<T> type)
      Convince method to create or get the instance of the given class type.
      Type Parameters:
      T - the type of the class modeled by the given class object.
      Parameters:
      type - the type of the element to get.
      Returns:
      the constructed instance of the class type, may be null.
      Throws:
      NullPointerException - if the given type is null.

    • instance

      <T> @UnknownNullability T instance(@NonNull @NonNull BindingKey<T> bindingKey)
      Convince method to create or get the instance of the given binding key.
      Type Parameters:
      T - the type of the return value modeled by the given binding key.
      Parameters:
      bindingKey - the binding key for the instance to resolve.
      Returns:
      the constructed instance of the class type, may be null.
      Throws:
      NullPointerException - if the given binding key is null.

    • instance

      <T> @UnknownNullability T instance(@NonNull @NonNull Class<T> type, @NonNull @NonNull UnaryOperator<InjectionRequest<T>> decorator)
      Convince method to create or get the instance of the given type, while allowing to specifically influence the injection context.
      Type Parameters:
      T - the type of the return value modeled by the given element.
      Parameters:
      type - the type of the element to get.
      decorator - the decorator for the injection request.
      Returns:
      the constructed instance of the class type, may be null.
      Throws:
      NullPointerException - if the given type or decorator is null.

    • install

      void install(@NonNull @NonNull UninstalledBinding<?> binding)
      Installs the uninstalled binding into the underlying injector.
      Parameters:
      binding - the binding to install.
      Throws:
      NullPointerException - if the given binding is null.

    • install

      void install(@NonNull @NonNull DynamicBinding binding)
      Installs a dynamic binding into the underlying injector. The dynamic binding can be used to provide bindings based on the presence of annotations and other matching criteria. Dynamic bindings have a lower priority than UninstalledBinding.
      Parameters:
      binding - the dynamic binding to install.
      Throws:
      NullPointerException - if the given binding is null.

    • installAutoConfigureBindings

      void installAutoConfigureBindings(@NonNull @NonNull ClassLoader loader, @NonNull @NonNull String component)
      Installs the autoconfiguration bindings for the given component. For this method to work the autoconfiguration bindings must be located at autoconfigure/<component>.aero.

      This method binds the autoconfiguration bindings to the underlying injector of this layer.

      Parameters:
      loader - the loader in which the file resource is located.
      component - the name of the component to load the autoconfiguration bindings of.
      Throws:
      NullPointerException - if the given class loader or component name is null.
      UncheckedIOException - if an I/O error occurs while loading the auto config bindings.

    • asUncloseable

      @NonNull @NonNull InjectionLayer<I> asUncloseable()
      Makes this injection layer not closeable, returning the same layer if it is already not closeable.
      Returns:
      the same injection layer from the functionality, but not closeable.

    • register

      @NonNull @NonNull InjectionLayer<I> register(@NonNull @NonNull Object... hints)
      Registers this injection layer to the injection layer registry. Subsequent calls to findLayerOf(Object) will be able to resolve the layer if the given object value is the exact the same as given as one of the hints (exact as by using the == compare operation).

      Note that the layer lookup order is predictable based on the call order of register. If different layers are registered for the same objects, the first layer to be registered will be found.

      Parameters:
      hints - the hints to use for the layer registration.
      Returns:
      the same layer as used to call the method, for chaining.
      Throws:
      NullPointerException - if the given hints array is null.

    • close

      void close()
      Closes this injector and removes all leftover bindings (if any).
      Specified by:
      close in interface AutoCloseable
      Throws:
      UnsupportedOperationException - if this layer cannot be closed.