Dropwizard Guicey

dropwizard-guicey provides Google Guice integration for Dropwizard applications. It is compiled for java 11 and is compatible with java 11 through java 21.

Main Features

• Auto configuration: Uses classpath scanning and Guice bindings.
• Yaml config bindings: Bind configuration values from YAML files by path or unique sub-objects.
• Web support: Advanced integration for web-related components.
• Console reporting: Automatically detects and prints installed extensions to the console.
• Test support: Custom JUnit and Spock extensions with abilities to disable or override application logic.
• Extensibility: Rich API for custom integrations, lifecycle hooks, and plug-and-play plugins via ServiceLoader lookup.

The guicey-jdbi3 extension includes a Row Mapper installer that automatically detects all implementations of RowMapper and registers them in the JDBI instance.

Row mappers are instantiated as standard Guice beans, meaning they support dependency injection and AOP.

Additionally, you can use custom annotations for parameter binding (e.g., @UserBind) to map objects to query parameters. These are detected automatically by JDBI without requiring a custom installer.

@SqlUpdate("update users set version=:version, name=:name where id=:id and version=:version - 1")
int update(@UserBind User entry);

When auto-scan is enabled, Guicey performs the following steps:

1. Search for Installers: It searches the classpath for classes implementing FeatureInstaller.
2. Match Extensions: It uses the registered installers (via FeatureInstaller#matches) to identify extensions.
3. Command Discovery: If .searchCommands() is enabled, it searches for all classes extending Command and installs them into the bootstrap.

Technical Details:

• Scope: It searches the specified packages and all their subpackages.
• Exclusions: Abstract classes are automatically ignored.
• Inner Classes: Static inner classes are resolved and detected (e.g., a @Provider static inner class within an abstract class).

The ResourceInstaller recognizes a class as a REST resource if the @Path annotation is found on a directly implemented interface. This pattern is particularly useful when using Jersey client proxies to call remote resources.

@Path("/res")
@Produces("application/json")
interface ResourceContract {

    @GET
    @Path("/sample")
    String sample();
}

class SampleResource implements ResourceContract {

    @Inject
    private MyService service;

    @Override
    public Response sample() {
        return Response.ok(service.result()).build();
    }
}

The JVM heap is divided into generations. Understanding how these appear in metrics depends on the GC algorithm in use:

Serial GC

When Serial GC is active (typically < 2GB memory), heap regions have fixed sizes. The Young generation (Eden + Survivor) is determined by MaxNewSize (defaulting to 1/3 of max heap). Within the Young generation, sizing is controlled by NewRatio and SurvivorRatio (defaults: 2 and 8 in OpenJDK).

G1 GC

In G1 GC, the sizes of Eden and Survivor spaces are adaptive and resized after every GC cycle. Metric Gotcha: In monitoring tools, the 'Max' values for Eden and Survivor spaces may appear as zero or -1 because they are not fixed. Do not be confused by this; the actual usage values will be non-zero.

The project is organized into a core module and several extension modules:

• ru.vyarus:dropwizard-guicey: The core Guicey module. This can be used standalone without any additional modules.
• ru.vyarus.guicey:guicey-[module name]: Extension modules that provide additional functionality, such as integration with 3rd party libraries. These should be used with the ru.vyarus.guicey:guicey-bom Bill of Materials (BOM).

For practical implementation details, refer to the various usage examples provided in the repository.

The Web Mappings Report provides a diagnostic view of all registered web components (filters and servlets). It displays the hierarchy of mappings, the component type, the path, the implementation class, the bundle/module responsible, and its current operational state.

Key states include:

• STOPPED: The component is registered but not currently active.
• [ERROR]: The component failed to start (often due to configuration or dependency issues).
• [REQUEST]: Indicates the component is part of the request processing chain.
• Disabled: A component that has been explicitly disabled (e.g., via setEnabled(false) on the ServletHandler) will appear as STOPPED in the report.

Installers can be ordered to ensure dependencies are satisfied during the installation process.

To support ordering, an installer must implement the Ordered interface. If an installer does not implement Ordered, its extensions will not be sorted, even if the extensions themselves have @Order annotations.

The guicey-admin-rest module mirrors all resources into an admin context using a special servlet that redirects incoming requests into the Jersey context.

This approach provides two main benefits:

1. Security: Admin-only resources (marked with @AdminResource) are hidden from the user context (returning 404) but remain accessible in the admin context.
2. Efficiency: It avoids the overhead of registering a completely separate Jersey context and simplifies the management of Jersey extensions.

When using dropwizard-guicey to disable specific extensions or modules, the Guice bindings report will explicitly mark these removals.

• Use .disableExtensions(Class<?>) to disable specific extension bindings.
• Use .disableModules(Class<?>) to disable entire Guice modules.

In the diagnostic report output, removed bindings are indicated with the REMOVED tag. This allows you to verify that your configuration to disable specific components is working as expected.

GuiceBundle.builder()
        .modules(new TransitiveModule())
        .disableExtensions(TransitiveModule.Res2)
        .disableModules(TransitiveModule.Inner)
        .printGuiceBindings()
        .build()