root
/
spring-framework
mirror of https://github.com/spring-projects/spring-framework.git
1
0
Fork 0
Code Issues Actions 8 Packages Projects Releases Wiki Activity

Polish @⁠DurationFormat Javadoc and tests

This commit is contained in:
Sam Brannen 2024-11-18 13:57:10 +01:00
parent 883254e1d0
commit d421f61a4a
2 changed files with 39 additions and 37 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

49
spring-context/src/main/java/org/springframework/format/annotation/DurationFormat.java
View File

@ -29,7 +29,8 @@ import org.springframework.lang.Nullable;
/**
* Declares that a field or method parameter should be formatted as a
* {@link java.time.Duration}, according to the specified {@link #style style}.
* {@link java.time.Duration}, according to the specified {@link #style Style}
* and {@link #defaultUnit Unit}.
*
* @author Simon Baslé
* @since 6.2
@ -40,20 +41,20 @@ import org.springframework.lang.Nullable;
public @interface DurationFormat {
/**
* The {@code Style} to use for parsing and printing a {@code Duration}.
* The {@link Style} to use for parsing and printing a {@link Duration}.
* <p>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.
* <p>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 {
* <p>Supported unit suffixes include: {@code ns, us, ms, s, m, h, d}.
* Those correspond to nanoseconds, microseconds, milliseconds, seconds,
* minutes, hours, and days, respectively.
* <p>Note that when printing a {@code Duration}, this style can be
* <p>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.
* <p>This is what the JDK uses in {@link java.time.Duration#parse(CharSequence)}
* <p>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.
* <p>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.
* <p>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) {

27
spring-context/src/test/java/org/springframework/format/datetime/standard/DurationFormatterUtilsTests.java
View File

@ -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")