Package ru.vyarus.dropwizard.guice.module.installer.bundle

Interface GuiceyCommonRegistration<T>

Type Parameters:
T - builder type
All Known Implementing Classes:
GuiceyBootstrap, GuiceyEnvironment
public interface GuiceyCommonRegistration<T>
Common methods for GuiceyBootstrap and GuiceyEnvironment objects (common for configuration and run phases).

Not implemented as base class to safe backwards compatibility (otherwise all existing bundles would have to be re-compiled).

Since:
14.03.2025

  • Method Summary

    Modifier and Type
    Method
    Description
    <K extends io.dropwizard.core.Configuration>
    io.dropwizard.core.Application<K>
    application()
    Application instance may be useful for complex (half manual) integrations where access for injector is required.
    <K extends io.dropwizard.core.Configuration>
    io.dropwizard.core.setup.Bootstrap<K>
    bootstrap()
    Note: for application in run phase (when called from GuiceyEnvironment), it would be too late to configure dropwizard bootstrap object.
    T
    disableExtensions(Class<?>... extensions)
     
    T
    disableModules(Class<? extends com.google.inject.Module>... modules)
    Disable both usual and overriding guice modules.
    T
    extensions(Class<?>... extensionClasses)
    Bundle should not rely on auto-scan mechanism and so must declare all extensions manually (this better declares bundle content and speed ups startup).
    T
    extensionsOptional(Class<?>... extensionClasses)
    The same as extensions(Class[]), but, in case if no installer recognize extension, will be automatically disabled instead of throwing error.
    T
    listen(GuiceyLifecycleListener... listeners)
    Guicey broadcast a lot of events in order to indicate lifecycle phases (GuiceyLifecycle).
    T
    modules(com.google.inject.Module... modules)
    Register guice modules.
    T
    modulesOverride(com.google.inject.Module... modules)
    Override modules (using guice Modules.override(com.google.inject.Module...)).
    <V, K extends Enum<? extends Option> & Option>
    V
    option(K option)
    Read option value.
    <K> Optional<K>
    sharedState(Class<K> key)
    Access shared value.
    <K> K
    sharedState(Class<K> key, Supplier<K> defaultValue)
    Alternative shared value initialization for cases when first accessed bundle should init state value and all others just use it.
    <K> K
    sharedStateOrFail(Class<K> key, String message, Object... args)
    Used to access shared state value and immediately fail if value not yet set (most likely due to incorrect configuration order).
    <K> T
    shareState(Class<K> key, K value)
    Share global state to be used in other bundles (during configuration).
    <V> void
    whenSharedStateReady(Class<V> key, Consumer<V> action)
    Reactive shared value access: if value already available action called immediately, otherwise action would be called when value set (note that value could be set only once).

  • Method Details

    • bootstrap

      <K extends io.dropwizard.core.Configuration> io.dropwizard.core.setup.Bootstrap<K> bootstrap()
      Note: for application in run phase (when called from GuiceyEnvironment), it would be too late to configure dropwizard bootstrap object.
      Type Parameters:
      K - configuration type
      Returns:
      dropwizard bootstrap instance

    • application

      <K extends io.dropwizard.core.Configuration> io.dropwizard.core.Application<K> application()
      Application instance may be useful for complex (half manual) integrations where access for injector is required. For example, manually registered Managed may access injector in it's start method by calling InjectorLookup.getInjector(io.dropwizard.core.Application).

      NOTE: it will work in this example, because injector access will be after injector creation. Directly inside bundle initialization method injector could not be obtained as it's not exists yet.

      Type Parameters:
      K - configuration type
      Returns:
      dropwizard application instance

    • option

      <V, K extends Enum<? extends Option> & Option> V option(K option)
      Read option value. Options could be set only in application root GuiceBundle.Builder.option(Enum, Object). If value wasn't set there then default value will be returned. Null may return only if it was default value and no new value were assigned.

      Option access is tracked as option usage (all tracked data is available through OptionsInfo).

      Type Parameters:
      V - option value type
      K - helper type to define option
      Parameters:
      option - option enum
      Returns:
      assigned option value or default value
      See Also:

    • modules

      T modules(com.google.inject.Module... modules)
      Register guice modules.

      When registration called under initialization phase (GuiceyBootstrap), neither configuration nor environment objects are available yet. If you need them for module, then you can wrap it with DropwizardAwareModule or register modules in run phase (inside GuiceyBundle.run(GuiceyEnvironment)).

      When registration called under run phase (GuiceyEnvironment), environment and configuration objects already available (no need to use Aware* interfaces, but if you will they will also work, of course). This may look like misconception because configuration appear not in configuration phase, but it's not: for example, in pure dropwizard you can register jersey configuration modules in run phase too. This brings the simplicity of use: 3rd party guice modules often require configuration values to be passed directly to constructor, which is impossible in initialization phase (and so you have to use Aware* workarounds).

      Parameters:
      modules - one or more guice modules
      Returns:
      builder instance for chained calls
      See Also:

    • modulesOverride

      T modulesOverride(com.google.inject.Module... modules)
      Override modules (using guice Modules.override(com.google.inject.Module...)).
      Parameters:
      modules - overriding modules
      Returns:
      builder instance for chained calls
      See Also:

    • extensions

      T extensions(Class<?>... extensionClasses)
      Bundle should not rely on auto-scan mechanism and so must declare all extensions manually (this better declares bundle content and speed ups startup).

      NOTE: startup will fail if bean not recognized by installers. Use extensionsOptional(Class[]) to register optional extension.

      Alternatively, you can manually bind extensions in guice module and they would be recognized (GuiceyOptions.AnalyzeGuiceModules).

      Parameters:
      extensionClasses - extension bean classes to register
      Returns:
      builder instance for chained calls
      See Also:

    • extensionsOptional

      T extensionsOptional(Class<?>... extensionClasses)
      The same as extensions(Class[]), but, in case if no installer recognize extension, will be automatically disabled instead of throwing error. Useful for optional extensions declaration in 3rd party bundles (where it is impossible to be sure what other bundles will be used and so what installers will be available).

      Alternatively, you can manually bind extensions in guice module and they would be recognized (GuiceyOptions.AnalyzeGuiceModules). Extensions with no available target installer will simply wouldn't be detected (because installers used for recognition) and so there is no need to mark them as optional in this case.

      Parameters:
      extensionClasses - extension bean classes to register
      Returns:
      builder instance for chained calls

    • disableExtensions

      T disableExtensions(Class<?>... extensions)
      Parameters:
      extensions - extensions to disable (manually added, registered by bundles or with classpath scan)
      Returns:
      builder instance for chained calls
      See Also:

    • disableModules

      T disableModules(Class<? extends com.google.inject.Module>... modules)
      Disable both usual and overriding guice modules.

      If bindings analysis is not disabled, could also disable inner (transitive) modules, but only inside normal modules.

      Parameters:
      modules - guice module types to disable
      Returns:
      builder instance for chained calls
      See Also:

    • listen

      T listen(GuiceyLifecycleListener... listeners)
      Guicey broadcast a lot of events in order to indicate lifecycle phases (GuiceyLifecycle). This could be useful for diagnostic logging (like GuiceBundle.Builder.printLifecyclePhases()) or to implement special behaviours on installers, bundles, modules extensions (listeners have access to everything). For example, ConfigurationAwareModule like support for guice modules could be implemented with listeners.

      Configuration items (modules, extensions, bundles) are not aware of each other and listeners could be used to tie them. For example, to tell bundle if some other bundles registered (limited applicability, but just for example).

      You can also use GuiceyLifecycleAdapter when you need to handle multiple events (it replaces direct events handling with simple methods).

      Listener is not registered if equal listener were already registered (Set used as listeners storage), so if you need to be sure that only one instance of some listener will be used implement Object.equals(Object) and Object.hashCode().

      Parameters:
      listeners - guicey lifecycle listeners
      Returns:
      builder instance for chained calls
      See Also:

    • shareState

      <K> T shareState(Class<K> key, K value)
      Share global state to be used in other bundles (during configuration). This was added for very special cases when shared state is unavoidable (to not re-invent the wheel each time)!

      During application strartup, shared state could be requested with a static call SharedConfigurationState.getStartupInstance(), but only from main thread.

      Internally, state is linked to application instance, so it would be safe to use with concurrent tests. Value could be accessed statically with application instance: SharedConfigurationState.lookup(Application, Class).

      In some cases, it is preferred to use bundle class as key. Value could be set only once (to prevent hard to track situations).

      If initialization point could vary (first access should initialize it) use sharedState(Class, java.util.function.Supplier) instead.

      Type Parameters:
      K - shared object type
      Parameters:
      key - shared object key
      value - shared object
      Returns:
      builder instance for chained calls
      See Also:

    • sharedState

      <K> K sharedState(Class<K> key, Supplier<K> defaultValue)
      Alternative shared value initialization for cases when first accessed bundle should init state value and all others just use it.

      It is preferred to initialize shared state under initialization phase to avoid problems related to initialization order (assuming state is used under run phase). But in some cases, it is not possible.

      Type Parameters:
      K - shared object type
      Parameters:
      key - shared object key
      defaultValue - default object provider
      Returns:
      shared object (possibly just created)
      See Also:

    • sharedState

      <K> Optional<K> sharedState(Class<K> key)
      Access shared value.
      Type Parameters:
      K - shared object type
      Parameters:
      key - shared object key
      Returns:
      shared object
      See Also:

    • sharedStateOrFail

      <K> K sharedStateOrFail(Class<K> key, String message, Object... args)
      Used to access shared state value and immediately fail if value not yet set (most likely due to incorrect configuration order).
      Type Parameters:
      K - shared object type
      Parameters:
      key - shared object key
      message - exception message (could use String.format(String, Object...) placeholders)
      args - placeholder arguments for error message
      Returns:
      shared object
      Throws:
      IllegalStateException - if no value available
      See Also:

    • whenSharedStateReady

      <V> void whenSharedStateReady(Class<V> key, Consumer<V> action)
      Reactive shared value access: if value already available action called immediately, otherwise action would be called when value set (note that value could be set only once).
      Type Parameters:
      V - value type
      Parameters:
      key - shared object key
      action - action to execute when value would be set