Agent Skills: GuicedEE Inject

GuicedEE Inject

The runtime engine that classpath-scans, creates the Guice injector, and manages the full startup/shutdown lifecycle.

Core Concept

GuiceContext is a singleton that orchestrates everything. Call inject() once — it discovers SPIs, scans, builds the injector, and runs lifecycle hooks:

IGuiceConfigurator → ClassGraph scan → IGuicePreStartup → Injector created → IGuicePostStartup
                                                                                    ↓
                                                                          IGuicePreDestroy (shutdown)

Required Flow

1. Add com.guicedee:inject dependency.
2. Register your module for scanning, then bootstrap:

   IGuiceContext.registerModuleForScanning.add("my.app");
   IGuiceContext.instance().inject();
   

3. Configure module-info.java:
   • requires com.guicedee.guicedinjection;
   • opens injection packages to com.google.guice
   • opens DTO packages to com.fasterxml.jackson.databind
   • provides every SPI implementation
4. Dual-register all SPIs in module-info.java and META-INF/services/.

Providing Guice Modules

Implement IGuiceModule and register via SPI:

public class AppModule extends AbstractModule implements IGuiceModule<AppModule> {
    @Override
    protected void configure() {
        bind(Greeter.class).to(DefaultGreeter.class);
    }
}

// module-info.java
provides com.guicedee.client.services.lifecycle.IGuiceModule with my.app.AppModule;

Lifecycle Hooks

| Hook | When it runs | Return | |---|---|---| | IGuiceConfigurator | First — configures GuiceConfig before scanning | IGuiceConfig<?> | | IGuicePreStartup | After scan, before injector — grouped by sortOrder() | List<Future<Boolean>> | | IGuiceModule | During injector creation — standard Guice module | — | | IGuicePostStartup | After injector is ready — async, grouped by sortOrder() | List<Uni<Boolean>> | | IGuicePreDestroy | On shutdown — cleanup resources | void |

All hooks extend IDefaultService<J> (CRTP); override sortOrder() to control execution order and enabled() to conditionally skip.

Logging

LogUtils — programmatic setup

LogUtils.addHighlightedConsoleLogger();        // ANSI console (local dev)
LogUtils.addConsoleLogger(Level.INFO);         // plain console
LogUtils.addFileRollingLogger("app", "logs");  // rolling file (100 MB / daily)
Logger audit = LogUtils.getSpecificRollingLogger("audit", "logs/audit", null, false);

When CLOUD env var is set, layouts auto-switch to compact JSON.

Log level control

Set via environment: GUICEDEE_LOG_LEVEL, LOG_LEVEL, DEBUG=true, or TRACE=true. Programmatic: GuiceContext.setDefaultLogLevel(Level.INFO).

JobService

Virtual-thread-backed executor pools with graceful shutdown:

JobService jobs = JobService.INSTANCE;
jobs.registerJob("import", 100);
jobs.addJob("import", () -> processFile(file));
jobs.registerPollingJob("heartbeat", () -> ping(), 0, 30, TimeUnit.SECONDS);

Pools auto-shutdown via IGuicePreDestroy.

Non-Negotiable Constraints

• Never call inject() recursively during build — use IGuicePostStartup instead.
• At most one GuiceContext instance per JVM.
• Every SPI must be dual-registered (module-info.java + META-INF/services/).
• Injection packages must opens to com.google.guice.
• IGuiceContext.registerModuleForScanning.add("my.module") must be called before instance().
• Scanning is off by default and no built-in configurator enables it — call IGuiceContext.instance().getConfig().setClasspathScanning(true).setAnnotationScanning(true).setMethodInfo(true).setFieldInfo(true) (or setServiceLoadWithClassPath(true)) before inject(), or annotation discovery finds nothing. Tests that boot directly must do the same in @BeforeAll.
• All lifecycle hooks must extend IDefaultService<J> (CRTP) and override sortOrder().

References

• references/classpath-scanning.md — scanner SPI interfaces, GuiceConfig options, module/JAR/package filtering.
• references/lifecycle-logging.md — lifecycle hook details, @InjectLogger attributes, LogUtils API, Log4JConfigurator SPI, JobService full API.