# Home

Source: https://guicedee.com/home

Discover

Performance

Developer

Native-Image

Persistence

CDI

Kotlin

WebAssembly

MODULAR ENTERPRISE JAVA

# E2E Modular Enterprise Java, reactive by nature.

Build reactive microservices and  moduliths  with  Google Guice ,  Vert.x 5  — all on the Java Module System. Zero XML. Zero boilerplate. Just annotate and go.

GuicedEE

Vert.x 5

Jackson 3

Java 25+

JPMS Level 3

Zero Config

MicroProfile

Get Started

IntelliJ Plugin

End-to-end Guide

Browse Modules

01 / MEASURED PERFORMANCE

## Keeping pace with the best.

Quarkus is our primary comparison because both frameworks build on Vert.x. Different application models, the same stack example: startup, OAuth, REST, GraphQL and a Firestore write/read. Explore the measurements and setup.

Explore the measurements

### Stack example startup · milliseconds

GuicedEE, Quarkus and Micronaut native · median startup through the stack example · 0.25 CPU / 500 MiB.

### Every runtime. The full picture.

Default JVM

C1 JVM

Artifact shading shows the size of the startup difference; full width is 100%. Signed percentages remain in the Startup Δ column.

Startup includes the first complete response from the stack example. Warm p50 is per-start request latency; peak memory covers the whole container. 0.25 CPU / 500 MiB. Native results use their separate cohort and remain unchanged when switching JVM profiles.

02 / DEVELOPER EXPERIENCE

## Build. Run. Keep your flow.

Small build cycles leave more room for ideas. Compare clean JVM compilation with the same application workload.

Explore the measurements

Compile

JVM package

Native build

GuicedEE modular JARs run with java -m on the full JDK, using SPI or scanner discovery. Clean offline builds with dependencies cached.

### Every build. The full picture.

Artifact shading shows the size of the package difference; full width is 100%. Signed percentages remain in the Difference column.

03 / NATIVE IMAGE

## Your Guice application. Ahead of time.

Opt-in native-image support keeps runtime injection, scopes and interceptors. SPI discovery and application reachability metadata prepare your application for a closed world.

Explore the measurements

### Peak container memory · MiB

GuicedEE, Quarkus and Micronaut native · whole-container charged memory, not heap. Support is workload-specific; JVM and application jlink remain options.

### Native runtime results

Startup is the time to the first complete stack example response; peak MiB is whole-container charged memory. Warm p50 is request latency. Results use 0.25 CPU / 500 MiB.

04 / PERSISTENCE

## Real transactions. Real evidence.

A PostgreSQL workload across 15 related entities: committed writes, joined reads, updates and rollbacks.

Explore the measurements

Startup

Read

CRUD cycle

0.25 CPU / 500 MiB per app. Startup includes the first committed 15-entity graph. CRUD cycles include three write transactions and one read. GuicedEE uses reactive stateless sessions; Quarkus and Micronaut use ORM transactions.

POSTGRESQL + HIBERNATE REACTIVE

### One transaction. An asynchronous result.

Inject a session factory, compose your writes and return a Uni. Hibernate owns the session and completes the transaction before the result is delivered.

Adapted from the benchmark store: Graph.create builds the 15 related entities, and Graph.PROJECTED_QUERY reads them back with joins. The stateless session uses explicit writes; a failed operation rolls the transaction back.

View the persistence example

```java
@Inject
private Mutiny.SessionFactory factory;

public Uni<List<Object[]>> create(long id) {
    return factory.withStatelessSession(session ->
        session.withTransaction(tx ->
            session.insertAll(0, Graph.create(id).toArray())
                .chain(() -> session.createQuery(
                    Graph.PROJECTED_QUERY, Object[].class)
                    .setParameter("id", id)
                    .getResultList())));
}

```

05 / JAKARTA CDI & CONFIGURATION

## Familiar annotations. A Guice runtime.

Application scope, injection, REST and fault tolerance use familiar Jakarta and MicroProfile annotations. The CDI bridge runs them on Guice, with the same SDK and Firestore stack example.

@ApplicationScoped

@Inject

@PostConstruct

@ConfigProperty

### CDI/config capability checks

Each CDI variant passed all 16 checks, including injected properties, environment override and Jakarta initialization.

Local validation · 15 November 2026 · one start per variant, one warmup, three measured requests. Capability evidence, not a performance ranking.

Both frameworks build on Vert.x, making Quarkus a useful comparison for the same stack example. Shared annotations include @ApplicationScoped, Jakarta @Inject, Jakarta REST endpoints, @Retry and @Timeout. GuicedEE uses a Guice-backed CDI bridge; Quarkus uses its CDI runtime. In GuicedEE, @ConfigProperty injects the value directly, without an additional @Inject. This is not a full CDI-compliance claim.

```java
@ApplicationScoped
public class Service {
    @ConfigProperty(name = "bench.upstream")
    private String upstream;

    @ConfigProperty(name = "bench.phase.diagnostics")
    private boolean diagnostics;

    @ConfigProperty(name = "bench.config.marker")
    private String configMarker;

    private Workload workload;

    @PostConstruct
    public void initialize() {
        if (!"application-properties".equals(configMarker))
            throw new IllegalStateException("application.properties was not injected");
        workload = new Workload(upstream, diagnostics);
    }
}

```

```java
bench.upstream=http://127.0.0.1:18089
bench.phase.diagnostics=false
bench.config.marker=application-properties

```

BENCH_UPSTREAM and BENCH_PHASE_DIAGNOSTICS override the dotted property keys. The /configuration endpoint verifies the file-only marker, effective upstream and completed initialization. HTTP, Vert.x and observability bootstrap settings still use the benchmark .env. Quarkus currently reads its workload settings with ConfigProvider and initializes Workload in a field initializer, rather than using this @ConfigProperty/@PostConstruct pattern.

```java
GuiceApplication.run(() -> {
    IGuiceContext.registerModule(Main.class);
});

```

```java
requires com.guicedee.cdi;
requires com.guicedee.microprofile.config;
requires com.guicedee.rest;
opens bench.guicedee.service to com.google.guice, com.guicedee.vertx;

```

Scanner and SPI cases have separate application modules. The SPI variant registers BenchmarkDiscovery through JPMS and META-INF/services. Linked images contain the complete application module graph. Native uses SPI discovery; requesting runtime scanning is explicitly rejected.

Linux validation uses 0.25 CPU / 500 MiB. Shared capability checks cover vendor SDK requests, Firestore, retries/timeouts, metrics, OpenAPI and Swagger UI. These short validation runs were performed alongside other workspace jobs; timed comparison cohorts remain separate.

Explore the benchmark repository

06 / KOTLIN SUPPORT

## Your stack. Now in Kotlin.

Kotlin across your GuicedEE stack — from REST and persistence to messaging and integrations. Keep the modules you know, with concise Kotlin code and coroutines for asynchronous work.

Constructor injection

Coroutines

Kotlin data classes

Guice handles injection. Vert.x runs your asynchronous work. GuicedEE manages coroutine scope and shutdown.

Explore Kotlin examples →

KOTLIN + GUICEDEE

### Familiar endpoints. Suspending services.

```kotlin
@Path("/hello")
class HelloResource @Inject constructor(
    private val coroutines: GuicedCoroutines,
    private val service: GreetingService
) {
    @GET
    fun hello(): Future<Greeting> =
        coroutines.future {
            service.greet("Kotlin")
        }
}

```

Call a suspending service inside coroutines.future { … } and return a Vert.x Future through the normal REST pipeline.

07 / WEBASSEMBLY

Experimental

## Guice meets WebAssembly.

Guice injection and outbound HTTP are running in standalone WASI probes. We're exploring portable Java workloads for server and edge runtimes.

Next: typed REST clients and JWebMP rendering. A small, useful profile is taking shape.

Explore the WebAssembly preview →

RUNNING TODAY

### Two working foundations.

### Guice injection

Providers, singletons and custom scopes — including cleanup and failure recovery.

### Outbound HTTP

Real GET/POST requests, deadlines and resource cleanup through standard WASI HTTP.

Independent probes today. Connecting the application workflow is next.

‹

›

How it works

## Three steps to modular applications

No code generators, no runtime reflection hacks, no XML plumbing.

### 1. Add a dependency

Import the BOM, pick the modules you need, and your build tool handles the rest. Maven, Gradle, or any Java compiler — no plugin zoo, no starter generators.

One BOM, zero surprises.

### 2. Write your code

Use standard annotations —  @Path ,  @Inject ,  @Liveness ,  @ConfigProperty . GuicedEE discovers everything via  ClassGraph  and wires it through  Guice .

Standards you already know.

### 3. Run it

Call one line and your HTTP server, REST routes, WebSocket handlers, and persistence units all light up automatically.

One line to launch.

IntelliJ Plugin

## Start your next project in IntelliJ IDEA

From idea to a modular application, with the Guiced project wizard.

Create a GuicedEE application right inside IntelliJ IDEA. Choose your modules and let the project wizard generate your  pom.xml ,  module-info.java  and application bootstrap.

Get the IntelliJ plugin

Plugin setup guide

AI skills marketplace

## Build with your IDE. Guide your AI.

Reusable development skills, ready to install in your project.

Give your AI assistant the same patterns your team uses. Install individual skills for GuicedEE, JWebMP, EntityAssist and ActivityMaster with Agent Package Manager.

```java
irm https://aka.ms/apm-windows | iex
```

```java
curl -sSL https://aka.ms/apm-unix | sh
```

Open a new terminal after installing APM, then run these commands in your application project.

```java
apm --version
apm marketplace add GuicedEE/ai-rules
apm install guicedee-inject@guicedee-ai-rules

```

Browse the AI skills marketplace

Install APM

Foundations

## What makes GuicedEE different

A cohesive platform where Guice DI, Vert.x reactivity, and JPMS modularity work together — not against each other.

### Guice-first DI

All lifecycle, routing, persistence, messaging, and telemetry are wired through a single  Guice  injector.  @Inject  works everywhere — in REST resources, health checks, WebSocket receivers, even in event bus consumers.

One injector to rule them all.

### Vert.x 5 reactive core

Non-blocking HTTP, WebSockets, event bus, SQL clients, RabbitMQ, Kafka, and IBM MQ — all on the  Vert.x  event loop with  Mutiny   Uni / Multi  support throughout the stack.

Built for modern runtime constraints.

### JPMS Level 3

Every module ships a proper  module-info.java  with explicit  exports ,  requires ,  provides , and  uses . Build JLink and JPackage distributables confidently.

Real modules, not automatic modules.

### SPI + ClassGraph

Modules, lifecycle hooks, REST resources, health checks, consumers — everything is discovered automatically at startup. No manual registration, no classpath scanning hacks.

Convention over configuration, done right.

### Pure environment variable config

Every runtime setting — ports, pool sizes, credentials, feature flags — resolves from  environment variables  or system properties. No  application.yml , no  bootstrap.properties , no secret files to manage. 12-factor by default, cloud-native from day one.

Your deployment IS your configuration.

### Config files are optional

Need  microprofile-config.properties ? It works. Prefer  persistence.xml ? Also works. But you never  need  them — every value can be set via annotations, code, or env vars. Config files are an escape hatch, not a requirement.

Zero files to deploy if you choose.

### One language, end to end

Your REST endpoints, persistence, messaging, health checks, security, configuration, and deployment logic — all in  Java . No YAML to debug, no XML to lint, no JSON schemas to validate. Your IDE catches every error at compile time.

Type-safe from editor to production.

Modular by design

## Ship only what you need

A composable stack where you build up your runtime — never exclude down from a kitchen-sink starter.

```xml
<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>com.guicedee</groupId>
            <artifactId>guicedee-bom</artifactId>
            <version>2.6.0</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

<!-- Then just add what you need — no versions required -->
<dependencies>
    <dependency>
        <groupId>com.guicedee</groupId>
        <artifactId>rest</artifactId>
    </dependency>
    <dependency>
        <groupId>com.guicedee</groupId>
        <artifactId>persistence</artifactId>
    </dependency>
</dependencies>
```

```groovy
// Import the BOM — all versions aligned
dependencies {
    implementation platform('com.guicedee:guicedee-bom:2.6.0')

    // Then just add what you need — no versions required
    implementation 'com.guicedee:rest'
    implementation 'com.guicedee:persistence'
}
```

### Build it up, never exclude down

Start with  inject  and add only what you need:  rest ,  persistence ,  websockets ,  rabbitmq ,  kafka ,  ibmmq . Each module is self-contained with its own JPMS descriptor.

Your runtime is only as big as you choose.

### JLink / JPackage ready

Every artifact is JPMS Level 3 — build custom JRE images with only the modules your app needs. Deploy as a native installer or minimal Docker image.

From 500 MB JRE to 40 MB custom runtime.

### One BOM, all versions aligned

Import  guicedee-bom  in your  dependencyManagement . All 20+ modules are version-aligned and tested together.

No dependency conflicts, ever.

### Grouped library wrappers

Third-party libraries (Hibernate, Jackson, Vert.x) are repackaged with proper  module-info.java  descriptors. The descriptors are trimmed to owned packages and necessary dependency edges, keeping the module path clean and transitive requirements predictable.

Over 50 focused JPMS-wrapped service modules.

Module catalog

## Drop-in capabilities — add a dependency, get a feature

Each integration ships as a micro-module with its own module-info.java. Zero side effects.

### REST (JAX-RS)

@Path / @GET / @POST  routes auto-registered on Vert.x Router via  ClassGraph . Full parameter binding.

### REST (JAX-RS)

View module →

RFC 6455 with call-scoped connections, action-based routing, and group broadcasting.

### WebSockets

View module →

Hibernate Reactive 4.5 and ORM 7.4  +  Mutiny.SessionFactory . Multi-database, env-var driven.

### Persistence

View module →

Annotate connections, exchanges, queues, consumers, and publishers. Auto-recovery included.

### RabbitMQ

View module →

Annotation-driven Apache Kafka with Vert.x Kafka Client.  @KafkaConnectionOptions ,  @KafkaTopicDefinition , consumers, and publishers.

### Kafka

View module →

Annotation-driven IBM MQ via JMS client.  @IBMMQConnectionOptions ,  @IBMMQQueueDefinition , consumers, and publishers.

### IBM MQ

View module →

@Liveness ,  @Readiness ,  @Startup  checks at  /health  as JSON.

### Health

View module →

Dropwizard + MicroProfile.  @Counted ,  @Timed , Prometheus endpoint.

### Metrics

View module →

OpenTelemetry tracing with  @Trace , OTLP export, Log4j2 correlation.

### Telemetry

View module →

OpenAPI 3.1 spec at  /openapi.json  +  /openapi.yaml  from JAX-RS annotations.

### OpenAPI

View module →

SPI-driven schema at  /graphql  with HTTP + WebSocket + optional  GraphiQL  IDE.

### GraphQL

View module →

Browsable UI at  /swagger/  with zero code. Just add the dependency.

### Swagger UI

View module →

@ConfigProperty  injection from env vars, system props, and properties files.

### Config

View module →

@Retry ,  @CircuitBreaker ,  @Timeout ,  @Bulkhead  via Guice AOP.

### Fault Tolerance

View module →

SOAP/JAX-WS via Apache CXF.  @WebService  endpoints, WS-Security.

### Web Services

View module →

@ApplicationScoped ,  @RequestScoped ,  BeanManager  — all mapped to Guice.

### CDI Bridge

View module →

### Serial (Cerial)

@Named  port injection, auto-reconnect, idle monitoring, health reporting.

### Serial (Cerial)

View module →

Zero-file-based-config philosophy

## No XML. No YAML. No boilerplate.

Configuration lives in your code, not in a file tree. Override anything at deploy time with environment variables. You can of course still use configuration if you desire

Every GuicedEE module follows the same philosophy: sensible defaults out of the box, annotations for customization, and environment variables for deployment overrides. You'll never touch an XML configuration file (unless you want MicroProfile Config properties files).

```java
// ❌ Traditional framework:
//   - application.yml
//   - beans.xml
//   - web.xml
//   - persistence.xml
//   - logback.xml
//   - 47 starter dependencies
//   - A code generator to set it all up
//   - A dev console for management

// ✅ GuicedEE:
GuiceApplication.run(() -> {});
// That's it. Your REST endpoints, health checks,
// persistence units, and WebSocket handlers are live.
```

### No persistence.xml?

Configure your database with a  DatabaseModule . GuicedEE creates the persistence unit from supplied properties, merged with  persistence.xml  if provided.

Properties + persistence.xml = merged configuration.

### No web.xml ever

The  Vert.x  HTTP server starts automatically when you add the 'web' module. Port, TLS, body limits — all controlled via environment variables or SPI hooks.

HTTP_PORT=8080, done.

### No beans.xml

Guice  doesn't need one. GuicedEE discovers your modules, bindings, and lifecycle hooks via JPMS  ServiceLoader  and  ClassGraph . Since  Guice  supports JIT (Just-In-Time) binding, you can often skip explicit registration altogether.

SPI is the configuration.

### No application.yml

Keep it simple and cozy—no more jumping between  application.yml  and  cloud-config.yml . Use  @ConfigProperty  from MicroProfile Config for external properties, and override anything with env vars at deploy time.

Unified configuration, zero duplication.

See the code

## Real examples, not toy demos

Every snippet below runs in production today. Copy, paste, ship.

### REST endpoint — standard Jakarta annotations

```java
@Path("/api/products")
public class ProductResource {

    @Inject
    private ProductService products;

    @GET
    @Produces(MediaType.APPLICATION_JSON)
    public List<Product> list() {
        return products.findAll();
    }

    @POST
    @Consumes(MediaType.APPLICATION_JSON)
    @Produces(MediaType.APPLICATION_JSON)
    public Product create(Product product) {
        return products.save(product);
    }
}
```

Routes are discovered by  ClassGraph  at startup and registered on the  Vert.x Router . No registration code needed — just annotate and ship. Common JAX-RS syntax for simplicity

### Health checks — MicroProfile standard

```java
@Liveness
public class DatabaseHealth implements HealthCheck {

    @Inject
    private Mutiny.SessionFactory sessionFactory;

    @Override
    public HealthCheckResponse call() {
        return HealthCheckResponse.named("database")
            .status(sessionFactory != null)
            .build();
    }
}
// Exposed at /health/live automatically
```

### WebSockets — action-based routing

```java
public class ChatReceiver
    implements IWebSocketMessageReceiver<Void, ChatReceiver> {

    @Override
    public Set<String> messageNames() {
        return Set.of("chat");
    }

    @Override
    public Uni<Void> receiveMessage(
            WebSocketMessageReceiver<?> message) {
        // broadcast to all group members
        return IGuicedWebSocket.broadcastGroup(
            message.getData().toString());
    }
}
```

### Distributed tracing — just add @Trace

```java
@TelemetryOptions(
    serviceName = "order-service",
    otlpEndpoint = "http://tempo:4318"
)
public class OrderService {

    @Trace
    public Uni<Order> placeOrder(
            @SpanAttribute("customer.id") String customerId) {
        // This method is automatically traced.
        // Spans are exported to Tempo/Jaeger via OTLP.
        return processOrder(customerId);
    }
}
```

REST services

## Jakarta REST on Vert.x 5 — zero registration, full power

Standard @Path annotations, Guice-injected resources, reactive returns, CORS, security, and a typed REST client — all auto-discovered.

GuicedEE's REST module adapts standard Jakarta REST (JAX-RS) annotations to the  Vert.x 5 Router . Routes are discovered at startup by  ClassGraph , resource instances come from the  Guice  injector, and methods can return plain values,  Uni<T> , or  Future<T> . CORS, security, and exception mapping all work via annotations and SPI — no  web.xml , no  Application  subclass, no registration code.

```java
@Path("/api/orders")
@Cors(allowedOrigins = {"https://app.example.com"},
      allowedMethods = {"GET", "POST"},
      allowCredentials = true)
public class OrderResource {

    @Inject
    private OrderService orderService;

    @GET
    @Produces(MediaType.APPLICATION_JSON)
    public Uni<List<Order>> listOrders(
            @QueryParam("status") String status,
            @QueryParam("page") @DefaultValue("1") int page) {
        return orderService.findByStatus(status, page);
    }

    @POST
    @Consumes(MediaType.APPLICATION_JSON)
    @Produces(MediaType.APPLICATION_JSON)
    @RolesAllowed("order:write")
    public Uni<Response> createOrder(OrderRequest request) {
        return orderService.create(request)
            .onItem().transform(order ->
                Response.status(201)
                    .entity(order)
                    .build());
    }

    @GET @Path("/{id}")
    @Produces(MediaType.APPLICATION_JSON)
    public Uni<Order> getOrder(@PathParam("id") String id) {
        return orderService.findById(id);
    }
}
```

### Zero-config routes

@Path ,  @GET ,  @POST ,  @PUT ,  @DELETE ,  @PATCH  —  OperationRegistry  scans  ClassGraph  results and maps them to  Vert.x  routes at startup. No registration code.

### Full parameter binding

@PathParam ,  @QueryParam ,  @HeaderParam ,  @CookieParam ,  @FormParam ,  @MatrixParam ,  @BeanParam  — all Jakarta REST parameter annotations are supported.

### Reactive returns

Return  Uni<T> ,  Future<T> , or plain values. Reactive types run on the event loop; blocking methods are dispatched to a worker pool automatically.

### @Cors annotation

Apply CORS at class or method level. Configures allowed origins, methods, headers, credentials, and max age. Override any value with  REST_CORS_*  env vars.

### RestInterceptor SPI

Hook into request start/end for logging, metrics, or cross-cutting concerns. Implement  onStart()  and  onEnd()  — both return  Future<Boolean> .

### ExceptionMapper

Standard  ExceptionMapper  SPI with cause-chain traversal. Map exceptions to HTTP status codes and error response bodies.

### @Verticle worker pools

Resources in  @Verticle -annotated packages automatically use their named worker pool. Isolate API groups with different threading and pool sizes.

### JAX-RS Response

Return  Response  for full control over status codes, headers, and entity bodies. Works alongside reactive returns.

### REST Client — annotation-driven outbound calls

Need to call external APIs? Declare an  @Endpoint  on a  RestClient<Send, Receive>  field, add  @Named , and inject. URL, method, authentication, timeouts, and connection options are all annotation-driven. Every call returns  Uni<Receive>  for fully reactive composition.

```java
public class PaymentService {

    // Define the endpoint once — URL, auth, and timeouts
    @Endpoint(url = "https://api.stripe.com/v1/charges",
              method = "POST",
              security = @EndpointSecurity(
                  value = SecurityType.Bearer,
                  token = "${STRIPE_SECRET_KEY}"),
              options = @EndpointOptions(
                  connectTimeout = 5000,
                  readTimeout = 10000))
    @Named("stripe-charge")
    private RestClient<ChargeRequest, ChargeResponse> chargeClient;

    public Uni<ChargeResponse> charge(ChargeRequest req) {
        return chargeClient.send(req);
    }
}

// Inject the same client anywhere by name — no @Endpoint needed:
public class RefundService {
    @Inject @Named("stripe-charge")
    private RestClient<ChargeRequest, ChargeResponse> chargeClient;
}
```

```java
# Enable/disable CORS (annotation values are defaults)
REST_CORS_ENABLED=true
REST_CORS_ALLOWED_ORIGINS=https://app.example.com,https://admin.example.com
REST_CORS_ALLOWED_METHODS=GET,POST,PUT,DELETE,PATCH,OPTIONS
REST_CORS_ALLOWED_HEADERS=Content-Type,Authorization,X-Request-Id
REST_CORS_ALLOW_CREDENTIALS=true
REST_CORS_MAX_AGE=3600
```

Security

## Standard annotations, pluggable authentication, secrets in env vars

Jakarta @RolesAllowed, Vert.x auth handlers, @EndpointSecurity for outbound calls, and HTTPS — all without config files.

Security in GuicedEE uses standard Jakarta security annotations with pluggable  Vert.x  authentication and authorization handlers. No  security.xml , no realm configuration files — annotate your resources and plug in your auth provider via SPI.

```java
@Path("/api/admin")
@RolesAllowed({"admin", "super-admin"})
public class AdminResource {

    @GET @Path("/users")
    @Produces(MediaType.APPLICATION_JSON)
    public Uni<List<User>> listUsers() {
        return userService.findAll();  // requires admin role
    }

    @DELETE @Path("/users/{id}")
    @RolesAllowed("super-admin")  // method overrides class
    public Uni<Void> deleteUser(@PathParam("id") String id) {
        return userService.delete(id);
    }

    @GET @Path("/health")
    @PermitAll  // no auth needed for this endpoint
    public String health() { return "OK"; }
}
```

### @RolesAllowed

Standard Jakarta annotation. Apply at class or method level. GuicedEE's  SecurityHandler  checks roles against the authenticated  Vert.x User .

### @PermitAll / @DenyAll

Allow or deny all access at class or method level. Method-level annotations override class-level ones.

### Pluggable AuthenticationHandler

Call  SecurityHandler.setDefaultAuthenticationHandler()  with any  Vert.x AuthenticationHandler  — JWT, OAuth2, Basic, or your own custom handler.

### Pluggable AuthorizationProvider

Plug in role/permission resolution via  SecurityHandler.setDefaultAuthorizationProvider() . Works with  Vert.x 's built-in providers or your own.

### REST Client @EndpointSecurity

Bearer, JWT, Basic, and ApiKey authentication on outbound REST calls. Credentials support  ${ENV_VAR}  placeholders — secrets never touch source code.

### HTTPS / TLS

JKS and PKCS#12 keystores auto-detected by file extension. Set  HTTPS_ENABLED=true ,  HTTPS_KEYSTORE , and  HTTPS_KEYSTORE_PASSWORD .

### Call-scoped isolation

Each HTTP request runs in a  Guice CallScope  with its own  CallScopeProperties . User context, request data, and scoped services are isolated per request.

### CORS security

@Cors  annotation with env var overrides for origins, methods, headers, credentials, and max age. Applied per-class, per-method, or globally via environment variables.

```java
// In your IGuicePostStartup hook or module:
public class SecuritySetup implements IGuicePostStartup<SecuritySetup> {

    @Override
    public List<Uni<Boolean>> postLoad() {
        // Vert.x 5 JWT auth
        var jwtAuth = JWTAuth.create(vertx, new JWTAuthOptions()
            .addPubSecKey(new PubSecKeyOptions()
                .setAlgorithm("RS256")
                .setBuffer(publicKey)));

        SecurityHandler.setDefaultAuthenticationHandler(
            JWTAuthHandler.create(jwtAuth));

        return List.of(Uni.createFrom().item(true));
    }
}
```

```java
// Bearer token from environment variable
@Endpoint(url = "https://api.example.com/v2/data",
          security = @EndpointSecurity(
              value = SecurityType.Bearer,
              token = "${API_TOKEN}"))
@Named("secure-api")
private RestClient<Request, Response> secureClient;

// Basic auth
@Endpoint(url = "https://legacy.example.com/soap",
          security = @EndpointSecurity(
              value = SecurityType.Basic,
              username = "${LEGACY_USER}",
              password = "${LEGACY_PASS}"))
@Named("legacy-api")
private RestClient<Request, Response> legacyClient;

// API Key in custom header
@Endpoint(url = "https://maps.googleapis.com/maps/api",
          security = @EndpointSecurity(
              value = SecurityType.ApiKey,
              apiKey = "${GOOGLE_API_KEY}",
              apiKeyHeader = "X-Goog-Api-Key"))
@Named("google-maps")
private RestClient<Request, Response> mapsClient;
```

```java
# Enable HTTPS alongside HTTP
HTTPS_ENABLED=true
HTTPS_PORT=8443
HTTPS_KEYSTORE=/etc/ssl/keystore.p12
HTTPS_KEYSTORE_PASSWORD=${KEYSTORE_PASSWORD}

# Keystore format is auto-detected by extension:
#   .jks       → Java KeyStore
#   .p12 .pfx  → PKCS#12
#   .p8        → PKCS#8

# Generate a dev keystore:
# keytool -genkey -alias dev -keyalg RSA -keysize 2048 \
#   -validity 365 -keystore keystore.jks -storepass changeit
```

Vert.x deployment

## HTTP/HTTPS servers, verticles, and SPI extension points

Three SPI hooks to customize the server, per-verticle isolation for API groups, and environment-driven configuration.

The  Vert.x 5  HTTP server, router, and verticle infrastructure are fully managed by GuicedEE. Three SPI extension points let you customize every layer. Per-verticle isolation means you can run different API groups on separate worker pools with their own threading models.

```java
// package-info.java — isolate the payments API
@Verticle(value = "payments-pool",
          workerPoolSize = 16,
          maxWorkerExecuteTime = 30,
          maxWorkerExecuteTimeUnit = TimeUnit.SECONDS,
          capabilities = {Capabilities.Rest, Capabilities.Persistence})
package com.example.payments;

import com.guicedee.vertx.spi.Verticle;
import com.guicedee.vertx.spi.Verticle.Capabilities;
import java.util.concurrent.TimeUnit;

// Any @Path resource in com.example.payments gets its own
// worker pool and sub-router — isolated from other API groups.
```

### Auto-start HTTP/HTTPS

VertxWebServerPostStartup  runs as  IGuicePostStartup . Creates HTTP and HTTPS servers from environment config. Compression level 9, TCP keepalive, and configurable limits.

### VertxHttpServerOptionsConfigurator

SPI to customize  HttpServerOptions  before servers are created. Set idle timeouts, buffer sizes, ALPN, or any  Vert.x  option.

### VertxHttpServerConfigurator

SPI to configure  HttpServer  instances after creation. Add connection handlers, WebSocket upgrade logic, or metrics hooks.

### VertxRouterConfigurator

SPI to add routes and middleware to the  Router . Sorted by  sortOrder()  — infrastructure runs first, application routes later.

### @Verticle annotation

Annotate a package to create an isolated verticle with its own worker pool, threading model, instance count, and HA settings.

### Per-verticle sub-routers

VertxRouterConfigurator  implementations in  @Verticle  packages get their own  Router , mounted as a sub-router on the main  Router .

### Capabilities enum

@Verticle can declare capabilities: Rest, RabbitMQ, Kafka, IBM MQ, Web, Telemetry, Persistence, Sockets, OpenAPI, Swagger, and more. Each maps to its module package.

### Startup flow control

IGuicePostStartup  hooks use  sortOrder()  for deterministic startup. Web server starts early (MIN_VALUE + 500), your routes register after.

```java
// Customize server options before creation
public class MyServerOptions
        implements VertxHttpServerOptionsConfigurator {
    @Override
    public HttpServerOptions builder(HttpServerOptions opts) {
        opts.setIdleTimeout(60);
        opts.setMaxWebSocketFrameSize(1048576);
        return opts;
    }
}

// Register in module-info.java:
provides VertxHttpServerOptionsConfigurator
    with MyServerOptions;
```

```java
public class ApiMiddleware
        implements VertxRouterConfigurator<ApiMiddleware> {

    @Override
    public Router builder(Router router) {
        // Request logging
        router.route("/api/*").handler(ctx -> {
            log.info("{} {}", ctx.request().method(),
                              ctx.request().path());
            ctx.next();
        });

        // Static files
        router.route("/static/*")
            .handler(StaticHandler.create("webroot"));

        return router;
    }

    @Override
    public Integer sortOrder() {
        return 100;  // infrastructure runs early
    }
}
```

```java
# HTTP server
HTTP_ENABLED=true
HTTP_PORT=8080

# HTTPS server
HTTPS_ENABLED=true
HTTPS_PORT=8443
HTTPS_KEYSTORE=/etc/ssl/keystore.p12
HTTPS_KEYSTORE_PASSWORD=changeit

# Body handler
VERTX_MAX_BODY_SIZE=524288000   # 500 MB default

# Server defaults (applied before SPI configurators):
# Compression: enabled, level 9
# TCP keepalive: true
# Max header/chunk/form size: 65536 bytes
# Max form fields: unlimited (-1)
```

MicroProfile native

## Enterprise standards, Guice-powered

Eclipse MicroProfile specifications implemented through SPI discovery and Guice injection.

Eclipse MicroProfile provides an additive support mechanism, implemented through  Guice  integration. If you know the MicroProfile annotations, you already know GuicedEE.

```java
// META-INF/microprofile-config.properties
// messaging.enabled=true
// messaging.bootstrap.servers=localhost:9092

public class MessagingService {

    @ConfigProperty(name = "messaging.enabled",
                    defaultValue = "true")
    boolean enabled;

    @ConfigProperty(name = "messaging.bootstrap.servers")
    String bootstrapServers;
}

// Override at deploy time:
// MESSAGING_ENABLED=false
// MESSAGING_BOOTSTRAP_SERVERS=kafka-prod:9092
```

### MicroProfile Config

Inject configuration with  @ConfigProperty . Sources: environment variables (highest priority), system properties, and  META-INF/microprofile-config.properties . Profile support included.

SmallRye Config under the hood.

### MicroProfile Health

Standard  @Liveness ,  @Readiness , and  @Startup  health checks. Discovered by  ClassGraph  and exposed as  /health  JSON endpoints on the  Vert.x Router .

Kubernetes-ready out of the box.

### MicroProfile Metrics

@Counted ,  @Timed ,  @Gauge  — backed by Dropwizard Metrics with a Prometheus scrape endpoint. Add the module and your metrics are live.

Prometheus + Graphite reporting.

### MicroProfile Fault Tolerance

@Retry ,  @CircuitBreaker ,  @Timeout ,  @Bulkhead ,  @Fallback  — resilience patterns wired through  Guice  AOP interception.

Production resilience, zero effort.

### MicroProfile OpenAPI

OpenAPI 3.1 spec generation from your JAX-RS annotations. Served at  /openapi.json  and  /openapi.yaml  with zero configuration.

Swagger UI auto-mounts at /swagger/.

### OpenTelemetry

@Trace  and  @SpanAttribute  for distributed tracing. OTLP export to Tempo, Jaeger, or any collector.  Uni -aware — spans complete when the reactive chain resolves.

Correlated logs via Log4j2 appender.

Ship as JLink artifacts

## Custom runtimes in minimal Docker containers

JPMS Level 3 means every module participates in JLink. Build a custom JRE, copy it into a distroless container, and deploy instantly.

Because every GuicedEE module is JPMS Level 3 with explicit  module-info.java  descriptors, you can use the  moditect-maven-plugin  to create a custom Java runtime that contains only the modules your application actually uses. The result is a self-contained image — no external JDK required at deploy time — that ships in a minimal Docker container.

```xml
<!-- pom.xml — moditect-maven-plugin creates the JLink image -->
<plugin>
    <groupId>org.moditect</groupId>
    <artifactId>moditect-maven-plugin</artifactId>
    <executions>
        <execution>
            <id>add-module-infos</id>
            <phase>none</phase>
            <configuration combine.self="override">
                <skip>true</skip>
            </configuration>
        </execution>
        <execution>
            <id>create-runtime-image</id>
            <phase>package</phase>
            <goals>
                <goal>create-runtime-image</goal>
            </goals>
            <configuration>
                <modulePath>
                    <path>${project.build.directory}/libs</path>
                    <path>${project.build.directory}/${project.build.finalName}.jar</path>
                </modulePath>
                <modules>
                    <module>my.service</module>
                </modules>
                <jarInclusionPolicy>NONE</jarInclusionPolicy>
                <launcher>
                    <name>myservice</name>
                    <module>my.service/com.example.Main</module>
                </launcher>
                <noHeaderFiles>true</noHeaderFiles>
                <noManPages>true</noManPages>
                <stripDebug>true</stripDebug>
                <outputDirectory>
                    ${project.build.directory}/jlink-image
                </outputDirectory>
            </configuration>
        </execution>
    </executions>
</plugin>

# 1. Build the JLink custom runtime
mvn clean package

# 2. Package into a minimal Docker image
# Dockerfile:
#   FROM gcr.io/distroless/base-nossl-debian12
#   COPY target/jlink-image /app/jrt
#   ENTRYPOINT ["/app/jrt/bin/myservice"]
docker build -t my-service:latest .

# 3. Push and deploy
docker push registry.example.com/my-service:latest
```

```groovy
// build.gradle — moditect Gradle plugin creates the JLink image
plugins {
    id 'org.moditect.gradleplugin' version '1.3.0.Final'
}

moditect {
    createRuntimeImage {
        modulePath = [
            file("${buildDir}/libs"),
            tasks.jar.archiveFile
        ]
        modules = ['my.service']
        jarInclusionPolicy = 'NONE'
        launcher {
            name = 'myservice'
            module = 'my.service/com.example.Main'
        }
        noHeaderFiles = true
        noManPages = true
        stripDebug = true
        outputDirectory = file("${buildDir}/jlink-image")
    }
}

// 1. Build the JLink custom runtime
// gradle build

// 2. Package into a minimal Docker image
// Dockerfile:
//   FROM gcr.io/distroless/base-nossl-debian12
//   COPY build/jlink-image /app/jrt
//   ENTRYPOINT ["/app/jrt/bin/myservice"]
// docker build -t my-service:latest .

// 3. Push and deploy
// docker push registry.example.com/my-service:latest
```

### Native JREs

Use the  moditect-maven-plugin  with  create-runtime-image  to build a trimmed Java runtime. Only the modules your app requires are included — everything else is stripped.

From ~500 MB JDK to ~40 MB custom image.

### JPackage installers

Use  jpackage  to wrap your JLink image into a native installer — MSI on Windows, DEB/RPM on Linux, DMG on macOS. Zero JDK installation required by end users.

Real desktop/server installers.

### Minimal Docker containers

Copy the JLink image into a scratch or distroless base. No JDK layer, no package manager, no shell — just your application and its runtime. Cloud Run, Kubernetes, and ECS ship these instantly.

~40-60 MB Docker images.

### Incredible startup time on JRT

JLink custom runtimes utilize the module path, and the JRT filesystem. Combined with  Vert.x 's non-blocking boot and  ClassGraph 's fast scanning, REST services run on a reactive, application-linked runtime.

Cold-start friendly for serverless.

### CI/CD pipeline integration

Your CI builds the JLink image and pushes it to a container registry. Terraform / Cloud Run / Kubernetes deploys reference the JLink image — never a fat JAR on a generic JDK (But you can if you want to...).

No JARs in production.

### 50+ JPMS service wrappers

Third-party libraries (Hibernate, Jackson, Vert.x, Netty, Log4j2) ship as proper JPMS modules with  exports ,  requires , and  provides . JLink resolves the entire dependency graph cleanly.

No automatic-module hacks.

```java
# Check what your app actually uses at runtime
java --show-module-resolution -m my.service

# Or validate providers with jlink directly
jlink \
  --module-path target/libs \
  --add-modules my.service \
  --suggest-providers
```

Tip:  You can also invoke  jlink  directly from the command line to build the runtime image:  jlink --module-path target/libs --add-modules my.service --output target/jlink-image --strip-debug --no-header-files --no-man-pages . The moditect plugin wraps this into your Maven build lifecycle so it runs automatically during  mvn package .

Every GuicedEE module declares its SPI  provides  and  uses  directives in  module-info.java , so JLink can resolve the full service graph automatically. No reflection hacks, no runtime classpath surprises. What you see in  module-info.java  is exactly what ships.

Cloud-aware logging

## One env var switches to production-ready JSON

CLOUD=true — that's it. Every log line becomes structured JSON for your aggregator. Locally, you get colorized output.

GuicedEE ships production-ready logging out of the box. Locally, you get colorized, human-readable console output with highlighting. In the cloud, set one environment variable and every log line switches to compact JSON — ready for ingestion by CloudWatch, Stackdriver, Loki, Datadog, or any log aggregator. This is a programmatic alternative to XML configuration — existing  log4j2.xml  and  log4j2.properties  files, standard Log4j2 API calls, and Lombok's  @Log4j2  annotation all continue to work exactly as expected. GuicedEE simply gives you a code-first option that integrates with environment variables and the DI lifecycle.

```java
# Local development — colorized, human-readable:
[2026-03-06 14:23:01.123] [c.e.myservice.OrderService ] [vert.x-eventloop-0 ] [INFO ] - Order 42 placed

# Cloud deployment — set one env var:
# CLOUD=true

# Same log line becomes structured JSON:
{"instant":{"epochSecond":1741270981,"nanoOfSecond":123000000},
 "thread":"vert.x-eventloop-0",
 "level":"INFO",
 "loggerName":"com.example.myservice.OrderService",
 "message":"Order 42 placed",
 "contextMap":{"traceId":"abc123","spanId":"def456"}}
```

### CLOUD=true → JSON logs

Set the  CLOUD  environment variable to 'true' and all console appenders switch to compact JSON layout automatically. No  log4j2.xml  required, no code changes — it's built into the  GuiceContext  static initializer.

One env var for production logging.

### Highlighted local output

When CLOUD is not set, console output uses ANSI-highlighted patterns with colored log levels, fixed-width logger names, and thread identifiers. Debug and trace are easy to spot.

Developer-friendly by default.

### Rolling file appenders

LogUtils.addFileRollingLogger()  creates daily/size-based rolling appenders. 100 MB per file, 30 files retained, automatic rollover. In cloud mode, file loggers are skipped — only console JSON is emitted.

Zero-config file rotation.

### @InjectLogger

Inject named Log4j2 loggers into any Guice-managed class with  @InjectLogger("name") . No static Logger fields, no LoggerFactory calls. The  Log4JTypeListener  wires them automatically.

Clean, testable logging.

### Log4JConfigurator SPI

Need custom appenders or filters? Implement  Log4JConfigurator  and register via  ServiceLoader . Your configurator runs during static initialization — before any application code logs.

Full programmatic control.

### Dynamic layout switching

Call  GuiceContext.setConsoleLayout(ConsoleLayoutOption.JSON)  at any time to switch all console appenders between CURRENT, FIXED, HIGHLIGHT, and JSON layouts. No restart required.

Runtime control.

### Log level via environment

Set  LOG_LEVEL ,  GUICEDEE_LOG_LEVEL , or  guicedee.log.level  to control the root logger level. Or use  DEBUG=true  /  TRACE=true  for quick toggle. All resolved at startup, overridable at deploy time.

No log4j2.xml needed.

### OpenTelemetry log correlation

When the telemetry module is active, an OpenTelemetry Log4j2 appender is auto-registered. Log records are correlated with active trace spans and exported via OTLP alongside your traces.

Logs + traces in one view.

```java
# Switch to JSON for cloud log aggregators
CLOUD=true

# Control the root log level (choose one)
LOG_LEVEL=INFO
GUICEDEE_LOG_LEVEL=DEBUG

# Quick toggles
DEBUG=true
TRACE=true

# Programmatic switch at runtime (no restart)
GuiceContext.setConsoleLayout(ConsoleLayoutOption.JSON);
GuiceContext.setDefaultLogLevel(Level.DEBUG);
```

The logging system is configured in the  GuiceContext  static initializer — before any  Guice  module loads. When  CLOUD=true , stdout receives DEBUG/INFO as JSON, stderr receives WARN/ERROR/FATAL as JSON, and the rolling file appender is skipped entirely. This means your container only needs to capture stdout/stderr — no log volume mounts, no sidecar log shippers. If you already have a  log4j2.xml  or  log4j2.properties  on your classpath, Log4j2 will honour it as usual — the programmatic configuration only applies when no existing config file is detected.

For developers

## Open source with practical guardrails

Clear patterns, comprehensive testing, and transparent code give teams the controls they need.

```java
module my.app {
    requires com.guicedee.guicedinjection;
    requires com.guicedee.vertx.web;
    requires com.guicedee.rest;
    requires com.guicedee.persistence;
    requires com.guicedee.health;

    // Wire your Guice module + lifecycle hooks via SPI
    provides com.guicedee.client.services.lifecycle.IGuiceModule
        with my.app.AppModule;
    provides com.guicedee.client.services.lifecycle.IGuicePostStartup
        with my.app.AppStartup;
}
```

### AI skills marketplace

Install reusable GuicedEE, JWebMP, EntityAssist and ActivityMaster guidance with Agent Package Manager (APM). Choose the skills your project needs from the AI Rules catalog.

Consistent patterns for AI-assisted development.

### End-to-end testable

Test the entire stack with JUnit 5 + Jupiter. Health checks, REST endpoints, persistence — all verifiable in CI.

In-memory telemetry exporters for tracing tests.

### Code-first always

No XML, no YAML, no JSON config. Your configuration is your code. Override at deploy time with environment variables.

Configuration lives where you can test it.

### Active community

GitHub Issues and Discussions for support. PRs welcome. All modules are Apache 2.0 licensed.

Open source with practical guardrails.

## Ready to Build?

From zero to production microservice — with zero XML.

Stop wrestling with configuration files and boilerplate. Build reactive microservices with the annotations and patterns you already know.

Get Started

Capabilities

View on GitHub

Browse All Examples

