Configuration¶

Guicey main dropwizard bundle must be registered:

@Override
public void initialize(Bootstrap<Configuration> bootstrap) {
    bootstrap.addBundle(GuiceBundle.builder() 
            // <configuration methods>           
            .build());
}

Guicey could be configured through:

Main (dropwizard) bundle
Bundles
Hooks

Main bundle¶

Tip

Bundle builder contains shortcuts for all guicey features, so required function may be found only by looking at available methods (and reading javadoc).

Configuration items¶

.enableAutoConfig(String... basePackages): Enable classpath scan for automatic extension registration, custom installers search and commands search (if enabled)
.enableAutoConfig(): Shortcut for enabling classpath scan on application package
.modules(Module... modules): Guice modules registration

Here guice modules are created in initialization phase, when Configuration and Environment are not yet available. If they are required for module either use "Aware" interfaces or register module in GuiceyBundle's run method (under run phase).
.modulesOverride(Module... modules): Overriding registered guice modules bindings (using guice Modules.override() api)

Extensions are not recognized in overriding modules (intentionally)!
.installers(Class<? extends FeatureInstaller>... installers): Guicey extension installers registration. Required if you have custom installers or to specify installers after disabling all default installers: .noDefaultInstallers()

Custom installers are registered automatically when classpath scan is enabled.
.extensions(Class<?>... extensionClasses): Manual extension registration. May be used together with classpath scan and binding extensions
.extensionsOptional(Class<?>... extensionClasses): Optional extension registration. The difference with .extensions is that such extensions will be automatically disabled if there are no compatible installers (instead of throwing exception).
.bundles(GuiceyBundle... bundles): Guicey bundles registration.
.bundleLookup(GuiceyBundleLookup bundleLookup): Custom lookup mechanism for guicey bundles. By default, lookup by system property and ServiceLoader are enabled. To disable all look-ups use: .disableBundleLookup()
.dropwizardBundles(ConfiguredBundle... bundles): Shortcut for dropwizard bundles registration. This way guicey could apply disable and de-duplication rules to registered bundles (and, also, registered bundles appear in reports)
.searchCommands(): Search and register custom dropwizard commands. Requires enabled classpath scan

Disable items¶

Registered configuration items could be disabled. This is mostly useful for tests where entire application parts could be disabled and replaced (e.g. with mocks) this way. Could be also useful to "hack" third party items.

.disableInstallers(Class<? extends FeatureInstaller>... installers)
.disableExtensions(Class<?>... extensions)
.disableModules(Class<? extends Module>... modules): Affects transitive guice modules
.disableBundles(Class<? extends GuiceyBundle>... bundles)
.disableDropwizardBundles(Class<? extends ConfiguredBundle>... bundles): Affects only dropwizard bundles registered through guicey api and their transitive bundles
.disable(Predicate<ItemInfo>... predicates): Custom disable predicate useful to disable groups of items (by some sign)

Items de-duplication¶

Guicey detects instances of the same type (bundles, modules). By default, two instances considered as duplicates if they are equal, so duplicates could be controlled with proper equals method implementation. When it's not possible, custom de-duplication implementation could be used.

Tip

Special base classes are available with correct equals implementations: UniqueModule (for guice modules) and UniqueGuiceyBundle (for bundles).

.duplicateConfigDetector(DuplicateConfigDetector detector): Special implementation provided to replicate legacy guicey behaviour "one instance per class": duplicateConfigDetector(new LegacyModeDuplicatesDetector())
.uniqueItems(Class<?>... configurationItems): Register special de-duplication implementation which will allow only one instance of provided types.

Options¶

Guicey generic options mechanism may be used for guicey (or other 3^rd party bundles) fine-tuning.

Guicey option enums: GuiceyOptions and InstallersOptions

.option(K option, Object value): Set option value (override default)
.options(Map<Enum, Object> options): Set multiple options at once (e.g. map system properties as option values)

GuiceyOptions¶

Note

Some options are configured through main bundle shortcut methods and so they are not shown in the table below.

Option	Type	Default	Description
BindConfigurationByPath	Boolean	true	Introspect configuration to be able to bind separate values
TrackDropwizardBundles	Boolean	true	Recognize transitive dropwizard bundles (for bundles registered through guicey api)
AnalyzeGuiceModules	Boolean	true	Extension recognition in guice bindings, transitive modules disable support
GuiceFilterRegistration	`EnumSet<DispatcherType>`	[REQUEST]	Guice filter registration options
UseHkBridge	Boolean	false	Activates HK2-guice bridge (bridge dependency must be available on the classpath)

InstallersOptions¶

Option	Type	Default	Description
DenyServletRegistrationWithClash	Boolean	false	Throw error if `@WebServlet` annotated servlets clash with already registered servlets
DenySessionListenersWithoutSession	Boolean	false	Throw error for registered `SessionListener` (annotated `@WebListener`) if sessions support not enabled (default)
ForceSingletonForJerseyExtensions	Boolean	true	Force singleton scope for registered jersey extensions (resources, exception handlers etc) if no explicit scope declared

Injector¶

.injectorFactory(InjectorFactory injectorFactory): Use custom injector factory implementation. May be useful for tests or for integration of 3^rd party library (like governator)
.build(Stage stage): Build bundle with custom guice stage (by default, Production)
.build(): Build bundle with default guice stage

Lifecycle¶

.listen(GuiceyLifecycleListener... listeners): Listen for guicey lifecycle events
.noGuiceFilter(): Disable GuiceFilter registration.
This will remove guice request and session scopes and also it would become impossible to use ServletModules
.strictScopeControl(): Explicitly detect when guice bean is instantiated with HK2 and vice versa.
Bean target container is defined with @JerseyManaged and @GuiceManaged annotations or default (either guice or hk2 used as default (for jersey extensions))
.useHK2ForJerseyExtensions(): Use HK2 by default for jersey extensions (change default). With this @GuiceManaged annotation may be used to override default for bean.
Beans managed by HK2 can't use guice AOP, so AOP-based features will not work with such beans

Danger

In the next version guicey will get rid of HK2 and so all HK2 related options will be removed (only guice will be used). Also, .noGuiceFilter() will be removed because request scope will be required.

Diagnostic tools¶

Guicey provide many bundled console reports to help with problems diagnostic (or to simply clarify how application works) during development, like:

.printDiagnosticInfo()

See diagnostic section for a full list of available reports.

.hookAlias(String name, Class<? extends GuiceyConfigurationHook> hook): Hook alias registration for simplified usage (various diagnostic tools quick enabling with a system property)
.withSharedState(Consumer<SharedConfigurationState> stateAction): This method is mainly useful for hooks, because it's the only way to access application shared state from hook.

Guicey bundle¶

GuiceyBundles are like dropwizard bundles, but with greater abilities. Supposed to be used instead of dropwizard bundles. Bundles are registered either directly (in main bundle or other guicey bundle) or resolved by bundles lookup.

Initialization¶

public class MyBundle implements GuiceyBundle {

    @Override
    public void initialize(GuiceyBootstrap bootstrap) {
        ...
    }      
}

Bundle initialization share many methods in common with main guice bundle:

.modules(Module... modules)
.modulesOverride(Module... modules)
.installers(Class<? extends FeatureInstaller>... installers)
.extensions(Class<?>... extensionClasses) .extensionsOptional(Class<?>... extensionClasses)
.bundles(GuiceyBundle... bundles)
.dropwizardBundles(ConfiguredBundle... bundles)

.disableInstallers(Class<? extends FeatureInstaller>... installers)
.disableExtensions(Class<?>... extensions)
.disableModules(Class<? extends Module>... modules)

No disable for bundles because at this moment some bundles were already executed and so real state could be inconsistent with configuration (and highly depend on processing order).

.listen(GuiceyLifecycleListener... listeners): Listener registered in bundle will "hear" only events starting with GuiceyLifecycle#BundlesInitialized

Shortcuts:

.bootstrap()
.application()

Option value access:

.option(T option): Bundle can't declare option value because it would make options state not predictable (highly dependent on initialization order)

Shared state access:

.shareState(Class<?> key, Object value): Declare shared state (primary module scenario)
.sharedState(Class<?> key, Supplier<T> defaultValue): Get or init shared state (equal bundles scenario)
.sharedStateOrFail(Class<?> key, String message, Object... args): Shortcut to get shared state or immediately fail if not declared

Run¶

public class MyBundle implements GuiceyBundle {

    @Override
    public void run(GuiceyEnvironment environment) {
        ...
    }      
}

Everything is configured under initialization phase. On run phase bundle allows only modules registration and extensions disable.

Shortcuts:

.configuration()
.environment()
.application()
.register(Object... items): Shortcut for environment().jersey().register(Object)
.register(Class<?>... items): Shortcut for environment().jersey().register(Class)
.manage(Managed managed): Shortcut for environment().lifecycle().manage()
.listenServer(ServerLifecycleListener listener): Shortcut for environment().lifecycle().addServerLifecycleListener()
.listenJetty(LifeCycle.Listener listener): Shortcut for environment().lifecycle().addLifeCycleListener()

Extended configuration access:

.configuration(String yamlPath)
.configuration(Class<T> type)
.configurations(Class<T> type)
.annotatedConfiguration(ann)
.annotatedConfiguration(Class)
.configurationTree()

Modules registration:

.modules(Module... modules): Only here modules may be created directly with configuration values

.modulesOverride(Module... modules)

Disables:

.disableExtensions(final Class<?>... extensions)
.disableModules(Class<? extends Module>... modules)

Option value access:

.option(T option)

Shared state:

.sharedStateOrFail(Class<?> key, String message, Object... args)
.sharedState(Class<?> key)

Guicey listeners:

.listen(GuiceyLifecycleListener... listeners): Listener registered in run phase will "hear" only events starting with GuiceyLifecycle#BundlesStarted
.onGuiceyStartup(GuiceyStartupListener listener): Shortcut for manual configuration under run phase with available injector
.onApplicationStartup(ApplicationStartupListener listener): Shortcut for manual actions after complete application start (jetty started)

It is also called after guicey initialization in lightweight guicey tests

Hooks¶

Guicey hooks are registered statically before main guice bundle registration:

public class MyHook implements GuiceyConfigurationHook {

    @Override
    public void configure(final GuiceBundle.Builder builder) {
        builder.printDiagnosticInfo();
    }
}    

// static registration
new MyHook().register()

On execution hook receives the same builder as used in main GuiceBundle. So hooks could configure everything.

Hooks are intended to be used in tests and to implement a pluggable diagnostic tools activated with system property -Dguicey.hooks=... (as an example, see guicey DiagnosticHook).