= Vert.x Config

Vert.x Config provides a way to configure your Vert.x application.
It:

* offers multiple configuration syntaxes (JSON, properties, Yaml (extension), Hocon
(extension)...
* offers multiple configuration stores such as files, directories, HTTP, git (extension), Redis
(extension), system properties and environment properties.
* lets you define the processing order and overloading
* supports runtime reconfiguration

== Concepts

The library is structured around:

**Config Retriever** instantiated and used by the Vert.x application. It
configures a set of configuration store
**Configuration store** defines a location from where the configuration data is read and also a format (JSON by default)

The configuration is retrieved as a JSON Object.

== Using the Config Retriever

To use the Config Retriever, add the following dependency to the
_dependencies_ section of your build descriptor:

* Maven (in your `pom.xml`):

[source,xml,subs="+attributes"]
----
<dependency>
  <groupId>io.vertx</groupId>
  <artifactId>vertx-config</artifactId>
  <version>${maven.version}</version>
</dependency>
----

* Gradle (in your `build.gradle` file):

[source,groovy,subs="+attributes"]
----
compile 'io.vertx:vertx-config:${maven.version}'
----

Once done, you first need to instantiate the {@link io.vertx.config.ConfigRetriever}:

[source]
----
{@link examples.ConfigExamples#example1(io.vertx.core.Vertx)}
----

By default, the Config Retriever is configured with the following stores (in
this order):

* The Vert.x verticle `config()`
* The system properties
* The environment variables
* A `conf/config.json` file. This path can be overridden using the `vertx-config-path` system property or
`VERTX_CONFIG_PATH` environment variable.

You can configure your own stores:

[source]
----
{@link examples.ConfigExamples#example2(io.vertx.core.Vertx)}
----

More details about the overloading rules and available stores are available below. Each store can be marked as
`optional`. If a failure is caught while retrieving (or processing) the configuration from an optional store, the failure
is logged, but the processing does not fail. Instead, an empty JSON object is returned (`{}`). To mark a store as
optional, use the `optional` attribute:

[source]
----
{@link examples.ConfigExamples#example2_optional(io.vertx.core.Vertx)}
----

Once you have the instance of the Config Retriever, _retrieve_ the configuration
as follows:

[source]
----
{@link examples.ConfigExamples#example3(ConfigRetriever)}
----

== Overloading rules

The declaration order of the configuration store is important as it defines the
overloading. For conflicting key, configuration stores arriving _last_ overloads the
value provided by the previous configuration stores. Let's take an example. We have 2
configuration stores:

* `A` provides `{a:value, b:1}`
* `B` provides `{a:value2, c:2}`

Declared in this order (A, B), the resulting configuration would be:
`{a:value2, b:1, c:2}`.

If you declare them in the reverse order (B, A), you will get: `{a:value, b:1, c:2}`.

== Using the retrieve configuration

The retrieve configuration allows:

* configuring verticles,
* configure ports, clients, locations and so on,
* configuring Vert.x itself

This section gives a few examples of usage.

=== Configuring a single verticle

The following example can be placed in the `start` method of a verticle. It retrieves the configuration (using the
default stores), and configure an HTTP server with the content of the configuration.

[source]
----
{@link examples.HttpGreetingVerticle#start()}
----

=== Configuring a set of verticles

The following example configures 2 verticles using the configurations contained in the `verticles.json` file:

[source]
----
{@link examples.VerticleDeployment#deploymentOfVerticles()}
----

=== Configuring Vert.x itself

You can also configure Vert.x directly. For this, you need a temporary Vert.x instance used to retrieve the
configuration. Then the actual instance is created:

[source]
----
{@link examples.VerticleDeployment#configureVertx()}
----

=== Propagating configuration changes to the event bus

Vert.x Config notifies you when the configuration changes. If you want to react to this event, you need to implement
the reaction yourself. For instance, you can un-deploy and redeploy verticle or send the new configuration on the event bus.
The following example shows this latter case. It sends the new configuration on the event bus. Interested verticles can
listen for this address and update themselves:

[source]
----
{@link examples.VerticleDeployment#propagateConfigurationInTheEventBus()}
----

== Available configuration stores

The Config Retriever provides a set of configuration stores and formats.
More are available as extensions, and you can also implement your own.

=== Structure of the configuration

Each declared data store must specify the `type`. It can also define the `format`. If
not set JSON is used.

Some configurations tore requires additional configuration (such a path...). This
configuration is passed as a Json Object using {@link io.vertx.config.ConfigStoreOptions#setConfig(io.vertx.core.json.JsonObject)}

=== File

This configuration store just read the configuration from a file. It supports all
supported formats.

[source, $lang]
----
{@link examples.ConfigExamples#file()}
----

The `path` configuration is required.

=== JSON

The JSON configuration store serves the given JSON config as it is.

[source, $lang]
----
{@link examples.ConfigExamples#json()}
----

The only supported format for this configuration store is JSON.

=== Environment Variables

This configuration store transforms environment variables to a JSON Object contributed to
the global configuration.

[source, $lang]
----
{@link examples.ConfigExamples#env()}
----

This configuration store does not support the `format` configuration. By default, the retrieved value is
transformed into JSON compatible structures (number, string, boolean, JSON object and JSON array). To avoid this
conversion, configure the `raw-data` attribute:

[source, $lang]
----
{@link examples.ConfigExamples#env2()}
----

You can configure the `raw-data` attribute (`false` by default). If `raw-data` is `true` no attempts to convert
values are made, and you'll be able to get raw values using `config.getString(key)`. It is useful when manipulating
large integers.

If you want to select the set of keys to import, use the `keys` attributes. It filters out all not selected keys. Keys
must be listed individually:

[source, $lang]
----
{@link examples.ConfigExamples#env3()}
----

=== System Properties

This configuration store transforms system properties to a JSON Object contributed to the
global configuration.

[source, $lang]
----
{@link examples.ConfigExamples#sys()}
----

This configuration store does not support the `format` configuration.

You can configure the `cache` attribute (`true` by default) let you decide whether or
not it caches the system properties on the first access and does not reload them.

You can also configure the `raw-data` attribute (`false` by default). If `raw-data` is `true` no attempts to convert
values are made, and you'll be able to get raw values using `config.getString(key)`. It is useful when manipulating
large integers.

Furthermore, there is the `hierarchical` attribute (`false` by default). If `hierarchical` is `true`, the system
properties will be parsed as a nested JSON object, using the dot-separated property name as the path in the JSON object.

Example:

[source, $lang]
----
{@link examples.ConfigExamples#sysHierarchical()}
----
....
java -Dserver.host=localhost -Dserver.port=8080 -jar your-application.jar
....

This will read the system properties as JSON object equivalent to

[source,json]
----
{
  "server": {
    "host": "localhost",
    "port": 8080
  }
}
----

=== HTTP

This configuration store retrieves the configuration from an HTTP location. It can use
any supported format.

[source, $lang]
----
{@link examples.ConfigExamples#http()}
----

It creates a Vert.x HTTP Client with the store configuration (see next snippet). To
ease the configuration; you can also configure the `host`, `port` and `path` with the
`host`, `port` and `path`
properties. You can also configure optional HTTP request headers with `headers` property,
the timeout (in milliseconds, 3000 by default) to retrieve the configuration with `timeout` property,
if following redirects (false by default) with `followRedirects` property.

[source, $lang]
----
{@link examples.ConfigExamples#http2()}
----

=== Event Bus

This event bus configuration store receives the configuration from the event bus. This
stores let you distribute your configuration among your local and distributed components.

[source, $lang]
----
{@link examples.ConfigExamples#eb()}
----

This configuration store supports any format.

=== Directory

This configuration store is similar to the `file` configuration store, but instead of
reading a single file, read several files from a directory.

This configuration store configuration requires:

* a `path` - the root directory in which files are located
* at least one `fileset` - an object to select the files
* for properties file, you can indicate if you want to disable the type conversion using the `raw-data` attribute

Each `fileset` contains:

* a `pattern` : an Ant-style pattern to select files. The pattern is applied to the
relative path of the files from the current working directory.
* an optional `format` indicating the format of the files (each fileset can use a
different format, BUT files in a fileset must share the same format).

[source, $lang]
----
{@link examples.ConfigExamples#dir()}
----

=== Properties file and raw data

Vert.x Config can read a properties file. When reading such a file, you can pass the `raw-data` attribute to
indicate to Vert.x to not attempt to convert values. It is useful when manipulating large integers. Values can be
retrieved using `config.getString(key)`.

[source, $lang]
----
{@link examples.ConfigExamples#propsWithRawData()}
----

Some properties configuration maybe is hierarchical in nature.
When reading such a file, you can pass the `hierarchical` attribute to
indicate to Vert.x to convert the configuration to a json object while maintaining this hierarchy,
in contrast to the previous method with a flat structure.

Example:

....
server.host=localhost
server.port=8080
multiple.values=1,2,3
....

Get values:

[source, $lang]
----
{@link examples.ConfigExamples#propsWithHierarchicalStructure()}
----

== Listening for configuration changes

The Configuration Retriever periodically retrieves the configuration, and if the outcome
is different from the current one, your application can be reconfigured. By default, the
configuration is reloaded every 5 seconds.

[source, $lang]
----
{@link examples.ConfigExamples#period}
----

== Retrieving the last retrieved configuration

You can retrieve the last retrieved configuration without "waiting" to be retrieved
using:

[source, $lang]
----
{@link examples.ConfigExamples#cache(ConfigRetriever)}
----

== Reading configuration as a stream

The {@link io.vertx.config.ConfigRetriever} provide a way to access the stream of configuration.
It's a {@link io.vertx.core.streams.ReadStream} of {@link io.vertx.core.json.JsonObject}. By registering the right
set of handlers you are notified:

* when a new configuration is retrieved
* when an error occur while retrieving a configuration
* when the configuration retriever is closed (the
{@link io.vertx.core.streams.ReadStream#endHandler(io.vertx.core.Handler)} is called).

[source, $lang]
----
{@link examples.ConfigExamples#stream}
----

== Processing the configuration

You can configure a _processor_ that can validate and update the configuration. This is done using the
{@link io.vertx.config.ConfigRetriever#setConfigurationProcessor(java.util.function.Function)} method.

The processing must not return `null`. It takes the retrieved configuration and returns the processed one. If the processor
does not update the configuration, it must return the input configuration. If the processor can throw an exception (for
example for validation purpose).

== Retrieving the configuration as a Future

The {@link io.vertx.config.ConfigRetriever} provide a way to retrieve the configuration as a
{@link io.vertx.core.Future}:

[source, $lang]
----
{@link examples.ConfigExamples#future(io.vertx.config.ConfigRetriever)}
----

== Extending the Config Retriever

You can extend the configuration by implementing:

* the {@link io.vertx.config.spi.ConfigProcessor} SPI to add support for a
format
* the {@link io.vertx.config.spi.ConfigStoreFactory} SPI to add support for
configuration store (place from where the configuration data is retrieved)

== Additional formats

Besides the out of the box format supported by this library, Vert.x Config provides additional
formats you can use in your application.

include::hocon-format.adoc[]

include::yaml-format.adoc[]

== Additional stores

Besides the out of the box stores supported by this library, Vert.x Config provides additional
stores you can use in your application.

include::git-store.adoc[]

include::kubernetes-store.adoc[]

include::redis-store.adoc[]

include::zookeeper-store.adoc[]

include::consul-store.adoc[]

include::spring-store.adoc[]

include::vault-store.adoc[]
