Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Improve description of the duration format in configuration documentation #35844

Merged
merged 1 commit into from
Sep 12, 2023
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
@@ -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";

Original file line number Diff line number Diff line change
@@ -28,25 +28,43 @@ 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:
* <ul>
* <li>If the value is only a number, it is treated as a number of seconds.</li>
* <li>If the value is a number followed by {@code ms}, it is treated as a number of milliseconds.</li>
* <li>If the value is a number followed by {@code h}, {@code m}, or {@code s}, it is prefixed with {@code PT}
* and {@link Duration#parse(CharSequence)} is called.</li>
* <li>If the value is a number followed by {@code d}, it is prefixed with {@code P}
* and {@link Duration#parse(CharSequence)} is called.</li>
* </ul>
*
* @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) {
return parseDuration(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:
* <ul>
* <li>If the value is only a number, it is treated as a number of seconds.</li>
* <li>If the value is a number followed by {@code ms}, it is treated as a number of milliseconds.</li>
* <li>If the value is a number followed by {@code h}, {@code m}, or {@code s}, it is prefixed with {@code PT}
* and {@link Duration#parse(CharSequence)} is called.</li>
* <li>If the value is a number followed by {@code d}, it is prefixed with {@code P}
* and {@link Duration#parse(CharSequence)} is called.</li>
* </ul>
*
* 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();
17 changes: 11 additions & 6 deletions docs/src/main/asciidoc/_includes/duration-format-note.adoc
Original file line number Diff line number Diff line change
@@ -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`.
====
Original file line number Diff line number Diff line change
@@ -188,10 +188,6 @@ public class GrpcClientConfiguration {

/**
* The deadline used for each call.
* <p>
* 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<Duration> deadline;