Class GuiceyEnvironment
- java.lang.Object
-
- ru.vyarus.dropwizard.guice.module.installer.bundle.GuiceyEnvironment
-
public class GuiceyEnvironment extends java.lang.Object
Guicey environment object. Provides almost the same configuration methods asGuiceBundle.Builder
. Also, contains dropwizard configuration and environment objects.As it is called on run phase, it does not allow to install or disable new bundles and installers.
- Since:
- 13.06.2019
-
-
Constructor Summary
Constructors Constructor Description GuiceyEnvironment(ConfigurationContext context)
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description io.dropwizard.core.Application
application()
Application instance may be useful for complex (half manual) integrations where access for injector is required.<T extends io.dropwizard.core.Configuration>
Tconfiguration()
<T,K extends T>
Kconfiguration(java.lang.Class<T> type)
May be used to access unique sub configuration object.<T> T
configuration(java.lang.String yamlPath)
May be used to access current configuration value by exact path.<T> java.util.List<? extends T>
configurations(java.lang.Class<T> type)
IMPORTANT: method semantic is different fromconfiguration(Class)
, which use direct class declaration match, whereas this method searches by all assignable types.ConfigurationTree
configurationTree()
Raw configuration introspection info.GuiceyEnvironment
disableExtensions(java.lang.Class<?>... extensions)
GuiceyEnvironment
disableModules(java.lang.Class<? extends com.google.inject.Module>... modules)
Disable both usual and overriding guice modules.io.dropwizard.core.setup.Environment
environment()
GuiceyEnvironment
listen(GuiceyLifecycleListener... listeners)
Guicey broadcast a lot of events in order to indicate lifecycle phases (GuiceyLifecycle).GuiceyEnvironment
listenJetty(org.eclipse.jetty.util.component.LifeCycle.Listener listener)
Shortcut for jetty lifecycle listenerlistener
registration.GuiceyEnvironment
listenServer(io.dropwizard.lifecycle.ServerLifecycleListener listener)
Shortcut forServerLifecycleListener
registration.GuiceyEnvironment
manage(io.dropwizard.lifecycle.Managed managed)
Shortcut for manual registration ofManaged
objects.GuiceyEnvironment
modules(com.google.inject.Module... modules)
Register guice modules.GuiceyEnvironment
modulesOverride(com.google.inject.Module... modules)
Override modules (using guiceModules.override(Module...)
).GuiceyEnvironment
onApplicationStartup(ApplicationStartupListener listener)
Code to execute after complete application startup.GuiceyEnvironment
onGuiceyStartup(GuiceyStartupListener listener)
Code to execute after guice injector creation (but still under run phase).<V,T extends java.lang.Enum & Option>
Voption(T option)
Read option value.GuiceyEnvironment
register(java.lang.Class<?>... items)
Shortcut forenvironment().jersey().register()
for direct registration of jersey extensions.GuiceyEnvironment
register(java.lang.Object... items)
Shortcut forenvironment().jersey().register()
for direct registration of jersey extensions.<T> java.util.Optional<T>
sharedState(java.lang.Class<?> key)
Access shared value.<T> T
sharedState(java.lang.Class<?> key, java.util.function.Supplier<T> defaultValue)
Alternative shared value initialization for cases when first accessed bundle should init state value and all other just use it.<T> T
sharedStateOrFail(java.lang.Class<?> 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).GuiceyEnvironment
shareState(java.lang.Class<?> key, java.lang.Object value)
Share global state to be used in other bundles (during configuration).
-
-
-
Constructor Detail
-
GuiceyEnvironment
public GuiceyEnvironment(ConfigurationContext context)
-
-
Method Detail
-
configuration
public <T extends io.dropwizard.core.Configuration> T configuration()
- Type Parameters:
T
- configuration type- Returns:
- configuration instance
-
configuration
public <T> T configuration(java.lang.String yamlPath)
May be used to access current configuration value by exact path. This is helpful for bundles universality: suppose bundle X requires configuration object XConf, which is configured somewhere inside application configuration. We can require configuration path in bundle constructor and use it to access required configuration object:new X("sub.config.path")
.- Type Parameters:
T
- value type- Parameters:
yamlPath
- target value yaml path- Returns:
- configuration value by path or null if value is null or path not exists
- See Also:
for custom configuration searches
-
configuration
public <T,K extends T> K configuration(java.lang.Class<T> type)
May be used to access unique sub configuration object. This is helpful for bundles universality: suppose bundle X requires configuration object XConf and we are sure that only one declaration of XConf would be used in target configuration class, then we can simply request it:configuration(XConf.class) == <instance of XConf or null>
.Note that uniqueness is checked by declaration class:
are unique declarations (declaration of the same type never appears in configuration on any level).class Config extends Configuration { Sub sub; SubExt ext; // SubExt extends Sub }
configuration(Sub.class) == sub
andconfiguration(SubExt.class) == ext
.Example of accessing server config from dropwizard configuration:
configuration(ServerFactory.class) == DefaultServerFactory (or SimpleServerFactory)
(see dropwizardConfiguration
class).- Type Parameters:
T
- declaration typeK
- required value type (may be the same or extending type)- Parameters:
type
- target configuration declaration type- Returns:
- unique configuration value or null if value is null or no declaration found
- See Also:
for custom configuration searches
-
configurations
public <T> java.util.List<? extends T> configurations(java.lang.Class<T> type)
IMPORTANT: method semantic is different fromconfiguration(Class)
, which use direct class declaration match, whereas this method searches by all assignable types.class Config extends Configuration { Sub sub; SubExt ext; // SubExt extends Sub }
configurations(Sub.class) == [sub, ext]
, butconfigurations(SubExt.class) == [ext]
.Useful when multiple sub configuration objects could be used and all of them are required in some universal bundle.
Note: only custom types may be used (sub configuration objects), not Integer, Boolean, List, etc.
- Type Parameters:
T
- value type- Parameters:
type
- target configuration type- Returns:
- list of configuration values with required type or empty list
- See Also:
for custom configuration searches
-
configurationTree
public ConfigurationTree configurationTree()
Raw configuration introspection info. Could be used for more sophisticated configuration searches then provided in shortcut methods.Note that configuration is analyzed using jackson serialization api, so not all configured properties could be visible (when property getter is not exists or field not annotated).
Returned object contains all resolved configuration paths. Any path element could be traversed like a tree. See find* and value* methods as an examples of how stored paths could be traversed.
- Returns:
- detailed configuration object
- See Also:
for configuration introspection details
,for available guice configuration bindings
-
environment
public io.dropwizard.core.setup.Environment environment()
- Returns:
- environment instance
-
application
public io.dropwizard.core.Application application()
Application instance may be useful for complex (half manual) integrations where access for injector is required. For example, manually registeredManaged
may access injector in it's start method by callingInjectorLookup.getInjector(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.
- Returns:
- dropwizard application instance
-
option
public <V,T extends java.lang.Enum & Option> V option(T option)
Read option value. Options could be set only in application rootGuiceBundle.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 typeT
- helper type to define option- Parameters:
option
- option enum- Returns:
- assigned option value or default value
- See Also:
more options info
,options example
,options definition
-
modules
public GuiceyEnvironment modules(com.google.inject.Module... modules)
Register guice modules.Note that this registration appear in run phase and so you already have access to environment and configuration (and don't 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:
- environment instance for chained calls
- See Also:
GuiceBundle.Builder.modules(com.google.inject.Module...)
-
modulesOverride
public GuiceyEnvironment modulesOverride(com.google.inject.Module... modules)
Override modules (using guiceModules.override(Module...)
).- Parameters:
modules
- overriding modules- Returns:
- environment instance for chained calls
- See Also:
GuiceBundle.Builder.modulesOverride(Module...)
-
disableExtensions
public final GuiceyEnvironment disableExtensions(java.lang.Class<?>... extensions)
- Parameters:
extensions
- extensions to disable (manually added, registered by bundles or with classpath scan)- Returns:
- environment instance for chained calls
- See Also:
GuiceBundle.Builder.disableExtensions(Class[])
-
disableModules
@SafeVarargs public final GuiceyEnvironment disableModules(java.lang.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:
- environment instance for chained calls
- See Also:
GuiceBundle.Builder.disableModules(Class[])
-
register
public GuiceyEnvironment register(java.lang.Object... items)
Shortcut forenvironment().jersey().register()
for direct registration of jersey extensions. For the most cases prefer automatic installation of jersey extensions with guicey installer.- Parameters:
items
- jersey extension instances to install- Returns:
- environment instance for chained calls
-
register
public GuiceyEnvironment register(java.lang.Class<?>... items)
Shortcut forenvironment().jersey().register()
for direct registration of jersey extensions. For the most cases prefer automatic installation of jersey extensions with guicey installer.- Parameters:
items
- jersey extension instances to install- Returns:
- environment instance for chained calls
-
manage
public GuiceyEnvironment manage(io.dropwizard.lifecycle.Managed managed)
Shortcut for manual registration ofManaged
objects.Pay attention that managed objects are not called for commands.
- Parameters:
managed
- managed to register- Returns:
- environment instance for chained calls
-
listen
public GuiceyEnvironment listen(GuiceyLifecycleListener... listeners)
Guicey broadcast a lot of events in order to indicate lifecycle phases (GuiceyLifecycle). Listener, registered in run phase could listen events fromGuiceyLifecycle.BundlesStarted
.Listener is not registered if equal listener was already registered (
Set
used as listeners storage), so if you need to be sure that only one instance of some listener will be used implementObject.equals(Object)
.- Parameters:
listeners
- guicey lifecycle listeners- Returns:
- bootstrap instance for chained calls
- See Also:
GuiceBundle.Builder.listen(GuiceyLifecycleListener...)
-
listenServer
public GuiceyEnvironment listenServer(io.dropwizard.lifecycle.ServerLifecycleListener listener)
Shortcut forServerLifecycleListener
registration.Note that server listener is called only when jetty starts up and so will not be called with lightweight guicey test helpers
TestGuiceyApp
. Prefer usingonApplicationStartup(ApplicationStartupListener)
to be correctly called in tests (of course, if not server only execution is desired).Obviously not called for custom command execution.
- Parameters:
listener
- server startup listener.- Returns:
- environment instance for chained calls
-
listenJetty
public GuiceyEnvironment listenJetty(org.eclipse.jetty.util.component.LifeCycle.Listener listener)
Shortcut for jetty lifecycle listenerlistener
registration.Lifecycle listeners are called with lightweight guicey test helpers
TestGuiceyApp
which makes them perfectly suitable for reporting.If only startup event is required, prefer
onApplicationStartup(ApplicationStartupListener)
method as more expressive and easier to use.Listeners are not called on custom command execution.
- Parameters:
listener
- jetty- Returns:
- environment instance for chained calls
-
shareState
public GuiceyEnvironment shareState(java.lang.Class<?> key, java.lang.Object 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)!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.
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)
.During application strartup, shared state could be requested with a static call
SharedConfigurationState.getStartupInstance()
, but only from main thread.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.- Parameters:
key
- shared object keyvalue
- shared object- Returns:
- bootstrap instance for chained calls
- See Also:
SharedConfigurationState
-
sharedState
public <T> T sharedState(java.lang.Class<?> key, java.util.function.Supplier<T> defaultValue)
Alternative shared value initialization for cases when first accessed bundle should init state value and all other 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:
T
- shared object type- Parameters:
key
- shared object keydefaultValue
- default object provider- Returns:
- shared object (possibly just created)
- See Also:
SharedConfigurationState
-
sharedState
public <T> java.util.Optional<T> sharedState(java.lang.Class<?> key)
Access shared value.- Type Parameters:
T
- shared object type- Parameters:
key
- shared object key- Returns:
- shared object
- See Also:
SharedConfigurationState
-
sharedStateOrFail
public <T> T sharedStateOrFail(java.lang.Class<?> 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).- Type Parameters:
T
- shared object type- Parameters:
key
- shared object keymessage
- exception message (could useString.format(String, Object...)
placeholders)args
- placeholder arguments for error message- Returns:
- shared object
- Throws:
java.lang.IllegalStateException
- if not value available- See Also:
SharedConfigurationState
-
onGuiceyStartup
public GuiceyEnvironment onGuiceyStartup(GuiceyStartupListener listener)
Code to execute after guice injector creation (but still under run phase). May be used for manual configurations (registrations into dropwizard environment).Listener will be called on environment command start too.
Note: there is no registration method for this listener in main guice bundle builder (
GuiceBundle.Builder
) because it is assumed, that such blocks would always be wrapped with bundles to improve application readability.- Parameters:
listener
- listener to call after injector creation- Returns:
- environment instance for chained calls
-
onApplicationStartup
public GuiceyEnvironment onApplicationStartup(ApplicationStartupListener listener)
Code to execute after complete application startup. For server command it would happen after jetty startup and for lightweight guicey test helpers (TestGuiceyApp
) - after guicey start (as jetty not started in this case). In both cases, application completely started at this moment. Suitable for reporting.If you need to listen only for real server startup then use
listenServer(ServerLifecycleListener)
instead.Not called on custom command execution (because no lifecycle involved in this case). In this case you can use
onGuiceyStartup(GuiceyStartupListener)
as always executed point.- Parameters:
listener
- listener to call on server startup- Returns:
- environment instance for chained calls
-
-