A modular, Guice-first application platform for building reactive Java services on Vert.x 5.

GuicedEE wires together Google Guice, Vert.x 5, and the MicroProfile specification ecosystem into a cohesive, JPMS-native platform. Every module is designed around SPI discovery, annotation-driven configuration, and environment variable overrides — so you get production-ready defaults with zero boilerplate.

Website: https://guicedee.com Organization: https://github.com/GuicedEE

• Guice-first DI — All lifecycle, routing, persistence, messaging, and telemetry are wired through a single Guice injector. @Inject works everywhere.
• Vert.x 5 reactive core — Non-blocking HTTP, WebSockets, event bus, SQL clients, and RabbitMQ — all on the Vert.x event loop with Mutiny Uni/Multi support.
• MicroProfile standards — Config, Health, Metrics, OpenAPI, Fault Tolerance, and Telemetry follow Eclipse MicroProfile specifications.
• JPMS Level 3 — Every module ships a proper module-info.java with explicit exports, requires, provides, and uses directives.
• SPI + ClassGraph discovery — Modules, lifecycle hooks, consumers, REST resources, health checks, and more are discovered automatically at startup.
• Annotation-driven, environment-overridable — Configure everything with annotations; override anything with environment variables or system properties at deploy time.

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>com.guicedee</groupId>
            <artifactId>guicedee-bom</artifactId>
            <version>2.0.2-SNAPSHOT</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

<dependencies>
    <dependency>
        <groupId>com.guicedee</groupId>
        <artifactId>inject</artifactId>
    </dependency>
    <dependency>
        <groupId>com.guicedee</groupId>
        <artifactId>web</artifactId>
    </dependency>
    <dependency>
        <groupId>com.guicedee</groupId>
        <artifactId>rest</artifactId>
    </dependency>
</dependencies>

IGuiceContext.registerModuleForScanning.add("my.app");
IGuiceContext.instance();
// HTTP server is listening on :8080, REST routes are registered, DI is live

@Path("/hello")
public class HelloResource {

    @Inject
    private GreetingService greeter;

    @GET
    @Produces(MediaType.APPLICATION_JSON)
    public String hello(@QueryParam("name") String name) {
        return greeter.greet(name);
    }
}

module my.app {
    requires com.guicedee.guicedinjection;
    requires com.guicedee.vertx.web;
    requires com.guicedee.rest;

    provides com.guicedee.client.services.lifecycle.IGuiceModule
        with my.app.AppModule;
}

┌─────────────────────────────────────────────────────────────────────┐
│                         Your Application                            │
├──────────┬──────────┬──────────┬──────────┬──────────┬──────────────┤
│   REST   │WebSockets│Persistence│ RabbitMQ │Telemetry │  OpenAPI     │
│  (JAX-RS)│ (RFC6455)│(Hibernate)│  (AMQP)  │  (OTLP)  │ (Swagger)   │
├──────────┴──────────┴──────────┴──────────┴──────────┴──────────────┤
│                    Vert.x Web · HTTP/HTTPS · Router                 │
├─────────────────────────────────────────────────────────────────────┤
│              Guiced Vert.x · EventBus · Verticles · Codecs          │
├──────────┬──────────┬──────────┬─────────────────────────────────────┤
│  Health  │ Metrics  │  Config  │         Fault Tolerance             │
│(MP Health)│(Dropwiz.)│(SmallRye)│           (MP FT)                  │
├──────────┴──────────┴──────────┴─────────────────────────────────────┤
│        GuicedEE Inject · Guice Injector · ClassGraph · SPI          │
├─────────────────────────────────────────────────────────────────────┤
│     Client SPI · Lifecycle Hooks · CallScope · Representations      │
├─────────────────────────────────────────────────────────────────────┤
│             BOM · Parent POM · Services (JPMS wrappers)             │
└─────────────────────────────────────────────────────────────────────┘

These modules are not part of the GuicedEE foundation. They exist to assist projects migrating from other DI frameworks (Jakarta CDI, Spring, etc.) to the native Guice-first model. New projects should use Guice annotations and APIs directly.

GuicedEE manages a deterministic startup/shutdown lifecycle through SPI hooks:

┌─ IGuiceConfigurator         Configure ClassGraph scan
├─ IGuicePreStartup           Pre-scan initialization (health, metrics, telemetry registration)
├─ ClassGraph Scan             Discover annotated classes, SPI providers, modules
├─ IGuiceModule                Guice module binding (configure phase)
├─ Injector Creation           Build the Guice injector
├─ IGuicePostStartup           Post-injection startup (HTTP server, persistence, consumers)
│   ├─ Vert.x Web server start
│   ├─ REST route registration
│   ├─ WebSocket handler mount
│   ├─ RabbitMQ connection & consumer setup
│   ├─ Persistence unit initialization
│   ├─ Health check registration
│   └─ Metrics endpoint registration
└─ IGuicePreDestroy            Graceful shutdown (connections, exporters, ports)

Override sortOrder() on any lifecycle hook to control execution order.

Every GuicedEE module follows the same three-tier configuration pattern:

1. Annotations — @TelemetryOptions, @MetricsOptions, @HealthOptions, @RabbitConnectionOptions, @Endpoint, etc.
2. Environment variables / system properties — Override any annotation attribute at deploy time without code changes.
3. SPI hooks — Implement configurator interfaces (VertxConfigurator, VertxHttpServerOptionsConfigurator, RestClientConfigurator, etc.) for programmatic customization.

// Annotation-driven
@TelemetryOptions(serviceName = "my-service", otlpEndpoint = "http://localhost:4318")

// Environment override (no code change needed)
// TELEMETRY_SERVICE_NAME=my-service
// TELEMETRY_OTLP_ENDPOINT=http://tempo:4318

Each module includes comprehensive tests. Run everything from the root:

mvn -B -ntp test

Or test a specific module:

cd inject && mvn -B -ntp test
cd rest && mvn -B -ntp test
cd persistence && mvn -B -ntp test

Modules that require external services (databases, RabbitMQ, telemetry collectors) use Testcontainers or in-memory alternatives:

// Telemetry in-memory testing
@TelemetryOptions(useInMemoryExporters = true)

# Clone with submodules
git clone --recurse-submodules https://github.com/GuicedEE/GuicedEE.git
cd GuicedEE

# Build all modules
mvn -B -ntp clean install

# Build a specific module
cd inject && mvn -B -ntp clean install

GuicedEE modules discover each other through JPMS provides/uses directives. Register your Guice modules, lifecycle hooks, REST resources, health checks, and message consumers via ServiceLoader:

module my.app {
    requires com.guicedee.guicedinjection;

    provides com.guicedee.client.services.lifecycle.IGuiceModule
        with my.app.AppModule;
    provides com.guicedee.client.services.lifecycle.IGuicePostStartup
        with my.app.AppStartup;
}

GuicedEE provides a @CallScope for request-scoped injection (WebSocket connections, REST requests). Scoped properties are available via CallScopeProperties.

Configuration and builder classes use the Curiously Recurring Template Pattern for type-safe fluent chaining:

connection.setBaudRate(BaudRate.$9600)
          .setDataBits(DataBits.$8)
          .setParity(Parity.None)
          .connect();

Annotate packages with @Verticle to scope components to dedicated Vert.x verticles. When absent, components deploy to the default verticle managed by Guiced Vert.x.

GuicedEE is part of a larger ecosystem:

Contributions are welcome! Please follow these guidelines:

1. Fork the repository and create a feature branch
2. Follow JPMS conventions — every module must have a proper module-info.java
3. Write tests — include unit tests for new functionality
4. Use glossary-aligned names — check GLOSSARY.md in each module
5. Update documentation — keep READMEs and RULES.md current
6. Submit a PR — include a clear description of changes

All GuicedEE modules are licensed under the Apache License 2.0.

Copyright 2025 GuicedEE Contributors

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.