edit

Configuration¶

Builder GuiceBundle.builder() contains shortcuts for all available features, so you can always find required function by looking at available methods and reading javadoc.

Configuration subjects (vocabulary)

Installers - used to recognize and install extension (usually encapsulates integration logic: get extension instance from guice injector and register in dropwizard (or jersey, hk, whatever))
Extensions - actual application parts, written by you (resources, tasks, health checks, servlets etc)
Guice modules
Guicey bundles - groups installers, extensions, gucie modules and other guicey bundles (represent reusable logic or 3^rd party integrations; very similar to dropwizard bundles)
Options - general mechanism for low level configurations (development time triggers)
Commands - dropwizard commands (mentioned because of ability for automatic registration)

Warning

Configured bundles, modules, installers and extensions are checked for duplicates using class type. Duplicate configurations will be simply ignored. For modules and bundles, which configured using instances, duplicates removes means that if two instances of the same type registered, then second instance will be ignored.

Configuration process is recorded and may be observed with by diagnostic info, so there is always a way to understand what and how was configured.

Auto configuration¶

Auto configuration enables classpath scan to search for extensions and custom installers. Without auto scan, all extensions (resource, managed, health check etc.) must be registered manually (manual mode).

.enableAutoConfig("com.mycompany.app")

or multiple packages

.enableAutoConfig("com.mycompany.app.resources", "com.mycompany.app.staff")

Commands search¶

In auto configuration mode guicey could also search and install dropwiard commands (register in bootstrap object):

.searchCommands()

By default commands scan is disabled because it may confusing. Besides, it's not often needed.

Extensions¶

All features installed with guicey installers are called extensions. When auto configuration is enabled, extensions are discovered automatically. Without auto configuratin (manual mode) all extensions must be specified manually.

.extensions(MyResource1.class, MyHealthCheck.class)

Auto configuration may be used together with manual definition (for example, manually registered extension could be unreachable for classpath scan).

Each extension could be installed only by one installer: if multiple installers could recognize extension, only one of them will install it (first one according to priority).

Installers¶

Guicey come with pre-defined set of installers (for common extensions). But you can write your own installers (or use some 3^rd party ones).

Most installers implementations are very simple and easy to understand. Look installer source to better understand how extensions work. In case when default installer does not fit your needs, it's not hard to replace installer with your custom version.

.installers(MyExtensionInstaller.class, ThirdPartyExtensionInstaller.class)

Tip

In auto configuration mode, installers are also detected and installed automatically

Default installers¶

Guicey come with a set of pre defined installers, enabled by default (for common extensions installation like resource, health check, task, managed etc.). You can disable them with:

.noDefaultInstallers()

Web installers¶

Guicey has advanced installers for standard servlet annotations (@WebServlet, @WebFilter, @WebListener). They are not enabled by default to avoid confusion: user may not expect guice support for these standard annotations.

To enable web installers:

.useWebInstallers()

Disable installer¶

You can disable installers (even if it's not registered)

.disableInstallers(ManagedInstaller.class, ResourceInstaller.class)

Debug installers¶

Special debug option could print to console all available installers (with registration sources):

.printAvailableInstallers()

Use to quickly understand available features.

Guice modules¶

You can register one or more guice modules (including guice ServletModules):

.modules(new MyModule1(), new MyModule2())

If you have many modules try to group their installation inside your custom module in order to keep guice staff together.

In some cases, it could be desired to use different instances of the same module:

.modules(new ParametrizableModule("mod1"), new ParametrizableModule("mod2"))

This will not work (second instance will be dropped). In such cases do registrations in custom guice module:

install(new ParametrizableModule("mod1"));
install(new ParametrizableModule("mod2"));

Guicey bundles¶

In essence, guicey bundles are the same as dropwizard bundles: used to install re-usable logic or 3^rd party library integration.

.bundles(new MyBundle(), new ThirdPartyBundle());

Dropwizard bundles unification¶

Guice bundles must implement interface (GuiceyBundle). Dropwizard bundle could inmplement it too. This may be useful for universal bundles when all main features are activated by dropwizard bundle and guicey features are optional (if guicey present).

When:

.configureFromDropwizardBundles()

guicey checks registered dropwizard bundles if they are also GuiceyBundle and register them as guicey bundles.

Bundle lookup¶

Bundle lookup mechanism provides support for indirect guicey bundles installation. Default lookup mechanism allows using service loader (plug-n-play bundles) or system property (test/diagnostic bundles).

Custom implementation could be specified:

.bundleLookup(new MyBundleLookupImpl())

Shortcut to disable default bundle lookup:

.disableBundleLookup()

Options¶

Options are used for development time configurations (test specific triggers or low level configurations). Guicey option enums: GuiceyOptions and InstallersOptions

.option(GuiceyOptions.InjectorStage, Stage.DEVELOPMENT)

Tip

Options look better with static import: .option(InjectorStage, DEVELOPMENT)

To provide multiple options at once (batch options load):

.options(new MyOptionsLookup().getOptions())

Guice¶

Stage¶

Guice stage cold be provided in:

.build(Stage.DEVELOPMENT)

By default, PRODUCTION stage used.

Injector¶

Custom guice injector factory may be registered to customize injector creation (e.g. required for governator):

.injectorFactory(new GovernatorInjectorFactory())

ServletModule¶

By default, guicey registers GuiceFilter for both main and admin contexts to provide request scopes for both contexts and ability to use guice ServletModules on main context.

GuiceFilter is registered with REQUEST dispatcher type. If you need to use other types:

.option(GuiceFilterRegistration, EnumSet.of(REQUEST, FORWARD))

If you don't need servlet module support (and request scopes), guice filter installation could be disabled:

.noGuiceFilter()

Servlet modules will be rejected in this case. Intended to be used when web installers enabled.

Note

HttpServletRequest and HttpServletResponse objects will be available for injection only in scope of jersey resources call.

Configuration binding¶

It may be useful to bind configuration instance to interface. Suppose some 3^rd party requires your configuration to implement interface:

public class MyConfiguraton extends Configuration implements HasRequiredConfig {...}

If binding by interface is enabled:

.bindConfigurationInterfaces()

Then configuration could be injected by interface:

@Inject HasRequiredConfig conf;

Note

By default, configuration is bound only for all classes in hierarchy. In example above it would be Configuration and MyConfiguration.

Diagnostic¶

Enable configuration diagnostic console logs to diagnose configuration problems:

.printDiagnosticInfo()

In case of doubts about extension owner (guice or HK) and suspicious for duplicate instantiation, you can enable strict control which will throw exception in case of wrong owner:

.strictScopeControl()