The Vert.x Configuration retriever provides a way to configure your Vert.x application.
It:
-
offer multiple configuration syntaxes (json, properties, yaml (extension), hocon (extension)…
-
offer multiple configuration stores (files, directories, http, git (extension), redis (extension), system properties, environment properties)…
-
let you define the processing order and overloading
-
support runtime reconfiguration
Concepts
The configuration retriever is structured around:
-
a Configuration 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 and a syntax (json by default)
The configuration is retrieved as a JSON Object.
Using the Vert.x Configuration Retriever
To use the Vert.x Configuration Retriever, add the following dependency to the dependencies section of your build descriptor:
-
Maven (in your
pom.xml
):
<dependency>
<groupId>io.vertx</groupId>
<artifactId>vertx-config</artifactId>
<version>3.4.0.Beta1</version>
</dependency>
-
Gradle (in your
build.gradle
file):
compile 'io.vertx:vertx-config:3.4.0.Beta1'
Once done, you first need to instantiate the ConfigRetriever
:
var ConfigRetriever = require("vertx-config-js/config_retriever");
var retriever = ConfigRetriever.create(vertx);
By default the Vert.x Configuration Retriever is configured with the following stores (in this order):
-
The Vert.x verticle
config()
-
The system properties
-
The environment variables
You can configure your own stores:
var ConfigRetriever = require("vertx-config-js/config_retriever");
var httpStore = {
"type" : "http",
"config" : {
"host" : "localhost",
"port" : 8080,
"path" : "/conf"
}
};
var fileStore = {
"type" : "file",
"config" : {
"path" : "my-config.json"
}
};
var sysPropsStore = {
"type" : "sys"
};
var options = {
"stores" : [
httpStore,
fileStore,
sysPropsStore
]
};
var retriever = ConfigRetriever.create(vertx, options);
More details about the overloading rules and available stores are available below.
Once you have the instance of the Vert.x Configuration Retriever, retrieve the configuration as follows:
retriever.getConfig(function (ar, ar_err) {
if (ar_err != null) {
// Failed to retrieve the configuration
} else {
var config = ar;
}
});
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 would get: * {a:value, b:1, c:2}
.
Available configuration stores
The Vert.x Configuration Retriever provides a set of configuration store and format. Some more are available as extension and you can 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 config
File
This configuration store just read the configuration from a file. It supports all supported formats.
var file = {
"type" : "file",
"format" : "properties",
"config" : {
"path" : "path-to-file.properties"
}
};
The path
configuration is required.
JSON
The JSON configuration store just serves the given JSON config as it is.
var json = {
"type" : "json",
"config" : {
"key" : "value"
}
};
The only supported format for this configuration store is JSON.
Environment Variables
This configuration store maps environment variables to a Json Object contributed to the global configuration.
var json = {
"type" : "env"
};
This configuration store does not support the format
configuration.
System Properties
This configuration store maps system properties to a Json Object contributed to the global configuration.
var json = {
"type" : "sys",
"config" : {
"cache" : "false"
}
};
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.
HTTP
This configuration stores retrieves the configuration from a HTTP location. It can use any supported format.
var http = {
"type" : "http",
"config" : {
"host" : "localhost",
"port" : 8080,
"path" : "/A"
}
};
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.
var http = {
"type" : "http",
"config" : {
"defaultHost" : "localhost",
"defaultPort" : 8080,
"ssl" : true,
"path" : "/A"
}
};
Event Bus
This event bus configuration stores receives the configuration from the event bus. This stores let you distribute your configuration among your local and distributed components.
var eb = {
"type" : "event-bus",
"config" : {
"address" : "address-getting-the-conf"
}
};
This configuration store supports any type of 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
Each fileset
contains:
* a pattern
: a Ant style pattern to select files. The pattern is applied on the
relative path of the files location in the 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).
var dir = {
"type" : "directory",
"config" : {
"path" : "config",
"filesets" : [
{
"pattern" : "dir/*json"
},
{
"pattern" : "dir/*.properties",
"format" : "properties"
}
]
}
};
Listening for configuration changes
The Configuration Retriever periodically retrieve 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.
var Vertx = require("vertx-js/vertx");
var ConfigRetriever = require("vertx-config-js/config_retriever");
var options = {
"scanPeriod" : 2000,
"stores" : [
store1,
store2
]
};
var retriever = ConfigRetriever.create(Vertx.vertx(), options);
retriever.getConfig(function (json, json_err) {
// Initial retrieval of the configuration
});
retriever.listen(function (change) {
// Previous configuration
var previous = change.previousConfiguration;
// New configuration
var conf = change.newConfiguration;
});
Retrieving the last retrieved configuration
You can retrieved the last retrieved configuration without "waiting" to be retrieved using:
var last = retriever.getCachedConfig();
Reading configuration as a stream
The ConfigRetriever
provide a way to access the stream of configuration.
It’s a ReadStream
of 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
endHandler
is called).
var Vertx = require("vertx-js/vertx");
var ConfigRetriever = require("vertx-config-js/config_retriever");
var options = {
"scanPeriod" : 2000,
"stores" : [
store1,
store2
]
};
var retriever = ConfigRetriever.create(Vertx.vertx(), options);
retriever.configStream().endHandler(function (v) {
// retriever closed
}).exceptionHandler(function (t) {
// an error has been caught while retrieving the configuration
}).handler(function (conf) {
// the configuration
});
Retrieving the configuration as a Future
The ConfigRetriever
provide a way to retrieve the configuration as a
Future
:
var ConfigRetriever = require("vertx-config-js/config_retriever");
var future = ConfigRetriever.getConfigAsFuture(retriever);
future.setHandler(function (ar, ar_err) {
if (ar_err != null) {
// Failed to retrieve the configuration
} else {
var config = ar;
}
});
Extending the Configuration Retriever
You can extend the configuration by implementing:
-
the
io.vertx.config.spi.ConfigurationProcessor
SPI to add support for a format -
the
io.vertx.config.spi.ConfigurationStoreFactory
SPI to add support for configuration store (place from where the configuration data is retrieved)