Skip to content

Commit 22de8f9

Browse files
committed
Improve Javadoc and examples for JRE conditions
Issue: #3930
1 parent 67beae4 commit 22de8f9

File tree

8 files changed

+65
-44
lines changed

8 files changed

+65
-44
lines changed

documentation/src/test/java/example/ConditionalTestExecutionDemo.java

Lines changed: 12 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,6 @@
1313
import static org.junit.jupiter.api.condition.JRE.JAVA_11;
1414
import static org.junit.jupiter.api.condition.JRE.JAVA_17;
1515
import static org.junit.jupiter.api.condition.JRE.JAVA_21;
16-
import static org.junit.jupiter.api.condition.JRE.JAVA_25;
1716
import static org.junit.jupiter.api.condition.JRE.JAVA_9;
1817
import static org.junit.jupiter.api.condition.OS.LINUX;
1918
import static org.junit.jupiter.api.condition.OS.MAC;
@@ -164,7 +163,9 @@ void onlyOnJava26() {
164163
}
165164

166165
@Test
167-
@EnabledOnJre(value = JAVA_25, versions = 26)
166+
@EnabledOnJre(versions = { 25, 26 })
167+
// Can also be expressed as follows.
168+
// @EnabledOnJre(value = JAVA_25, versions = 26)
168169
void onJava25And26() {
169170
// ...
170171
}
@@ -176,7 +177,9 @@ void onJava26AndHigher() {
176177
}
177178

178179
@Test
179-
@EnabledForJreRange(min = JAVA_25, maxVersion = 27)
180+
@EnabledForJreRange(minVersion = 25, maxVersion = 27)
181+
// Can also be expressed as follows.
182+
// @EnabledForJreRange(min = JAVA_25, maxVersion = 27)
180183
void fromJava25To27() {
181184
// ...
182185
}
@@ -188,7 +191,9 @@ void notOnJava26() {
188191
}
189192

190193
@Test
191-
@DisabledOnJre(value = JAVA_25, versions = 26)
194+
@DisabledOnJre(versions = { 25, 26 })
195+
// Can also be expressed as follows.
196+
// @DisabledOnJre(value = JAVA_25, versions = 26)
192197
void notOnJava25And26() {
193198
// ...
194199
}
@@ -200,7 +205,9 @@ void notOnJava26AndHigher() {
200205
}
201206

202207
@Test
203-
@DisabledForJreRange(min = JAVA_25, maxVersion = 27)
208+
@DisabledForJreRange(minVersion = 25, maxVersion = 27)
209+
// Can also be expressed as follows.
210+
// @DisabledForJreRange(min = JAVA_25, maxVersion = 27)
204211
void notFromJava25To27() {
205212
// ...
206213
}

junit-jupiter-api/src/main/java/org/junit/jupiter/api/condition/AbstractJreCondition.java

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -54,7 +54,7 @@ protected final IntStream validatedVersions(JRE[] jres, int[] versions) {
5454
this.annotationName, JRE.MINIMUM_VERSION));
5555
return version;
5656
})//
57-
);
57+
).distinct();
5858
}
5959

6060
}

junit-jupiter-api/src/main/java/org/junit/jupiter/api/condition/DisabledForJreRange.java

Lines changed: 17 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -27,8 +27,9 @@
2727
* or test method is <em>disabled</em> for a specific range of Java Runtime
2828
* Environment (JRE) versions.
2929
*
30-
* <p>Version ranges can be specified as {@link JRE} enum constants via {@link #min}
31-
* and {@link #max} or as integers via {@link #minVersion} and {@link #maxVersion}.
30+
* <p>Version ranges can be specified as {@link JRE} enum constants via
31+
* {@link #min min} and {@link #max max} or as integers via
32+
* {@link #minVersion minVersion} and {@link #maxVersion maxVersion}.
3233
*
3334
* <p>When applied at the class level, all test methods within that class will
3435
* be disabled on the same specified JRE versions.
@@ -91,11 +92,12 @@
9192
* be disabled, specified as a {@link JRE} enum constant.
9293
*
9394
* <p>If a {@code JRE} enum constant does not exist for a particular JRE
94-
* version, you can specify the minimum version via {@link #minVersion()}
95-
* instead.
95+
* version, you can specify the minimum version via
96+
* {@link #minVersion() minVersion} instead.
9697
*
9798
* <p>Defaults to {@link JRE#UNDEFINED UNDEFINED}, which will be interpreted
98-
* as {@link JRE#JAVA_8 JAVA_8} if the {@link #minVersion()} is not set.
99+
* as {@link JRE#JAVA_8 JAVA_8} if the {@link #minVersion() minVersion} is
100+
* not set.
99101
*
100102
* @see JRE
101103
* @see #minVersion()
@@ -108,11 +110,12 @@
108110
* be disabled, specified as a {@link JRE} enum constant.
109111
*
110112
* <p>If a {@code JRE} enum constant does not exist for a particular JRE
111-
* version, you can specify the maximum version via {@link #maxVersion()}
112-
* instead.
113+
* version, you can specify the maximum version via
114+
* {@link #maxVersion() maxVersion} instead.
113115
*
114116
* <p>Defaults to {@link JRE#UNDEFINED UNDEFINED}, which will be interpreted
115-
* as {@link JRE#OTHER OTHER} if the {@link #maxVersion()} is not set.
117+
* as {@link JRE#OTHER OTHER} if the {@link #maxVersion() maxVersion} is not
118+
* set.
116119
*
117120
* @see JRE
118121
* @see #maxVersion()
@@ -125,9 +128,10 @@
125128
* be disabled, specified as an integer.
126129
*
127130
* <p>If a {@code JRE} enum constant exists for the particular JRE version,
128-
* you can specify the minimum version via {@link #min()} instead.
131+
* you can specify the minimum version via {@link #min() min} instead.
129132
*
130-
* <p>Defaults to {@code -1} to signal that {@link #min()} should be used instead.
133+
* <p>Defaults to {@code -1} to signal that {@link #min() min} should be used
134+
* instead.
131135
*
132136
* @since 5.12
133137
* @see #min()
@@ -143,9 +147,10 @@
143147
* be disabled, specified as an integer.
144148
*
145149
* <p>If a {@code JRE} enum constant exists for the particular JRE version,
146-
* you can specify the maximum version via {@link #max()} instead.
150+
* you can specify the maximum version via {@link #max() max} instead.
147151
*
148-
* <p>Defaults to {@code -1} to signal that {@link #max()} should be used instead.
152+
* <p>Defaults to {@code -1} to signal that {@link #max() max} should be used
153+
* instead.
149154
*
150155
* @since 5.12
151156
* @see #max()

junit-jupiter-api/src/main/java/org/junit/jupiter/api/condition/DisabledOnJre.java

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -27,8 +27,8 @@
2727
* test method is <em>disabled</em> on one or more specified Java Runtime
2828
* Environment (JRE) versions.
2929
*
30-
* <p>Versions can be specified as {@link JRE} enum constants via {@link #value()}
31-
* or as integers via {@link #versions()}.
30+
* <p>Versions can be specified as {@link JRE} enum constants via
31+
* {@link #value() value} or as integers via {@link #versions() versions}.
3232
*
3333
* <p>When applied at the class level, all test methods within that class
3434
* will be disabled on the same specified JRE versions.
@@ -90,7 +90,8 @@
9090
* should be disabled, specified as {@link JRE} enum constants.
9191
*
9292
* <p>If a {@code JRE} enum constant does not exist for a particular JRE
93-
* version, you can specify the version via {@link #versions()} instead.
93+
* version, you can specify the version via {@link #versions() versions}
94+
* instead.
9495
*
9596
* @see JRE
9697
* @see #versions()
@@ -102,7 +103,7 @@
102103
* should be disabled, specified as integers.
103104
*
104105
* <p>If a {@code JRE} enum constant exists for a particular JRE version, you
105-
* can specify the version via {@link #value()} instead.
106+
* can specify the version via {@link #value() value} instead.
106107
*
107108
* @since 5.12
108109
* @see #value()

junit-jupiter-api/src/main/java/org/junit/jupiter/api/condition/EnabledForJreRange.java

Lines changed: 17 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -27,8 +27,9 @@
2727
* test method is only <em>enabled</em> for a specific range of Java Runtime
2828
* Environment (JRE) versions.
2929
*
30-
* <p>Version ranges can be specified as {@link JRE} enum constants via {@link #min}
31-
* and {@link #max} or as integers via {@link #minVersion} and {@link #maxVersion}.
30+
* <p>Version ranges can be specified as {@link JRE} enum constants via
31+
* {@link #min min} and {@link #max max} or as integers via
32+
* {@link #minVersion minVersion} and {@link #maxVersion maxVersion}.
3233
*
3334
* <p>When applied at the class level, all test methods within that class will
3435
* be enabled on the same specified JRE versions.
@@ -91,11 +92,12 @@
9192
* be enabled, specified as a {@link JRE} enum constant.
9293
*
9394
* <p>If a {@code JRE} enum constant does not exist for a particular JRE
94-
* version, you can specify the minimum version via {@link #minVersion()}
95-
* instead.
95+
* version, you can specify the minimum version via
96+
* {@link #minVersion() minVersion} instead.
9697
*
9798
* <p>Defaults to {@link JRE#UNDEFINED UNDEFINED}, which will be interpreted
98-
* as {@link JRE#JAVA_8 JAVA_8} if the {@link #minVersion()} is not set.
99+
* as {@link JRE#JAVA_8 JAVA_8} if the {@link #minVersion() minVersion} is
100+
* not set.
99101
*
100102
* @see JRE
101103
* @see #minVersion()
@@ -108,11 +110,12 @@
108110
* be enabled, specified as a {@link JRE} enum constant.
109111
*
110112
* <p>If a {@code JRE} enum constant does not exist for a particular JRE
111-
* version, you can specify the maximum version via {@link #maxVersion()}
112-
* instead.
113+
* version, you can specify the maximum version via
114+
* {@link #maxVersion() maxVersion} instead.
113115
*
114116
* <p>Defaults to {@link JRE#UNDEFINED UNDEFINED}, which will be interpreted
115-
* as {@link JRE#OTHER OTHER} if the {@link #maxVersion()} is not set.
117+
* as {@link JRE#OTHER OTHER} if the {@link #maxVersion() maxVersion} is not
118+
* set.
116119
*
117120
* @see JRE
118121
* @see #maxVersion()
@@ -125,9 +128,10 @@
125128
* be enabled, specified as an integer.
126129
*
127130
* <p>If a {@code JRE} enum constant exists for the particular JRE version,
128-
* you can specify the minimum version via {@link #min()} instead.
131+
* you can specify the minimum version via {@link #min() min} instead.
129132
*
130-
* <p>Defaults to {@code -1} to signal that {@link #min()} should be used instead.
133+
* <p>Defaults to {@code -1} to signal that {@link #min() min} should be used
134+
* instead.
131135
*
132136
* @since 5.12
133137
* @see #min()
@@ -143,9 +147,10 @@
143147
* be enabled, specified as an integer.
144148
*
145149
* <p>If a {@code JRE} enum constant exists for the particular JRE version,
146-
* you can specify the maximum version via {@link #max()} instead.
150+
* you can specify the maximum version via {@link #max() max} instead.
147151
*
148-
* <p>Defaults to {@code -1} to signal that {@link #max()} should be used instead.
152+
* <p>Defaults to {@code -1} to signal that {@link #max() max} should be used
153+
* instead.
149154
*
150155
* @since 5.12
151156
* @see #max()

junit-jupiter-api/src/main/java/org/junit/jupiter/api/condition/EnabledOnJre.java

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -27,8 +27,8 @@
2727
* test method is only <em>enabled</em> on one or more specified Java Runtime
2828
* Environment (JRE) versions.
2929
*
30-
* <p>Versions can be specified as {@link JRE} enum constants via {@link #value()}
31-
* or as integers via {@link #versions()}.
30+
* <p>Versions can be specified as {@link JRE} enum constants via
31+
* {@link #value() value} or as integers via {@link #versions() versions}.
3232
*
3333
* <p>When applied at the class level, all test methods within that class
3434
* will be enabled on the same specified JRE versions.
@@ -90,7 +90,8 @@
9090
* should be enabled, specified as {@link JRE} enum constants.
9191
*
9292
* <p>If a {@code JRE} enum constant does not exist for a particular JRE
93-
* version, you can specify the version via {@link #versions()} instead.
93+
* version, you can specify the version via {@link #versions() versions}
94+
* instead.
9495
*
9596
* @see JRE
9697
* @see #versions()
@@ -102,7 +103,7 @@
102103
* should be enabled, specified as integers.
103104
*
104105
* <p>If a {@code JRE} enum constant exists for a particular JRE version, you
105-
* can specify the version via {@link #value()} instead.
106+
* can specify the version via {@link #value() value} instead.
106107
*
107108
* @since 5.12
108109
* @see #value()

junit-jupiter-api/src/templates/resources/main/org/junit/jupiter/api/condition/JRE.java.jte

Lines changed: 8 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -22,10 +22,12 @@ import org.junit.platform.commons.util.StringUtils;
2222
/**
2323
* Enumeration of Java Runtime Environment (JRE) versions.
2424
*
25-
* <p>If the current JRE version cannot be detected &mdash; for example, if the
26-
* {@code java.version} JVM system property is undefined &mdash; then none of
27-
* the constants defined in this enum will be considered to be the
28-
* {@linkplain #isCurrentVersion current JRE version}.
25+
* <p>If the current JRE version can be detected but is not one of the predefined
26+
* constants in this enum, {@link #OTHER} will be considered to be the
27+
* {@linkplain #isCurrentVersion current JRE version}. If the current JRE version
28+
* cannot be detected &mdash; for example, if the {@code java.version} JVM system
29+
* property is undefined &mdash; {@link #UNDEFINED} will be considered to be the
30+
* current JRE version.
2931
*
3032
* @since 5.1
3133
@for(JRE jre : jres)<%--
@@ -76,7 +78,8 @@ public enum JRE {
7678
--%>@endfor
7779
*
7880
* <p>This constant returns {@link Integer#MAX_VALUE} for its
79-
* {@linkplain #version() version}.
81+
* {@linkplain #version() version}. To retrieve the actual version number,
82+
* use {@link #currentVersionNumber()}.
8083
*/
8184
OTHER(Integer.MAX_VALUE);
8285

jupiter-tests/src/test/java/org/junit/jupiter/api/condition/EnabledForJreRangeIntegrationTests.java

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -255,7 +255,6 @@ void minVersion20MaxVersion21() {
255255
void minVersion17MaxVersionMaxInteger() {
256256
assertTrue(onKnownVersion());
257257
assertTrue(JRE.currentVersionNumber() >= 17);
258-
assertTrue(JRE.currentVersionNumber() <= Integer.MAX_VALUE);
259258
}
260259

261260
@Test

0 commit comments

Comments
 (0)