content/config/userguide.ad

title=Geronimo Config User Guide
date=2017-09-19
type=page
status=published
~~~~~~

= Using Geronimo Config

To get started with Geronimo Config, you'll want to add the dependencies to the project.  Eclipse MicroProfile Config is a transitive dependency, it will come in automatically as a dependency.

If you're using Maven:

```
<dependency>
    <groupId>org.apache.geronimo.config</groupId>
    <artifactId>geronimo-config-impl</artifactId>
    <version>1.0</version>
</dependency>
```

If you're using Gradle:

```
dependencies {
     compile 'org.apache.geronimo.config:geronimo-config-impl:1.0'
}
```

== General Use Cases

=== Registering Config Sources

`ConfigSource` implementations can be registered via `ServiceLoader`.  Declare a `ServiceLoader` of type `ConfigSource` or `ConfigSourceProvider` to link:https://github.com/eclipse/microprofile-config/blob/1.1/spec/src/main/asciidoc/configsources.asciidoc#custom-configsources[register these classes].

=== Default Config Sources

By default, we register a `ConfigSource` for System Properties as well as Environment Variables.

Environment Variables are attempted using both `.` as well as `_`, meaning a property lookup for `my.config.property` will search both `my.config.property` as well as `my_config_property`, to conform to naming convention standards for environment variables.

System Properties are loaded on start up, copying the values into the config source instance.  You can change this behavior by:
- disabling default config source loading, and manually registering a `SystemPropertyConfigSource` passing in `false` in the constructor
- Set the system property `org.apache.geronimo.config.configsource.SystemPropertyConfigSource.copy` to `false`

== CDI Use Cases

Being an implementation of a MicroProfile specification, it favors use cases based on CDI.  Most of the heavy lifting is done for you when using CDI.

=== Injecting Config

The MicroProfile `Config` interface is supported as an injection point.  It is an `@ApplicationScoped` bean, loaded from the result of `ConfigProvider.getConfig()`.

```
@Inject
private Config config
```
Will allow you to use the default `Config` object for your application.  All of the operations of `Config` match the MicroProfile Specification.

=== Injecting Config Properties

Injecting `@ConfigProperty` link:https://github.com/eclipse/microprofile-config/blob/1.1/spec/src/main/asciidoc/configexamples.asciidoc#simple-dependency-injection-example[works based on the specification].

In addition to the defined supported types, Geronimo Config supports injecting `Supplier<T>` where `T` is any type that has a supported `Converter`.

== Non-CDI Use Cases

You may not be using CDI, or do not want to use the built in CDI integration.  You can then using the programmatic look up for the configuration.

```java
Config config = ConfigProviderResolver.instance().getBuilder()
    .addDefaultSources() // built in config sources (system properties, environment variables and microprofile-config.properties
    .addDiscoveredConverters() // converters discovered via ServiceLoader
    .addDiscoveredSources() // sources discovered via ServiceLoader
    .withConverters() // list of converter instances, cannot be lambda expressions
    .withSources() // list of config source instances
    .forClassLoader() // the classloader associated with this config
    .build()
```

This will register and build a `Config` object for use.  You will need to keep track of that created instance.  If you want it to be managed automatically, you can then register it

```java
ConfigProviderResolver.instance().registerConfig(config, classLoader);
```