From 9faf6b83d9e7db262be6e137814c7c69519d6260 Mon Sep 17 00:00:00 2001 From: Fortran Date: Sat, 7 Oct 2023 13:44:44 +0300 Subject: [PATCH 1/5] Update config-yaml.adoc This commit updates the Quarkus documentation to provide guidance on working with complex configuration structures in Quarkus applications. It addresses the current limitation where Quarkus can retrieve only single values using a string path and suggests strategies for flattening complex structures, such as using JSON within YAML files. Additionally, it recommends using the `quarkus.config.locations` property for including multiple configuration sources. --- docs/src/main/asciidoc/config-yaml.adoc | 55 +++++++++++++++++++++++++ 1 file changed, 55 insertions(+) diff --git a/docs/src/main/asciidoc/config-yaml.adoc b/docs/src/main/asciidoc/config-yaml.adoc index 9a84dcfb9f515..eb1d036c9aff2 100644 --- a/docs/src/main/asciidoc/config-yaml.adoc +++ b/docs/src/main/asciidoc/config-yaml.adoc @@ -211,3 +211,58 @@ quarkus: ---- YAML `null` keys are not included in the assembly of the configuration property name, allowing them to be used at any level for disambiguating configuration keys. + +== Current Limitation +The smallrye-config library can only retrieve a single value at a time using a string representation of the path, and it does not provide a built-in way to retrieve complex nested structures in configuration files. To work around this limitation, sources need to provide a single string representation of each value, effectively flattening the structure to a key-value pair of type `String -> String` . This means that nested structures in JSON or YAML files need to be represented in a flat format. + +Although Quarkus primarily uses `.properties` file extension for configuration, the snakeyaml library, which is used for parsing YAML in Quarkus, can also parse JSON structures. This means you can use YAML files with JSON content inside. + +To take advantage of this, you can use the application.yaml file (with the .yaml extension) and include JSON structures inside it. Snakeyaml will read both YAML and JSON formats within this file. This allows you to structure your configuration in a more hierarchical manner using JSON inside a YAML file. + +Certainly, here's a step-by-step guide on how to use complex configuration structures with Quarkus: + +1. Define Your Configuration Interface + +[source,java] +---- +@ConfigMapping(prefix = "server") +public interface ServiceConfig { + + List environments(); + + interface Environment { + String name(); + String services(); + } +} +---- + +2. Install the YAML Extension + +3. Configure Configuration Sources + +Add the following line to your application.properties or application.yml file: + +---- +quarkus.config.locations=path_to_yaml_file +---- + +4. Create the appropriate JSON structure and store it in a YAML file + +[source,yaml] +---- +{ + "server": { + "environments": [ + { + "name": "dev", + "services": "bookstore" + }, + { + "name": "batch", + "services": "warehouse" + } + ] + } +} +---- From 6cf187ee1da476d97be5c9d5be073be5e0ece0e6 Mon Sep 17 00:00:00 2001 From: Fortran Date: Sat, 14 Oct 2023 20:39:46 +0300 Subject: [PATCH 2/5] Fix code review comments --- docs/src/main/asciidoc/config-yaml.adoc | 17 ++--------------- 1 file changed, 2 insertions(+), 15 deletions(-) diff --git a/docs/src/main/asciidoc/config-yaml.adoc b/docs/src/main/asciidoc/config-yaml.adoc index eb1d036c9aff2..8537d6a183edc 100644 --- a/docs/src/main/asciidoc/config-yaml.adoc +++ b/docs/src/main/asciidoc/config-yaml.adoc @@ -212,12 +212,9 @@ quarkus: YAML `null` keys are not included in the assembly of the configuration property name, allowing them to be used at any level for disambiguating configuration keys. -== Current Limitation -The smallrye-config library can only retrieve a single value at a time using a string representation of the path, and it does not provide a built-in way to retrieve complex nested structures in configuration files. To work around this limitation, sources need to provide a single string representation of each value, effectively flattening the structure to a key-value pair of type `String -> String` . This means that nested structures in JSON or YAML files need to be represented in a flat format. - Although Quarkus primarily uses `.properties` file extension for configuration, the snakeyaml library, which is used for parsing YAML in Quarkus, can also parse JSON structures. This means you can use YAML files with JSON content inside. -To take advantage of this, you can use the application.yaml file (with the .yaml extension) and include JSON structures inside it. Snakeyaml will read both YAML and JSON formats within this file. This allows you to structure your configuration in a more hierarchical manner using JSON inside a YAML file. +YAML and JSON structures can be read in an application.yaml file. Certainly, here's a step-by-step guide on how to use complex configuration structures with Quarkus: @@ -237,17 +234,7 @@ public interface ServiceConfig { } ---- -2. Install the YAML Extension - -3. Configure Configuration Sources - -Add the following line to your application.properties or application.yml file: - ----- -quarkus.config.locations=path_to_yaml_file ----- - -4. Create the appropriate JSON structure and store it in a YAML file +2. Create the appropriate JSON structure and store it in a YAML file [source,yaml] ---- From e2a6a6bb9c92e0a3fe328c77ea591121cd90a9f0 Mon Sep 17 00:00:00 2001 From: Fortran Date: Wed, 15 Nov 2023 21:31:16 +0200 Subject: [PATCH 3/5] Update config-yaml.adoc --- docs/src/main/asciidoc/config-yaml.adoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/src/main/asciidoc/config-yaml.adoc b/docs/src/main/asciidoc/config-yaml.adoc index 8537d6a183edc..67918d8bb715c 100644 --- a/docs/src/main/asciidoc/config-yaml.adoc +++ b/docs/src/main/asciidoc/config-yaml.adoc @@ -218,7 +218,7 @@ YAML and JSON structures can be read in an application.yaml file. Certainly, here's a step-by-step guide on how to use complex configuration structures with Quarkus: -1. Define Your Configuration Interface +<1> Define Your Configuration Interface [source,java] ---- @@ -234,7 +234,7 @@ public interface ServiceConfig { } ---- -2. Create the appropriate JSON structure and store it in a YAML file +<2> Create the appropriate JSON structure and store it in a YAML file [source,yaml] ---- From f6d64681f2879c0120cfb72e7fed3af9223d3461 Mon Sep 17 00:00:00 2001 From: Fortran Date: Thu, 16 Nov 2023 07:14:45 +0200 Subject: [PATCH 4/5] Update config-yaml.adoc --- docs/src/main/asciidoc/config-yaml.adoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/src/main/asciidoc/config-yaml.adoc b/docs/src/main/asciidoc/config-yaml.adoc index 67918d8bb715c..bcf04d2c4f092 100644 --- a/docs/src/main/asciidoc/config-yaml.adoc +++ b/docs/src/main/asciidoc/config-yaml.adoc @@ -218,7 +218,7 @@ YAML and JSON structures can be read in an application.yaml file. Certainly, here's a step-by-step guide on how to use complex configuration structures with Quarkus: -<1> Define Your Configuration Interface +<1> Define Your Configuration Interface. [source,java] ---- @@ -234,7 +234,7 @@ public interface ServiceConfig { } ---- -<2> Create the appropriate JSON structure and store it in a YAML file +<2> Create the appropriate JSON structure and store it in a YAML file. [source,yaml] ---- From dc1b8e351155b7755e8be6a3f12ffe34ef6c715d Mon Sep 17 00:00:00 2001 From: Fortran Date: Thu, 16 Nov 2023 08:00:47 +0200 Subject: [PATCH 5/5] Update config-yaml.adoc --- docs/src/main/asciidoc/config-yaml.adoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/src/main/asciidoc/config-yaml.adoc b/docs/src/main/asciidoc/config-yaml.adoc index bcf04d2c4f092..0b73e8106fd3e 100644 --- a/docs/src/main/asciidoc/config-yaml.adoc +++ b/docs/src/main/asciidoc/config-yaml.adoc @@ -218,7 +218,7 @@ YAML and JSON structures can be read in an application.yaml file. Certainly, here's a step-by-step guide on how to use complex configuration structures with Quarkus: -<1> Define Your Configuration Interface. +* Define Your Configuration Interface. [source,java] ---- @@ -234,7 +234,7 @@ public interface ServiceConfig { } ---- -<2> Create the appropriate JSON structure and store it in a YAML file. +* Create the appropriate JSON structure and store it in a YAML file. [source,yaml] ----