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

Class GuiceyBootstrap

  • All Implemented Interfaces:
    GuiceyCommonRegistration<GuiceyBootstrap>
    public class GuiceyBootstrap
extends java.lang.Object
implements GuiceyCommonRegistration<GuiceyBootstrap>
    Guicey initialization object. Provides almost the same configuration methods as GuiceBundle.Builder. Also, contains dropwizard bootstrap objects. May register pure dropwizard bundles.

    In contrast to main builder, guicey bundle can't:

    • Disable bundles (because at this stage bundles already partly processed)
    • Use generic disable predicates (to not allow bundles disable, moreover it's tests-oriented feature)
    • Change options (because some bundles may already apply configuration based on changed option value which will mean inconsistent state)
    • Register listener, implementing GuiceyConfigurationHook (because it's too late - all hooks were processed)
    • Register some special objects like custom injector factory or custom bundles lookup
    Since:
    01.08.2015

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      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.
      GuiceyBootstrap bundles​(GuiceyBundle... bundles)
      Register other guicey bundles for installation.
      GuiceyBootstrap disableExtensions​(java.lang.Class<?>... extensions)
      GuiceyBootstrap disableInstallers​(java.lang.Class<? extends FeatureInstaller>... installers)  
      GuiceyBootstrap disableModules​(java.lang.Class<? extends com.google.inject.Module>... modules)
      Disable both usual and overriding guice modules.
      GuiceyBootstrap dropwizardBundles​(io.dropwizard.core.ConfiguredBundle... bundles)
      Shortcut for dropwizard bundles registration (instead of bootstrap().addBundle()), but with duplicates detection and tracking in diagnostic reporting.
      GuiceyBootstrap extensions​(java.lang.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).
      GuiceyBootstrap extensionsOptional​(java.lang.Class<?>... extensionClasses)
      The same as GuiceyCommonRegistration.extensions(Class[]), but, in case if no installer recognize extension, will be automatically disabled instead of throwing error.
      GuiceyBootstrap installers​(java.lang.Class<? extends FeatureInstaller>... installers)
      If bundle provides new installers then they must be declared here.
      GuiceyBootstrap listen​(GuiceyLifecycleListener... listeners)
      Guicey broadcast a lot of events in order to indicate lifecycle phases (GuiceyLifecycle).
      GuiceyBootstrap modules​(com.google.inject.Module... modules)
      Register guice modules.
      GuiceyBootstrap modulesOverride​(com.google.inject.Module... modules)
      Override modules (using guice Modules.override(com.google.inject.Module...)).
      <V,​K extends java.lang.Enum<? extends Option> & Option>
      V      		 option​(K option)
      Read option value.
      <K> java.util.Optional<K> sharedState​(java.lang.Class<K> key)
      Access shared value.
      <K> K sharedState​(java.lang.Class<K> key, java.util.function.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​(java.lang.Class<K> key, java.lang.String message, java.lang.Object... args)
      Used to access shared state value and immediately fail if value not yet set (most likely due to incorrect configuration order).
      <K> GuiceyBootstrap shareState​(java.lang.Class<K> key, K value)
      Share global state to be used in other bundles (during configuration).
      <V> void whenSharedStateReady​(java.lang.Class<V> key, java.util.function.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).

      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    • Constructor Detail

      • GuiceyBootstrap

        public GuiceyBootstrap​(ConfigurationContext context,
                       java.util.List<java.lang.Class<? extends GuiceyBundle>> bundlesPath,
                       java.util.List<GuiceyBundle> initOrder)
        Create bootstrap.
        Parameters:
        context - configuration context
        bundlesPath - paths to track bundles installation loops
        initOrder - holder for bundles initialization order

    • Method Detail

      • installers

        @SafeVarargs
public final GuiceyBootstrap installers​(java.lang.Class<? extends FeatureInstaller>... installers)
        If bundle provides new installers then they must be declared here. Optionally, core or other 3rd party installers may be declared also to indicate dependency (duplicate installers registrations will be removed).
        Parameters:
        installers - feature installer classes to register
        Returns:
        bootstrap instance for chained calls
        See Also:
        GuiceBundle.Builder.installers(Class[])

      • bundles

        public GuiceyBootstrap bundles​(GuiceyBundle... bundles)
        Register other guicey bundles for installation. Bundles initialized immediately (same as transitive dropwizard bundles and guice modules).

        Equal instances of the same type will be considered as duplicate.

        Parameters:
        bundles - guicey bundles
        Returns:
        bootstrap instance for chained calls
        See Also:
        GuiceBundle.Builder.bundles(GuiceyBundle...)

      • dropwizardBundles

        public GuiceyBootstrap dropwizardBundles​(io.dropwizard.core.ConfiguredBundle... bundles)
        Shortcut for dropwizard bundles registration (instead of bootstrap().addBundle()), but with duplicates detection and tracking in diagnostic reporting. Dropwizard bundle is immediately initialized.
        Parameters:
        bundles - dropwizard bundles to register
        Returns:
        bootstrap instance for chained calls
        See Also:
        GuiceBundle.Builder.dropwizardBundles(ConfiguredBundle...)

      • bootstrap

        public <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.
        Specified by:
        bootstrap in interface GuiceyCommonRegistration<GuiceyBootstrap>
        Type Parameters:
        K - configuration type
        Returns:
        dropwizard bootstrap instance

      • application

        public <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.

        Specified by:
        application in interface GuiceyCommonRegistration<GuiceyBootstrap>
        Type Parameters:
        K - configuration type
        Returns:
        dropwizard application instance

      • modules

        public GuiceyBootstrap 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).

        Specified by:
        modules in interface GuiceyCommonRegistration<GuiceyBootstrap>
        Parameters:
        modules - one or more guice modules
        Returns:
        builder instance for chained calls
        See Also:
        GuiceBundle.Builder.modules(com.google.inject.Module...), DropwizardAwareModule

      • extensionsOptional

        public GuiceyBootstrap extensionsOptional​(java.lang.Class<?>... extensionClasses)
        The same as GuiceyCommonRegistration.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.

        Specified by:
        extensionsOptional in interface GuiceyCommonRegistration<GuiceyBootstrap>
        Parameters:
        extensionClasses - extension bean classes to register
        Returns:
        builder instance for chained calls

      • listen

        public GuiceyBootstrap 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().

        Specified by:
        listen in interface GuiceyCommonRegistration<GuiceyBootstrap>
        Parameters:
        listeners - guicey lifecycle listeners
        Returns:
        builder instance for chained calls
        See Also:
        GuiceyLifecycle, GuiceyLifecycleAdapter, UniqueGuiceyLifecycleListener

      • sharedState

        public <K> K sharedState​(java.lang.Class<K> key,
                         java.util.function.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.

        Specified by:
        sharedState in interface GuiceyCommonRegistration<GuiceyBootstrap>
        Type Parameters:
        K - shared object type
        Parameters:
        key - shared object key
        defaultValue - default object provider
        Returns:
        shared object (possibly just created)
        See Also:
        SharedConfigurationState

      • sharedStateOrFail

        public <K> K sharedStateOrFail​(java.lang.Class<K> key,
                               java.lang.String message,
                               java.lang.Object... args)
        Used to access shared state value and immediately fail if value not yet set (most likely due to incorrect configuration order).
        Specified by:
        sharedStateOrFail in interface GuiceyCommonRegistration<GuiceyBootstrap>
        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
        See Also:
        SharedConfigurationState

      • whenSharedStateReady

        public <V> void whenSharedStateReady​(java.lang.Class<V> key,
                                     java.util.function.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).
        Specified by:
        whenSharedStateReady in interface GuiceyCommonRegistration<GuiceyBootstrap>
        Type Parameters:
        V - value type
        Parameters:
        key - shared object key
        action - action to execute when value would be set