GuiceyEnvironment (dropwizard-guicey 5.1.0 API)

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 as GuiceBundle.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 and Description

GuiceyEnvironment(ConfigurationContext context)

Constructors
Constructor and Description
`GuiceyEnvironment(ConfigurationContext context)`

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`io.dropwizard.Application`	`application()` Application instance may be useful for complex (half manual) integrations where access for injector is required.
`<T extends io.dropwizard.Configuration> T`	`configuration()`
`<T,K extends T> K`	`configuration(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 from `configuration(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.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 listener `listener` registration.
`GuiceyEnvironment`	`listenServer(io.dropwizard.lifecycle.ServerLifecycleListener listener)` Shortcut for `ServerLifecycleListener` registration.
`GuiceyEnvironment`	`manage(io.dropwizard.lifecycle.Managed managed)` Shortcut for manual registration of `Managed` objects.
`GuiceyEnvironment`	`modules(com.google.inject.Module... modules)` Register guice modules.
`GuiceyEnvironment`	`modulesOverride(com.google.inject.Module... modules)` Override modules (using guice `Modules.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> V`	`option(T option)` Read option value.
`GuiceyEnvironment`	`register(java.lang.Class<?>... items)` Shortcut for `environment().jersey().register()` for direct registration of jersey extensions.
`GuiceyEnvironment`	`register(java.lang.Object... items)` Shortcut for `environment().jersey().register()` for direct registration of jersey extensions.
`<T> java.util.Optional<T>`	`sharedState(java.lang.Class<?> key)` Access shared value.
`<T> T`	`sharedStateOrFail(java.lang.Class<?> key, java.lang.String message, java.lang.Object... args)` Use to access shared state value and immediately fail if value not yet set (most likely due to incorrect configuration order).

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Constructor Detail
  - GuiceyEnvironment
```
public GuiceyEnvironment(ConfigurationContext context)
```
- Method Detail
  - configuration
```
public <T extends io.dropwizard.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:
```
 class Config extends Configuration {
     Sub sub;
     SubExt ext; // SubExt extends Sub
 }
```
    are unique declarations (declaration of the same type never appears in configuration on any level). configuration(Sub.class) == sub and configuration(SubExt.class) == ext.
    Example of accessing server config from dropwizard configuration: configuration(ServerFactory.class) == DefaultServerFactory (or SimpleServerFactory) (see dropwizard Configuration class).
    Type Parameters:
    
    T - declaration type
    
    K - 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 from configuration(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], but configurations(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.setup.Environment environment()
```
    Returns:
    
    environment instance
  - application
```
public io.dropwizard.Application 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(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 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
    
    T - 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 guice Modules.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 for environment().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 for environment().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 of Managed 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 from GuiceyLifecycle.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 implement Object.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 for ServerLifecycleListener registration.
    Note that server listener is called only when jetty starts up and so will no be called with lightweight guicey test helpers GuiceyAppRule or UseGuiceyApp. Prefer using onApplicationStartup(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 listener listener registration.
    Lifecycle listeners are called with lightweight guicey test helpers GuiceyAppRule or UseGuiceyApp 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
    
    See Also:
    
    adapter
  - sharedStateOrFail
```
public <T> T sharedStateOrFail(java.lang.Class<?> key,
                               java.lang.String message,
                               java.lang.Object... args)
```
    Use to access shared state value and immediately fail if value not yet set (most likely due to incorrect configuration order).
    Note: shared state value assumed to be initialized under initialization phase (but you can workaround this limitation by accessing shared state statically)
    
    Type Parameters:
    
    T - 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:
    
    java.lang.IllegalStateException - if not value available
    
    See Also:
    
    SharedConfigurationState
  - sharedState
```
public <T> java.util.Optional<T> sharedState(java.lang.Class<?> key)
```
    Access shared value. Shared state value assumed to be initialized under initialization phase (but you can workaround this limitation by accessing shared state statically)
    
    Type Parameters:
    
    T - shared object type
    
    Parameters:
    
    key - shared object key
    
    Returns:
    
    shared object
    
    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 jerry startup and for lightweight guicey test helpers (GuiceyAppRule or UseGuiceyApp) - 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

Class GuiceyEnvironment

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

GuiceyEnvironment

Method Detail

configuration

configuration

configuration

configurations

configurationTree

environment

application

option

modules

modulesOverride

disableExtensions

disableModules

register

register

manage

listen

listenServer

listenJetty

sharedStateOrFail

sharedState

onGuiceyStartup

onApplicationStartup