Package ru.vyarus.dropwizard.guice.module.context

Class SharedConfigurationState

  • public class SharedConfigurationState
extends java.lang.Object
    Application-wide shared state assumed to be used in configuration phase. For example, in complex cases when bundles must share some global state (otherwise it would require to maintain some ThreadLocal field in bundle). But other cases could arise too. Intended to be used for very rare cases: use it only if you can't avoid shared state in configuration time (for example, like guicey gsp bundle, which requires global configuration, accessible by multiple bundles).

    Internally, guicey use it to store created Injector and make it available statically (see InjectorLookup).

    Universal sharing place should simplify testing in the future: if new global state will appear, there would be no need to reset anything in tests (to clear state, for example, on testing errors). One "dirty" place to replace all separate hacks.

    Shared state could be accessed statically with get(Application), or within GuiceyBundle. Guicey hooks could use GuiceBundle.Builder.withSharedState(java.util.function.Consumer) to access application state. Alternatively, dropwizard Environment may be used for resolution: get(Environment).

    During startup shared state instance could be obtained directly as getStartupInstance(), but only from application main thread. This might be required for places where neither application nor environment object available. After guice bundle's run method finishes, startup instance is unlinked.

    Classes are used as state keys to simplify usage (in most cases, bundle class will be used as key). Shared value could be set only once (to prevent complex situations with state substitutions). It is advised to initialize shared value only in initialization phase (to avoid potential static access errors).

    Objects available in shared state by default: Bootstrap, Configuration, Environment, ConfigurationTree, Injector (see shortcut instance methods).

    Since:
    26.09.2019

    • Field Summary

      Fields 
      Modifier and Type Field Description
      static java.lang.String CONTEXT_APPLICATION_PROPERTY
      Attribute name used to store application instance in application context attributes.

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      protected void assignTo​(io.dropwizard.Application application)
      Called on initialization phase to assign registry instance to application (to be able to statically reference registry).
      static void clear()
      Clears stored injectors references.
      protected void forgetStartupInstance()
      Called after application startup to cleanup thread local instance.
      static java.util.Optional<SharedConfigurationState> get​(io.dropwizard.Application application)
      Static lookup for entire application registry.
      static java.util.Optional<SharedConfigurationState> get​(io.dropwizard.setup.Environment environment)
      Static lookup for entire application registry by environment instance.
      <V> V get​(java.lang.Class<?> key)
      Note: in spite of fact that class is used for key, actual value is stored with full class name string.
      <V> V get​(java.lang.Class<?> key, java.util.function.Supplier<V> defaultValue)
      Get value or declare default if value not set yet.
      <C extends io.dropwizard.Configuration>
      javax.inject.Provider<io.dropwizard.Application<C>>      		 getApplication()
      Application object is available since guice bundle initialization start.
      <C extends io.dropwizard.Configuration>
      javax.inject.Provider<io.dropwizard.setup.Bootstrap<C>>      		 getBootstrap()
      Bootstrap object is available since guice bundle initialization start.
      <C extends io.dropwizard.Configuration>
      javax.inject.Provider<C>      		 getConfiguration()
      Configuration instance is available since guice bundle run.
      javax.inject.Provider<ConfigurationTree> getConfigurationTree()
      Configuration instance is available since guice bundle run.
      javax.inject.Provider<io.dropwizard.setup.Environment> getEnvironment()
      Environment instance is available since guice bundle run.
      javax.inject.Provider<com.google.inject.Injector> getInjector()
      Injector instance is created under guice bundle run.
      java.util.Set<java.lang.String> getKeys()
      Note: each key is a full name of registration class.
      static SharedConfigurationState getOrFail​(io.dropwizard.Application application, java.lang.String message, java.lang.Object... args)
      Shortcut for get(Application) to immediately fail if registry is not available.
      static SharedConfigurationState getOrFail​(io.dropwizard.setup.Environment environment, java.lang.String message, java.lang.Object... args)
      Shortcut for get(Environment) to immediately fail if registry is not available.
      <V> V getOrFail​(java.lang.Class<?> key, java.lang.String message, java.lang.Object... args)
      Shortcut for get(Class) to immediately fail if value not set.
      static SharedConfigurationState getStartupInstance()
      During application startup it is not always possible to lookup configuration state with Application or Environment objects.
      protected void listen​(io.dropwizard.setup.Environment environment)
      Called on run phase to assign to application lifecycle and listen for shutdown.
      static <V> java.util.Optional<V> lookup​(io.dropwizard.Application application, java.lang.Class<?> key)
      Static lookup for registry value.
      static <V> java.util.Optional<V> lookup​(io.dropwizard.setup.Environment environment, java.lang.Class<?> key)
      Static lookup for registry value by environment instance.
      static <V> V lookupOrFail​(io.dropwizard.Application application, java.lang.Class<?> key, java.lang.String message, java.lang.Object... args)
      Shortcut for lookup(Application, Class) to immediately fail if value is not available.
      static <V> V lookupOrFail​(io.dropwizard.setup.Environment environment, java.lang.Class<?> key, java.lang.String message, java.lang.Object... args)
      Shortcut for lookup(Environment, Class) to immediately fail if value is not available.
      void put​(java.lang.Class<?> key, java.lang.Object value)
      Assumed to be used to store some configuration during startup.
      static int statesCount()
      Could be useful only in tests in order to validate possibly stale applications.
      java.lang.String toString()  

      • Methods inherited from class java.lang.Object

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

    • Field Detail

      • CONTEXT_APPLICATION_PROPERTY

        public static final java.lang.String CONTEXT_APPLICATION_PROPERTY
        Attribute name used to store application instance in application context attributes.
        See Also:
        Constant Field Values

    • Constructor Detail

      • SharedConfigurationState

        public SharedConfigurationState()

    • Method Detail

      • get

        public <V> V get​(java.lang.Class<?> key)
        Note: in spite of fact that class is used for key, actual value is stored with full class name string. So classes, loaded from different class loaders will lead to the same value.
        Type Parameters:
        V - shared object type
        Parameters:
        key - shared object key
        Returns:
        value or null

      • get

        public <V> V get​(java.lang.Class<?> key,
                 java.util.function.Supplier<V> defaultValue)
        Get value or declare default if value not set yet.
        Type Parameters:
        V - shared object type
        Parameters:
        key - shared object key
        defaultValue - default shared object provider
        Returns:
        stored or default (just stored) value

      • getOrFail

        public <V> V getOrFail​(java.lang.Class<?> key,
                       java.lang.String message,
                       java.lang.Object... args)
        Shortcut for get(Class) to immediately fail if value not set. Supposed to be used by shared state consumers (to validate situations when value must exists for sure).
        Type Parameters:
        V - 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:
        stored object (never null)
        Throws:
        java.lang.IllegalStateException - if value not set

      • getBootstrap

        public <C extends io.dropwizard.Configuration> javax.inject.Provider<io.dropwizard.setup.Bootstrap<C>> getBootstrap()
        Bootstrap object is available since guice bundle initialization start. It will not be available for hooks (because hooks processed before guice bundle initialization call - no way to get boostrap reference).
        Type Parameters:
        C - configuration type
        Returns:
        bootstrap instance provider (would fail if called too early)

      • getApplication

        public <C extends io.dropwizard.Configuration> javax.inject.Provider<io.dropwizard.Application<C>> getApplication()
        Application object is available since guice bundle initialization start.
        Type Parameters:
        C - configuration type
        Returns:
        application instance provider (would fail if called too early)

      • getEnvironment

        public javax.inject.Provider<io.dropwizard.setup.Environment> getEnvironment()
        Environment instance is available since guice bundle run.
        Returns:
        environment instance provider (would fail if called too early)

      • getConfiguration

        public <C extends io.dropwizard.Configuration> javax.inject.Provider<C> getConfiguration()
        Configuration instance is available since guice bundle run.
        Type Parameters:
        C - configuration type
        Returns:
        configuration instance provider (would fail if called too early)

      • getConfigurationTree

        public javax.inject.Provider<ConfigurationTree> getConfigurationTree()
        Configuration instance is available since guice bundle run.
        Returns:
        configuration tree instance provider (would fail if called too early)

      • getInjector

        public javax.inject.Provider<com.google.inject.Injector> getInjector()
        Injector instance is created under guice bundle run.
        Returns:
        configuration instance provider (would fail if called too early)
        See Also:
        for simpler lookup method

      • put

        public void put​(java.lang.Class<?> key,
                java.lang.Object value)
        Assumed to be used to store some configuration during startup. For example, if multiple bundle instances should know of each other - they could use shared state to communicate.

        Class is used for key to avoid dummy mistakes with strings (in most cases bundle class would be key). But internally string class name is used in order to unify classes from different class loaders.

        Note: warning will be printed if existing state value is overridden because it is assumed that some global configuration object would be shared once and later all participants will work with the same object.

        Parameters:
        key - shared object key
        value - shared value (usually configuration object)

      • getKeys

        public java.util.Set<java.lang.String> getKeys()
        Note: each key is a full name of registration class.
        Returns:
        all available keys

      • toString

        public java.lang.String toString()
        Overrides:
        toString in class java.lang.Object

      • assignTo

        protected void assignTo​(io.dropwizard.Application application)
        Called on initialization phase to assign registry instance to application (to be able to statically reference registry).
        Parameters:
        application - application instance

      • listen

        protected void listen​(io.dropwizard.setup.Environment environment)
        Called on run phase to assign to application lifecycle and listen for shutdown.
        Parameters:
        environment - environment object

      • forgetStartupInstance

        protected void forgetStartupInstance()
        Called after application startup to cleanup thread local instance. After this moment call to getStartupInstance() would lead to exception (since that moment it is not a problem to obtain application or environment instances and resolve state with them).

      • getStartupInstance

        public static SharedConfigurationState getStartupInstance()
        During application startup it is not always possible to lookup configuration state with Application or Environment objects. For such cases simplified static call can be used. For example, in binding installer call, bundles lookup implementation, hook.

        IMPORTANT: It will work only during application startup and only from main application thread! Would not be available in application run method (becuase at this point guice bundle is already processed).

        Returns:
        shared configuration state instance
        Throws:
        java.lang.NullPointerException - if called after startup, from non-main thread or before guice bundle registration (too early).

      • lookup

        public static <V> java.util.Optional<V> lookup​(io.dropwizard.Application application,
                                               java.lang.Class<?> key)
        Static lookup for registry value.
        Type Parameters:
        V - shared object key
        Parameters:
        application - application instance
        key - shared object key
        Returns:
        value optional

      • lookup

        public static <V> java.util.Optional<V> lookup​(io.dropwizard.setup.Environment environment,
                                               java.lang.Class<?> key)
        Static lookup for registry value by environment instance.
        Type Parameters:
        V - shared object key
        Parameters:
        environment - dropwizard environment object
        key - shared object key
        Returns:
        value optional

      • lookupOrFail

        public static <V> V lookupOrFail​(io.dropwizard.Application application,
                                 java.lang.Class<?> key,
                                 java.lang.String message,
                                 java.lang.Object... args)
        Shortcut for lookup(Application, Class) to immediately fail if value is not available.
        Type Parameters:
        V - shared object type
        Parameters:
        application - application instance
        key - shared object key
        message - exception message (could use String.format(String, Object...) placeholders)
        args - placeholder arguments for error message
        Returns:
        value (never null)
        Throws:
        java.lang.IllegalStateException - if value not available

      • lookupOrFail

        public static <V> V lookupOrFail​(io.dropwizard.setup.Environment environment,
                                 java.lang.Class<?> key,
                                 java.lang.String message,
                                 java.lang.Object... args)
        Shortcut for lookup(Environment, Class) to immediately fail if value is not available.
        Type Parameters:
        V - shared object type
        Parameters:
        environment - environment instance
        key - shared object key
        message - exception message (could use String.format(String, Object...) placeholders)
        args - placeholder arguments for error message
        Returns:
        value (never null)
        Throws:
        java.lang.IllegalStateException - if value not available

      • get

        public static java.util.Optional<SharedConfigurationState> get​(io.dropwizard.Application application)
        Static lookup for entire application registry.
        Parameters:
        application - application instance
        Returns:
        optional of application registry (may be empty if called too early or too late)

      • get

        public static java.util.Optional<SharedConfigurationState> get​(io.dropwizard.setup.Environment environment)
        Static lookup for entire application registry by environment instance.
        Parameters:
        environment - environment instance
        Returns:
        optional of application registry (may be empty if called too early or too late)

      • getOrFail

        public static SharedConfigurationState getOrFail​(io.dropwizard.Application application,
                                                 java.lang.String message,
                                                 java.lang.Object... args)
        Shortcut for get(Application) to immediately fail if registry is not available.
        Parameters:
        application - application instance
        message - exception message (could use String.format(String, Object...) placeholders)
        args - placeholder arguments for error message
        Returns:
        registry (never null)
        Throws:
        java.lang.IllegalStateException - if no state is associated with application yet

      • getOrFail

        public static SharedConfigurationState getOrFail​(io.dropwizard.setup.Environment environment,
                                                 java.lang.String message,
                                                 java.lang.Object... args)
        Shortcut for get(Environment) to immediately fail if registry is not available.
        Parameters:
        environment - environment instance
        message - exception message (could use String.format(String, Object...) placeholders)
        args - placeholder arguments for error message
        Returns:
        registry (never null)
        Throws:
        java.lang.IllegalStateException - if no state is associated with application yet

      • clear

        public static void clear()
        Clears stored injectors references. Normally shouldn't be used at all, because managed object will detect application shutdown and remove assigned state (for example, when used DropwizardAppRule or GuiceyAppRule).

        May be useful in tests, when application was not shut down properly (but just to clear memory).

        WARNING: calling this method while application is working may cause incorrect behaviour.

      • statesCount

        public static int statesCount()
        Could be useful only in tests in order to validate possibly stale applications.
        Returns:
        number of registered contexts