Avaje Inject

Avaje Inject is an Annotation Processing Tool (APT) based dependency injection framework designed specifically for server-side developers. It uses Java annotation processing to generate source code at compile time, which avoids the use of reflection or classpath scanning. This results in low overhead and fast startup times, making it highly suitable for microservices.

Key characteristics:

• Compile-time DI: Uses APT to generate wiring code.
• Zero Reflection: No reflection or classpath scanning is used at runtime.
• Library-only: It is a lightweight DI library (~25k in size) with minimal dependencies.

Using Avaje Inject with GraalVM native images provides the following performance characteristics:

• Startup: < 50ms
• Memory: 30-50MB
• Warm-up: No warm-up required; the application runs at full speed immediately.

Avaje-Inject is designed for server-side development. While similar to Dagger in its use of annotation processing and code generation to avoid reflection, it offers several features more common in Spring:

• Lifecycle Support: Uses @PostConstruct and @PreDestroy.
• Factory Pattern: Supports Spring-like @Factory and @Bean annotations.
• Conditional Wiring: Supports @RequiresBean and @RequiresProperty.
• Testing: Provides @InjectTest for component testing via avaje-inject-test.
• Interface Retrieval: Provides an API to obtain all bean instances that implement a specific interface.

The Avaje Inject documentation is organized into a full library reference and a collection of step-by-step guides.

• For comprehensive information on the API, annotations, use cases, and performance, refer to LIBRARY.md.
• For specific tasks and implementation patterns, use the guides located in the guides/ directory.

Avaje Inject determines bean creation order based on real dependencies. To ensure one bean is initialized before another, include the dependency as a parameter in the @Bean factory method or the target class constructor.

Avoid creating artificial or reverse dependencies solely to force an order, as this can lead to circular dependency cycles. The dependency direction should always reflect the actual requirement for initialization.

@Factory
class DatabaseConfig {

  @Bean
  Database database(OpenTelemetry openTelemetry, DataSource dataSource) {
    return Database.builder()
      .dataSource(dataSource)
      .build();
  }
}

avaje-inject uses the inject-generator annotation processor to perform compile-time code generation. This approach avoids reflection-based wiring, making it compatible with the native image compiler. The generator produces the following artifacts:

• *Module classes: Explicit wiring code that constructs and injects beans in dependency order without reflection.
• *$DI classes: Per-bean classes containing explicit constructor calls, field injection, and lifecycle callbacks.
• META-INF/services/io.avaje.inject.spi.InjectExtension: A service file used by ServiceLoader to discover the generated module at startup.

Because the wiring is expressed as plain Java source code, it is treated as standard code by the native image compiler.

When avaje-inject generates AOP proxies (for example, for @Aspect beans), they are generated as plain source code. However, these proxies use reflection to obtain the Method included in the io.avaje.inject.aop.Invocation.

To support this, the generator automatically produces a reflect-config.json resource file located in META-INF/native-image. This file instructs the native image compiler to include the necessary reflection metadata required for AOP proxies to function at runtime.

You can control the lifecycle of a bean using scope annotations:

• @Singleton: Creates a single instance for the application (this is the default behavior for many configurations).
• @Prototype: Creates a new instance every time the bean is requested/injected.

@Singleton          // One instance (default)
public class Single { }

@Prototype          // New instance each time
public class Multi { }