Defaults to the JDK style ({@link Style#ISO8601}). */ Style style() default Style.ISO8601; /** - * The {@link Unit} to fall back to in case the {@code style()} needs a unit + * The {@link Unit} to fall back to in case the {@link #style Style} needs a unit * for either parsing or printing, and none is explicitly provided in the input. *
Defaults to {@link Unit#MILLIS} if unspecified. */ Unit defaultUnit() default Unit.MILLIS; /** - * Duration format styles. + * {@link Duration} format styles. */ enum Style { @@ -62,7 +63,7 @@ public @interface DurationFormat { *
Supported unit suffixes include: {@code ns, us, ms, s, m, h, d}. * Those correspond to nanoseconds, microseconds, milliseconds, seconds, * minutes, hours, and days, respectively. - *
Note that when printing a {@code Duration}, this style can be + *
Note that when printing a {@link Duration}, this style can be * lossy if the selected unit is bigger than the resolution of the * duration. For example, {@code Duration.ofMillis(5).plusNanos(1234)} * would get truncated to {@code "5ms"} when printing using @@ -73,7 +74,7 @@ public @interface DurationFormat { /** * ISO-8601 formatting. - *
This is what the JDK uses in {@link java.time.Duration#parse(CharSequence)} + *
This is what the JDK uses in {@link Duration#parse(CharSequence)} * and {@link Duration#toString()}. */ ISO8601, @@ -90,7 +91,7 @@ public @interface DurationFormat { } /** - * Duration format unit, which mirrors a subset of {@link ChronoUnit} and + * {@link Duration} format unit, which mirrors a subset of {@link ChronoUnit} and * allows conversion to and from a supported {@code ChronoUnit} as well as * conversion from durations to longs. * @@ -147,25 +148,24 @@ public @interface DurationFormat { } /** - * Convert this {@code DurationFormat.Unit} to its {@link ChronoUnit} - * equivalent. + * Convert this {@code Unit} to its {@link ChronoUnit} equivalent. */ public ChronoUnit asChronoUnit() { return this.chronoUnit; } /** - * Convert this {@code DurationFormat.Unit} to a simple {@code String} - * suffix, suitable for the {@link Style#SIMPLE SIMPLE} style. + * Convert this {@code Unit} to a simple {@code String} suffix, suitable + * for the {@link Style#SIMPLE SIMPLE} style. */ public String asSuffix() { return this.suffix; } /** - * Parse a {@code long} from a {@code String} and interpret it to be a - * {@code Duration} in the current unit. - * @param value the String representation of the long + * Parse a {@code long} from the given {@link String} and interpret it to be a + * {@link Duration} in the current unit. + * @param value the {@code String} representation of the long * @return the corresponding {@code Duration} */ public Duration parse(String value) { @@ -173,11 +173,11 @@ public @interface DurationFormat { } /** - * Print a {@code Duration} as a {@code String}, converting it to a long + * Print the given {@link Duration} as a {@link String}, converting it to a long * value using this unit's precision via {@link #longValue(Duration)} * and appending this unit's simple {@link #asSuffix() suffix}. - * @param value the {@code Duration} to convert to a String - * @return the String representation of the {@code Duration} in the + * @param value the {@code Duration} to convert to a {@code String} + * @return the {@code String} representation of the {@code Duration} in the * {@link Style#SIMPLE SIMPLE} style */ public String print(Duration value) { @@ -185,11 +185,12 @@ public @interface DurationFormat { } /** - * Convert the given {@code Duration} to a long value in the resolution - * of this unit. Note that this can be lossy if the current unit is - * bigger than the actual resolution of the duration. - *
For example, {@code Duration.ofMillis(5).plusNanos(1234)} would - * get truncated to {@code 5} for unit {@code MILLIS}. + * Convert the given {@link Duration} to a long value in the resolution + * of this unit. + *
Note that this can be lossy if the current unit is bigger than the + * actual resolution of the duration. For example, + * {@code Duration.ofMillis(5).plusNanos(1234)} would get truncated to + * {@code 5} for unit {@code MILLIS}. * @param value the {@code Duration} to convert to a long * @return the long value for the {@code Duration} in this {@code Unit} */ @@ -198,7 +199,7 @@ public @interface DurationFormat { } /** - * Get the {@code Unit} corresponding to the given {@code ChronoUnit}. + * Get the {@link Unit} corresponding to the given {@link ChronoUnit}. * @throws IllegalArgumentException if the given {@code ChronoUnit} is * not supported */ @@ -215,7 +216,7 @@ public @interface DurationFormat { } /** - * Get the {@code Unit} corresponding to the given {@code String} suffix. + * Get the {@link Unit} corresponding to the given {@link String} suffix. * @throws IllegalArgumentException if the given suffix is not supported */ public static Unit fromSuffix(String suffix) { diff --git a/spring-context/src/test/java/org/springframework/format/datetime/standard/DurationFormatterUtilsTests.java b/spring-context/src/test/java/org/springframework/format/datetime/standard/DurationFormatterUtilsTests.java index 6a4a17931e..a446d347dd 100644 --- a/spring-context/src/test/java/org/springframework/format/datetime/standard/DurationFormatterUtilsTests.java +++ b/spring-context/src/test/java/org/springframework/format/datetime/standard/DurationFormatterUtilsTests.java @@ -42,7 +42,7 @@ import static org.springframework.format.annotation.DurationFormat.Style.SIMPLE; class DurationFormatterUtilsTests { @ParameterizedTest - @EnumSource(DurationFormat.Style.class) + @EnumSource void parseEmptyStringFailsWithDedicatedException(DurationFormat.Style style) { assertThatIllegalArgumentException() .isThrownBy(() -> DurationFormatterUtils.parse("", style)) @@ -50,7 +50,7 @@ class DurationFormatterUtilsTests { } @ParameterizedTest - @EnumSource(DurationFormat.Style.class) + @EnumSource void parseNullStringFailsWithDedicatedException(DurationFormat.Style style) { assertThatIllegalArgumentException() .isThrownBy(() -> DurationFormatterUtils.parse(null, style)) @@ -113,29 +113,30 @@ class DurationFormatterUtilsTests { @Test void parseIsoNoChronoUnit() { - //these are based on the examples given in Duration.parse -// "PT20.345S" -- parses as "20.345 seconds" + // These are based on the examples given in Duration.parse. + + // "PT20.345S" -- parses as "20.345 seconds" assertThat(DurationFormatterUtils.parse("PT20.345S", ISO8601)) .hasMillis(20345); -// "PT15M" -- parses as "15 minutes" (where a minute is 60 seconds) + // "PT15M" -- parses as "15 minutes" (where a minute is 60 seconds) assertThat(DurationFormatterUtils.parse("PT15M", ISO8601)) .hasSeconds(15*60); -// "PT10H" -- parses as "10 hours" (where an hour is 3600 seconds) + // "PT10H" -- parses as "10 hours" (where an hour is 3600 seconds) assertThat(DurationFormatterUtils.parse("PT10H", ISO8601)) .hasHours(10); -// "P2D" -- parses as "2 days" (where a day is 24 hours or 86400 seconds) + // "P2D" -- parses as "2 days" (where a day is 24 hours or 86400 seconds) assertThat(DurationFormatterUtils.parse("P2D", ISO8601)) .hasDays(2); -// "P2DT3H4M" -- parses as "2 days, 3 hours and 4 minutes" + // "P2DT3H4M" -- parses as "2 days, 3 hours and 4 minutes" assertThat(DurationFormatterUtils.parse("P2DT3H4M", ISO8601)) .isEqualTo(Duration.ofDays(2).plusHours(3).plusMinutes(4)); -// "PT-6H3M" -- parses as "-6 hours and +3 minutes" + // "PT-6H3M" -- parses as "-6 hours and +3 minutes" assertThat(DurationFormatterUtils.parse("PT-6H3M", ISO8601)) .isEqualTo(Duration.ofHours(-6).plusMinutes(3)); -// "-PT6H3M" -- parses as "-6 hours and -3 minutes" + // "-PT6H3M" -- parses as "-6 hours and -3 minutes" assertThat(DurationFormatterUtils.parse("-PT6H3M", ISO8601)) .isEqualTo(Duration.ofHours(-6).plusMinutes(-3)); -// "-PT-6H+3M" -- parses as "+6 hours and -3 minutes" + // "-PT-6H+3M" -- parses as "+6 hours and -3 minutes" assertThat(DurationFormatterUtils.parse("-PT-6H+3M", ISO8601)) .isEqualTo(Duration.ofHours(6).plusMinutes(-3)); } @@ -189,7 +190,7 @@ class DurationFormatterUtilsTests { .isEqualTo(Duration.ofMinutes(34).plusSeconds(57)); } - @Test //Kotlin style compatibility + @Test // Kotlin style compatibility void parseCompositeNegativeWithSpacesAndParenthesis() { assertThat(DurationFormatterUtils.parse("-(34m 57s)", COMPOSITE)) .isEqualTo(Duration.ofMinutes(-34).plusSeconds(-57)); @@ -315,7 +316,7 @@ class DurationFormatterUtilsTests { assertThat(DurationFormatterUtils.detect("-(1d 2h 34m 2ns)")) .as("COMPOSITE") - .isEqualTo(COMPOSITE); + .isEqualTo(COMPOSITE); assertThatIllegalArgumentException().isThrownBy(() -> DurationFormatterUtils.detect("WPT2H-4M")) .withMessage("'WPT2H-4M' is not a valid duration, cannot detect any known style")