From 39759043b973caecf500a8c29053d64932812e56 Mon Sep 17 00:00:00 2001 From: Ladislav Thon Date: Mon, 11 Sep 2023 12:05:17 +0200 Subject: [PATCH] Improve description of the duration format in configuration documentation --- .../annotation/processor/Constants.java | 17 ++++++--- .../configuration/DurationConverter.java | 38 ++++++++++++++----- .../_includes/duration-format-note.adoc | 17 ++++++--- .../config/GrpcClientConfiguration.java | 4 -- 4 files changed, 51 insertions(+), 25 deletions(-) diff --git a/core/processor/src/main/java/io/quarkus/annotation/processor/Constants.java b/core/processor/src/main/java/io/quarkus/annotation/processor/Constants.java index d6251ece2eb60..f4c4b4a530eec 100644 --- a/core/processor/src/main/java/io/quarkus/annotation/processor/Constants.java +++ b/core/processor/src/main/java/io/quarkus/annotation/processor/Constants.java @@ -106,13 +106,20 @@ final public class Constants { "\n[id='" + DURATION_NOTE_ANCHOR + "']\n" + ".About the Duration format\n" + "====\n" + - "The format for durations uses the standard `java.time.Duration` format.\n" + - "You can learn more about it in the link:https://docs.oracle.com/javase/8/docs/api/java/time/Duration.html#parse-java.lang.CharSequence-[Duration#parse() javadoc].\n" + "To write duration values, use the standard `java.time.Duration` format.\n" + + "See the link:https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/time/Duration.html#parse(java.lang.CharSequence)[Duration#parse() javadoc] for more information.\n" + "\n" + - "You can also provide duration values starting with a number.\n" + - "In this case, if the value consists only of a number, the converter treats the value as seconds.\n" + - "Otherwise, `PT` is implicitly prepended to the value to obtain a standard `java.time.Duration` format.\n" + + "You can also use a simplified format, starting with a number:\n" + + "\n" + + "* If the value is only a number, it represents time in seconds.\n" + + "* If the value is a number followed by `ms`, it represents time in milliseconds.\n" + + "\n" + + "In other cases, the simplified format is translated to the `java.time.Duration` format for parsing:\n" + + "\n" + + "* If the value is a number followed by `h`, `m`, or `s`, it is prefixed with `PT`.\n" + + "* If the value is a number followed by `d`, it is prefixed with `P`" + + ".\n" + "====\n" + "endif::no-duration-note[]\n"; diff --git a/core/runtime/src/main/java/io/quarkus/runtime/configuration/DurationConverter.java b/core/runtime/src/main/java/io/quarkus/runtime/configuration/DurationConverter.java index 83f8fa17ffaf5..925f26fa23051 100644 --- a/core/runtime/src/main/java/io/quarkus/runtime/configuration/DurationConverter.java +++ b/core/runtime/src/main/java/io/quarkus/runtime/configuration/DurationConverter.java @@ -28,12 +28,21 @@ public DurationConverter() { } /** - * The converter accepts a value which start with a number by implicitly appending `PT` to it or `P` for days. - * If the value consists only of a number, it implicitly treats the value as seconds. - * Otherwise, tries to convert the value assuming that it is in the accepted ISO-8601 duration format. + * If the {@code value} starts with a number, then: + * * - * @param value duration as String - * @return {@link Duration} + * Otherwise, {@link Duration#parse(CharSequence)} is called. + * + * @param value a string duration + * @return the parsed {@link Duration} + * @throws IllegalArgumentException in case of parse failure */ @Override public Duration convert(String value) { @@ -41,12 +50,21 @@ public Duration convert(String value) { } /** - * Converts a value which start with a number by implicitly appending `PT` to it or `P` for days. - * If the value consists only of a number, it implicitly treats the value as seconds. - * Otherwise, tries to convert the value assuming that it is in the accepted ISO-8601 duration format. + * If the {@code value} starts with a number, then: + * + * + * Otherwise, {@link Duration#parse(CharSequence)} is called. * - * @param value duration as String - * @return {@link Duration} + * @param value a string duration + * @return the parsed {@link Duration} + * @throws IllegalArgumentException in case of parse failure */ public static Duration parseDuration(String value) { value = value.trim(); diff --git a/docs/src/main/asciidoc/_includes/duration-format-note.adoc b/docs/src/main/asciidoc/_includes/duration-format-note.adoc index 5f0fc05d24ad4..8738c77891b8b 100644 --- a/docs/src/main/asciidoc/_includes/duration-format-note.adoc +++ b/docs/src/main/asciidoc/_includes/duration-format-note.adoc @@ -1,10 +1,15 @@ [NOTE] ==== -The format for durations uses the standard `java.time.Duration` format. -You can learn more about it in the link:https://docs.oracle.com/javase/8/docs/api/java/time/Duration.html#parse-java.lang.CharSequence-[Duration#parse() javadoc]. +To write duration values, use the standard `java.time.Duration` format. +See the link:https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/time/Duration.html#parse(java.lang.CharSequence)[Duration#parse() javadoc] for more information. -You can also provide duration values starting with a number. -In this case, if the value consists only of a number, the converter treats the value as seconds. -Otherwise, `PT` for seconds, minute and hours or `P` for days are implicitly prepended to the value to obtain a standard `java.time.Duration` format. -Milliseconds are also supported by implicitly using `Duration.ofMillis()` +You can also use a simplified format, starting with a number: + +* If the value is only a number, it represents time in seconds. +* If the value is a number followed by `ms`, it represents time in milliseconds. + +In other cases, the simplified format is translated to the `java.time.Duration` format for parsing: + +* If the value is a number followed by `h`, `m`, or `s`, it is prefixed with `PT`. +* If the value is a number followed by `d`, it is prefixed with `P`. ==== diff --git a/extensions/grpc/runtime/src/main/java/io/quarkus/grpc/runtime/config/GrpcClientConfiguration.java b/extensions/grpc/runtime/src/main/java/io/quarkus/grpc/runtime/config/GrpcClientConfiguration.java index bd1ccca8623e9..92b282f128a37 100644 --- a/extensions/grpc/runtime/src/main/java/io/quarkus/grpc/runtime/config/GrpcClientConfiguration.java +++ b/extensions/grpc/runtime/src/main/java/io/quarkus/grpc/runtime/config/GrpcClientConfiguration.java @@ -188,10 +188,6 @@ public class GrpcClientConfiguration { /** * The deadline used for each call. - *

- * The format uses the standard {@link java.time.Duration} format. You can also provide duration values starting with a - * number. In this case, if the value consists only of a number, the converter treats the value as seconds. Otherwise, - * {@code PT} is implicitly prepended to the value to obtain a standard {@link java.time.Duration} format. */ @ConfigItem public Optional deadline;