Class Injector

java.lang.Object
de.tomatengames.util.injector.Injector
public final class Injector extends Object
A single shared InjectionProvider for the current runtime, sometimes called "root provider". This provider should be used by most applications that do not create individual providers.

Injector is a simple dependency injection framework. It allows to provide values using the provide(...) methods and inject them using the inject(...) methods. Values provided to the Injector are stored for an indefinite period of time, and can be accessed globally. Injector does not perform any kind of component scanning out of the box.

It is possible to provide values temporarily for a single thread by creating a local InjectionEnvironment using the local() method.

Since:
1.9

  • Method Details

    • local

      public static @NotNull InjectionEnvironment local()
      Creates a new local InjectionEnvironment. This environment can be used to provide local injection values.

      While the environment is open, values provided to the environment will be visible to inject calls. The environment is only open for the current thread. That means, values provided to the environment will only be visible to inject calls of the current thread. When the environment is closed, it is no longer open, i.e. values provided to the environment will no longer be visible to inject calls.

      If multiple environments are open at the same time in the same thread and provide the same key, the value of the last environment created will be used for inject calls.

      If an environment is open that provides the same key as the global provider, the value of the environment will be used for inject calls, effectively hiding the global provider's value.

      Returns:
      The new environment.
      See Also:

    • provide

      public static void provide(@NotNull String key, @NotNull Object value) throws InjectionException
      Provides the specified value for the specified injection key.
      Parameters:
      key - The injection key.
      value - The value.
      Throws:
      InjectionException - If the key is already provided.

    • provideIfAbsent

      public static boolean provideIfAbsent(@NotNull String key, @NotNull Object value)
      Provides the specified value for the specified injection key to the root provider if the key is not already provided. If the key is already provided, nothing happens.
      Parameters:
      key - The injection key.
      value - The value.
      Returns:
      true if the value was provided, false otherwise.

    • unprovide

      public static void unprovide(@NotNull String key)
      Removes the specified injection key from the root provider. If the key is not provided, nothing happens.

      It is recommended to create a local environment using local() instead of providing and unproviding values frequently.

      Parameters:
      key - The injection key.

    • injectOptional

      public static <T> @Nullable T injectOptional(@NotNull String key)
      Returns the value provided for the specified key if it exists.

      Note that the return value is auto-casted to the requested type. This is an unchecked cast. It must be ensured that the requested type is compatible with the value.

      Type Parameters:
      T - The requested type of the value. The return value is auto-casted to this type.
      Parameters:
      key - The key.
      Returns:
      The value provided for the key. If no value was provided for the key, null is returned. The return value is auto-casted to the requested type.

    • inject

      public static <T> @NotNull T inject(@NotNull String key) throws InjectionException
      Returns the value provided for the specified key.

      Note that the return value is auto-casted to the requested type. This is an unchecked cast. It must be ensured that the requested type is compatible with the value.

      Type Parameters:
      T - The requested type of the value. The return value is auto-casted to this type.
      Parameters:
      key - The key.
      Returns:
      The value provided for the key. If no such value exists, an InjectionException is thrown. The return value is auto-casted to the requested type.
      Throws:
      InjectionException - If the injection key was not provided.

    • provide

      public static <T> void provide(@NotNull InjectionKey<T> key, @NotNull T value) throws InjectionException
      Provides the specified value for the specified injection key to the root provider.
      Type Parameters:
      T - The type of values providable for the key.
      Parameters:
      key - injection key.
      value - The value.
      Throws:
      InjectionException - If the key is already provided.

    • provideIfAbsent

      public static <T> boolean provideIfAbsent(@NotNull InjectionKey<T> key, @NotNull T value)
      Provides the specified value for the specified injection key to the root provider if the key is not already provided. If the key is already provided, nothing happens.
      Type Parameters:
      T - The type of values providable for the key.
      Parameters:
      key - injection key.
      value - The value.
      Returns:
      true if the value was provided, false otherwise.

    • unprovide

      public static void unprovide(@NotNull InjectionKey<?> key)
      Removes the specified injection key from the root provider. If the key is not provided, nothing happens.

      It is recommended to create a local environment using local() instead of providing and unproviding values frequently.

      Parameters:
      key - The injection key.

    • injectOptional

      public static <T> @Nullable T injectOptional(@NotNull InjectionKey<T> key)
      Returns the value provided for the specified key if it exists.
      Type Parameters:
      T - The type of the value provided by the key.
      Parameters:
      key - The injection key.
      Returns:
      The value provided for the key. If no value was provided for the key, null is returned.

    • inject

      public static <T> @NotNull T inject(@NotNull InjectionKey<T> key) throws InjectionException
      Returns the value provided for the specified key.
      Type Parameters:
      T - The type of the value provided by the key.
      Parameters:
      key - The injection key.
      Returns:
      The value provided for the key. If no value was provided for the key, an InjectionException is thrown.
      Throws:
      InjectionException - If no value was provided for the key.

    • provide

      public static <T> void provide(@NotNull Class<T> key, @NotNull T value) throws InjectionException
      Provides the specified value for the specified key class to the root provider. The value is only provided for the exact key class specified.
      Type Parameters:
      T - The type of the value.
      Parameters:
      key - The key class.
      value - The value to provide.
      Throws:
      InjectionException - If the specified key class is already provided.

    • provideIfAbsent

      public static <T> boolean provideIfAbsent(@NotNull Class<T> key, @NotNull T value)
      Provides the specified value for the specified key class to the root provider if the key class is not already provided. The value is only provided for the exact key class specified.

      If the key class is already provided, nothing happens.

      Type Parameters:
      T - The type of the value.
      Parameters:
      key - The key class.
      value - The value to provide.
      Returns:
      true if the value was provided, false otherwise.

    • unprovide

      public static void unprovide(@NotNull Class<?> key)
      Removes the specified injection from the root provider. If the injected value found for the specified key is provided for additional classes in its class hierarchy that are specializations of the specified class, those occurrences are removed as well.

      If the key class is not provided, nothing happens.

      It is recommended to create a local environment using local() instead of providing and unproviding values frequently.

      Parameters:
      key - The key class.

    • injectOptional

      public static <T> @Nullable T injectOptional(@NotNull Class<T> key)
      Returns the value provided for the specified key class if it exists.
      Type Parameters:
      T - The type of the class and the value provided by the key class.
      Parameters:
      key - The injection key class.
      Returns:
      The value provided for the key. If no value was provided for the key, null is returned.

    • inject

      public static <T> @NotNull T inject(@NotNull Class<T> key) throws InjectionException
      Returns the value provided for the specified key class.
      Type Parameters:
      T - The type of the class and the value provided by the key class.
      Parameters:
      key - The injection key class.
      Returns:
      The value provided for the key. If no value was provided for the key, an InjectionException is thrown.
      Throws:
      InjectionException - If no value was provided for the key class.