Many resources are needed to download a project. Please understand that we have to compensate our server costs. Thank you in advance. Project price only 1 $
You can buy this project and download/modify it how often you want.
///////////////////////////////////////////////////////////////////////////////
Copyright (c) 2018, 2024 Oracle and/or its affiliates.
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
///////////////////////////////////////////////////////////////////////////////
= Additional Supported Formats and Sources
:description: Helidon config supported formats and sources
:keywords: helidon, config
:feature-name: Config
:rootdir: {docdir}/../..
include::{rootdir}/includes/se.adoc[]
== Contents
- <>
- <>
- <>
== Overview
Helidon Config provides several extension modules that support other configuration
formats (parsers) and sources. This document describes how to include them and use them in your project. In each case you need to add module dependencies to your project and, in some cases, write your application accordingly.
== Additional Config Formats and Parsers
=== Automatic Media Type and File Type Handling
With each of the parsers described here, your application can either
1. explicitly add a parser of the correct implementation to the `Config.Builder`, or
2. rely on Java service loading and the config system's matching of file types and
media types to parsers.
If your application creates a `Config.Builder` with parser services _disabled_
(see link:{config-javadoc-base-url}/io/helidon/config/Config.Builder.html#disableParserServices--[`disableParserServices`]
then that builder will not find the Java services for the various parsers and so
will be unable to match the file type or media type of sources with the corresponding
parser automatically. So if you want to use automatic type
matching with a given builder, do not invoke `Config.Builder.disableParserServices()`.
=== YAML [[Config-ModuleYaml]]
==== Maven Coordinates
Add the following dependency in your project:
[source,xml]
.Config YAML Dependency in `pom.xml`
----
io.helidon.confighelidon-config-yaml
----
==== Using the YAML Parser
The YAML parser handles the following media type:
- `application/x-yaml` - YAML format (file type `.yaml`)
[source,java]
.Automatic selection
----
include::{sourcedir}/se/config/SupportedFormatsSnippets.java[tag=snippet_1, indent=0]
----
<1> The config system automatically maps the file type `.yaml` to the media type `application/x-yaml`
which the Helidon YAML parser matches.
[source,java]
.YAML parser specified - no file type on source
----
include::{sourcedir}/se/config/SupportedFormatsSnippets.java[tag=snippet_2, indent=0]
----
<1> The media type of the source `my-config` is unknown, so the config system
cannot choose a parser automatically.
<2> The config system will parse the resource `my-config` on the runtime classpath
using the YAML parser instance created by the
link:{config-javadoc-base-url}.yaml/io/helidon/config/yaml/YamlConfigParser.html[`YamlConfigParser`].
The `create()` method creates a config parser with default behavior.
[source,java]
.Media type specified
----
include::{sourcedir}/se/config/SupportedFormatsSnippets.java[tag=snippet_3, indent=0]
----
<1> The media type of the source `my-config` is unknown, so the config system
cannot choose a parser automatically.
<2> Specifying the media type for the config source allows the config system to
use its matching algorithm with the available parsers to choose a parser for that type.
[source,java]
.YAML parser specified because parser services disabled
----
include::{sourcedir}/se/config/SupportedFormatsSnippets.java[tag=snippet_4, indent=0]
----
<1> Disables automatic parser lookup and registration.
<2> Explicit registration of the YAML parser is therefore required.
=== HOCON/JSON [[Config-ModuleHocon]]
The Helidon HOCON config module handles sources in the
HOCON and JSON formats.
==== Maven Coordinates
Add the following dependency in your project:
[source,xml]
.Config HOCON Dependency in `pom.xml`
----
io.helidon.confighelidon-config-hocon
----
==== Using the HOCON/JSON Parser
The parser handles the following media types:
- `application/hocon` - HOCON format (file type `.conf`)
- `application/json` - JSON format (file type `.json`)
[source,java]
.Automatic selection
----
include::{sourcedir}/se/config/SupportedFormatsSnippets.java[tag=snippet_5, indent=0]
----
<1> The config system automatically maps the file type `.conf` to the media type `application/hocon
which the Helidon HOCON parser matches.
The same module and parser supports file type `.json` and the media type
`application/json`.
[source,java]
.HOCON parser specified - no file type on source
----
include::{sourcedir}/se/config/SupportedFormatsSnippets.java[tag=snippet_6, indent=0]
----
<1> the media type of the source `my-config` is unknown, so the config system cannot
choose a parser automatically.
<2> The config system will parse the resource `my-config` using the HOCON parser created
by the link:{config-javadoc-base-url}.hocon/io/helidon/config/hocon/HoconConfigParser.html[HoconConfigParser].
The `create()` method creates a config parser with default behavior.
[source,java]
.Media type specified
----
include::{sourcedir}/se/config/SupportedFormatsSnippets.java[tag=snippet_7, indent=0]
----
<1> The media type of the source `my-config` is unknown, so the config system
cannot choose a parser automatically.
<2> Specifying the media type for the config source allows the config system to
use its matching algorithm with the available parsers to choose a parser for that
type.
[source,java]
.HOCON parser specified because parser services disabled
----
include::{sourcedir}/se/config/SupportedFormatsSnippets.java[tag=snippet_8, indent=0]
----
<1> Disables automatic parser lookup and registration.
<2> Explicit registration of the HOCON parser is therefore required.
[source,java]
.Customized HOCON parser
----
include::{sourcedir}/se/config/SupportedFormatsSnippets.java[tag=snippet_9, indent=0]
----
<1> Creates new instance of the parser builder.
<2> Disables resolution of substitutions.
(See the link:https://github.com/lightbend/config/blob/master/HOCON.md#substitutions[HOCON documentation].)
<3> Builds a new instance of the HOCON config parser.
You can also specify
link:https://github.com/lightbend/config/blob/master/config/src/main/java/com/typesafe/config/ConfigResolveOptions.java[`ConfigResolveOptions`]
using the `HoconConfigParser.builder().resolveOptions` method.
== Additional Config Source Types
=== Etcd [[Config-ModuleEtcd]]
The Helidon Etcd config module supports reading configuration from a specified
Etcd key.
==== Maven Coordinates
Add the following dependency to your project:
[source,xml]
.Config Etcd Dependency in `pom.xml`
----
io.helidon.confighelidon-config-etcd
----
==== Using the Etcd Config Source
To read configuration from an Etcd source, your application uses the
link:{config-etcd-javadoc-base-url}/io/helidon/config/etcd/EtcdConfigSourceBuilder.html[`EtcdConfigSourceBuilder`].
[source,java]
.Use Etcd config source
----
include::{sourcedir}/se/config/SupportedFormatsSnippets.java[tag=snippet_10, indent=0]
----
<1> Use the factory method `EtcdConfigSource.create` to create the `EtcdConfigSource`.
<2> Specify the Etcd endpoint address.
<3> Specify the Etcd key of the configuration document.
<4> Version of the Etcd API to use; `v3` is supported. `v2` is deprecated.
The config system will use the <> automatically in this example
because the file type of the key is `.yaml`.
The `EtcdConfigSourceBuilder` class extends
link:{config-javadoc-base-url}/io/helidon/config/AbstractConfigSourceBuilder.html[`AbstractConfigSourceBuilder`]
and so supports the usual settings on config sources.
==== Monitoring for Source Changes
The Etcd support includes a change watcher strategy designed for an etcd config source.
[source,java]
.Use Etcd config source
----
include::{sourcedir}/se/config/SupportedFormatsSnippets.java[tag=snippet_11, indent=0]
----
<1> Use the etcd-specific change watcher strategy.
==== Loading Meta-configuration via Etcd
To read meta-configuration from an Etcd source set the following required properties
for the source:
* `type` to `etcd`, or `class` to `io.helidon.config.etcd.EtcdConfigSourceBuilder`
* `uri` (type `URI`) - Etcd endpoint URI.
* `key` (type `String`) - Etcd key that is associated with the configuration.
* `api` (type `EtcdConfigSourceBuilder.EtcdApi`, i.e. `v2` or `v3`) - Etcd API
version. `v2` is deprecated.
Other optional `properties` are inherited from
`AbstractConfigSourceBuilder`. (see
link:{config-javadoc-base-url}/io/helidon/config/AbstractConfigSourceBuilder.html#init-io.helidon.config.Config-[javadoc])
[source,java]
.Load Config from meta-configuration
----
include::{sourcedir}/se/config/SupportedFormatsSnippets.java[tag=snippet_12, indent=0]
----
[source,YAML]
.Meta-config `config-meta-etcd.yaml` for the etcd source
----
sources:
- type: "etcd" # <1>
properties:
uri: "http://my-etcd:2379" # <2>
key: "/config.yaml" # <2>
api: "v3" # <2>
change-watcher:
type: "etcd" # <3>
----
<1> `etcd` config source type
<2> Etcd source-specific (mandatory) `properties`: `uri`, `key` and `api`.
<3> Watcher strategy `EtcdWatcher` is automatically initialized by
specified mandatory `properties`.
=== git [[Config-ModuleGit]]
The Helidon git config module supports reading configuration from a git
repository.
==== Maven Coordinates
Add the following dependency to your project:
[source,xml]
.Config git Dependency in `pom.xml`
----
io.helidon.confighelidon-config-git
----
==== Using the git Config Source
To read configuration from a git source, your application uses the
link:{config-git-javadoc-base-url}/io/helidon/config/git/GitConfigSourceBuilder.html[`GitConfigSourceBuilder`].
[source,java]
.Use git config source
----
include::{sourcedir}/se/config/SupportedFormatsSnippets.java[tag=snippet_13, indent=0]
----
<1> Use the factory method `GitConfigSource.builder` to initialize the builder.
<2> Specify the git repository URI.
<3> Specify a directory where the git repository is already cloned, or it will be cloned.
<4> Specify the git branch.
Note that the config system will use the <> in
this example because the file type is `.conf`. Recall that for this to work the
HOCON config module must be on module-path or classpath.
The `GitConfigSourceBuilder` supports the usual source builder properties because
it extends
link:{config-javadoc-base-url}/io/helidon/config/AbstractConfigSourceBuilder.html[`AbstractConfigSourceBuilder`].
==== Monitoring for Source Changes
Your application can monitor changes to a configuration loaded from a git source
associating the `regular` built-in polling strategy with the source.
[source,java]
.Use of git config source with polling strategy
----
include::{sourcedir}/se/config/SupportedFormatsSnippets.java[tag=snippet_14, indent=0]
----
<1> Use `PollingStrategies.regular(Duration duration)` to monitor for config changes.
You can also implement your own polling strategy by implementing
link:{config-javadoc-base-url}/io/helidon/config/spi/PollingStrategy.html[`PollingStrategy`]. See
the xref:mutability-support.adoc[mutability support] and
xref:extensions.adoc#Config-SPI-PollingStrategy[polling strategy] discussions.
==== Loading Meta-configuration via git
The config system can load information about config sources from meta-configuration
rather than requiring your application to construct the builder. To read
meta-configuration from a git config source set the following properties for the source:
* `type` to `git` or `class` to `io.helidon.config.git.GitConfigSourceBuilder`
* `path` (type `String`) - Relative path to the configuration file in repository.
* `uri` (type `URI`) - URI to the git repository.
* `directory` (type `Path`) - Directory with a cloned repository, by default
a temporary directory.
* `branch` (type `String`) - git branch (default is `master`).
The meta-configuration must set the `path` and one of `uri` or `directory`.
Other optional `properties` are inherited from
`AbstractConfigSourceBuilder` (see
link:{config-javadoc-base-url}/io/helidon/config/AbstractConfigSourceBuilder.html[javadoc])
[source,java]
.Load Config from meta-configuration
----
include::{sourcedir}/se/config/SupportedFormatsSnippets.java[tag=snippet_15, indent=0]
----
[source,YAML]
.Meta-config `config-meta-git.yaml` for the git source
----
sources:
- type: "git" # <1>
properties:
path: "application.conf" # <2>
uri: "https://github.com/okosatka/test-config.git" # <2>
directory: "/config" # <2>
branch: "dev" # <2>
polling-strategy:
type: "regular" # <3>
properties:
interval: "PT5M" # <3>
----
<1> `git` config source type
<2> git source-specific properties: `path`, `uri`, `directory` and `branch`.
<3> Polling strategy `regular` with an interval, in
`Duration` format, of 5 minutes in this example.
