jdk 8331051: Add an `@since` checker test for `java.base` module

This checker checks the values of the @since tag found in the documentation comment for an element against the release in which the element first appeared.

Real since value of an API element is computed as the oldest release in which the given API element was introduced. That is:

for modules, classes and interfaces, the release in which the element with the given qualified name was introduced
for constructors, the release in which the constructor with the given VM descriptor was introduced
for methods and fields, the release in which the given method or field with the given VM descriptor became a member of its enclosing class or interface, whether direct or inherited

Effective since value of an API element is computed as follows:

if the given element has a @since tag in its javadoc, it is used
in all other cases, return the effective since value of the enclosing element

The since checker verifies that for every API element, the real since value and the effective since value are the same, and reports an error if they are not.

Preview method are handled as per JEP 12, if @PreviewFeature is used consistently going forward then the checker doesn't need to be updated with every release. The checker has explicit knowledge of preview elements that came before JDK 14 because they weren't marked in a machine understandable way and preview elements that came before JDK 17 that didn't have @PreviewFeature.

Important note : We only check code written since JDK 9 as the releases used to determine the expected value of @since tags are taken from the historical data built into javac which only goes back that far

The intial comment at the beginning of SinceChecker.java holds more information into the program.

I already have filed issues and fixed some wrong tags like in #18640, #18032, #18030, #18055, #18373, #18954, #18972.

Progress

[ ] Change must be properly reviewed (1 review required, with at least 1 Reviewer)
[x] Change must not contain extraneous whitespace
[x] Commit message must refer to an issue

Issue

JDK-8331051: Add an @since checker test for java.base module (Sub-task - P4)

Reviewing

Using git

Checkout this PR locally:
$ git fetch https://git.openjdk.org/jdk.git pull/18934/head:pull/18934
$ git checkout pull/18934

Update a local copy of the PR:
$ git checkout pull/18934
$ git pull https://git.openjdk.org/jdk.git pull/18934/head

Using Skara CLI tools

Checkout this PR locally:
$ git pr checkout 18934

View PR using the GUI difftool:
$ git pr show -t 18934

Using diff file

Download this PR as a diff file:
https://git.openjdk.org/jdk/pull/18934.diff

Webrev

Link to Webrev Comment

Apr 24 '24 14:04 nizarbenalla

:wave: Welcome back nizarbenalla! A progress list of the required criteria for merging this PR into master will be added to the body of your pull request. There are additional pull request commands available for use with this pull request.

Apr 24 '24 14:04 bridgekeeper[bot]

@nizarbenalla This change now passes all automated pre-integration checks.

ℹ️ This project also has non-automated pre-integration requirements. Please see the file CONTRIBUTING.md for details.

After integration, the commit message for the final commit will be:

8331051: Add an `@since` checker test for `java.base` module

Reviewed-by: jlahoda, jjg

You can use pull request commands such as /summary, /contributor and /issue to adjust it as needed.

At the time when this comment was updated there had been 189 new commits pushed to the master branch:

b9cabbecdac27ae8b93df88660a4a0f3f60e6828: 8341997: Tests create files in src tree instead of scratch dir
5eae20f73b9e8578d58c7e49d2da79cf1b0b229c: 8323672: Suppress unwanted autoconf added flags in CC and CXX
6ed6dff22208e7e6c24c98d3a9ff895a6c6c0ae0: 8341871: Disable G1 for unsupported platforms after JDK-8334060
54c9348c8c0f5b363d1ef31166179fe9ac61ab9c: 8336103: Clean up confusing Method::is_initializer
2c0c65353b2f67bdcd954b4d2c2ae3e9b24d1c22: 8342044: Increase timeout of gc/shenandoah/oom/TestClassLoaderLeak.java
df7d6e081ff9513fbd6cff5d033a307e6798418b: 8338603: DiagnosticCommandMBean operations should standardize types for parameters
c9a536c330d37632139a1d71b0c054352eae5aa0: 8337339: gc/arguments/Test*SizeFlags.java timing out with Xcomp
f4dccfd4cf354f360b823c8cce15bb54ef90e9ca: 8338596: Clarify handling of restricted and caller-sensitive methods
3b8a2f8c45ffd0bdb48db805cf70b4652525d891: 8337269: G1ConfidencePercent interpreted inconsistently
521effe017b9b6322036f1851220056a637d6b1c: 8340189: 8339531 incorrect for Big Endian platforms
... and 179 more: https://git.openjdk.org/jdk/compare/d6820d1324711eac95a297dd68ec94e6f6be4b35...master

As there are no conflicts, your changes will automatically be rebased on top of these commits when integrating. If you prefer to avoid this automatic rebasing, please check the documentation for the /integrate command for further details.

➡️ To integrate this PR with the above commit message to the master branch, type /integrate in a new comment.

Apr 24 '24 14:04 openjdk[bot]

@nizarbenalla The following label will be automatically applied to this pull request:

core-libs

When this pull request is ready to be reviewed, an "RFR" email will be sent to the corresponding mailing list. If you would like to change these labels, use the /label pull request command.

Apr 24 '24 14:04 openjdk[bot]

Webrevs

Apr 29 '24 09:04 mlbridge[bot]

If not already planned, I recommend a much broader discussion/announcement of this test before it goes back. For example, a message to jdk-dev stating "The value of @since tags will be tested now by a tier $N test. This is how you run the test before a push. Here are rules for some tricky cases like introducing a covariant override." etc.

Apr 29 '24 16:04 jddarcy

/reviewers 2

May 24 '24 13:05 lahodaj

@lahodaj The total number of required reviews for this PR (including the jcheck configuration and the last /reviewers command) is now set to 2 (with at least 1 Reviewer, 1 Author).

May 24 '24 13:05 openjdk[bot]

The checker's report has been improved, the result after running it on java.base is the following

        SinceChecker java.base
STDERR:
src/java.base/java/io/PrintStream.java:685 method: void java.io.PrintStream.write(byte[]): `@since` version is 14 but the element exists before JDK 10
src/java.base/java/io/FileInputStream.java:374 method: byte[] java.io.FileInputStream.readNBytes(int): `@since` version: 9; found: 11
src/java.base/java/lang/classfile/ClassSignature.java:45 method: java.lang.classfile.Signature.ClassTypeSig java.lang.classfile.ClassSignature.superclassSignature(): `@since` version: 22; found: 23
src/java.base/java/lang/classfile/ClassReader.java:131 method: java.lang.classfile.constantpool.PoolEntry java.lang.classfile.ClassReader.readEntryOrNull(int,java.lang.Class): `@since` version: 24; found: 23
src/java.base/java/lang/classfile/constantpool/ConstantPool.java:74 method: java.lang.classfile.constantpool.PoolEntry java.lang.classfile.constantpool.ConstantPool.entryByIndex(int,java.lang.Class): `@since` version: 24; found: 23
src/java.base/java/lang/constant/ClassDesc.java:378 method: java.lang.Class java.lang.constant.ClassDesc.resolveConstantDesc(java.lang.invoke.MethodHandles.Lookup): `@since` version: 12; found: 21
src/java.base/java/lang/constant/MethodTypeDesc.java:226 method: java.lang.invoke.MethodType java.lang.constant.MethodTypeDesc.resolveConstantDesc(java.lang.invoke.MethodHandles.Lookup): `@since` version: 12; found: 21
src/java.base/java/lang/constant/MethodHandleDesc.java:210 method: java.lang.invoke.MethodHandle java.lang.constant.MethodHandleDesc.resolveConstantDesc(java.lang.invoke.MethodHandles.Lookup): `@since` version: 12; found: 21
src/java.base/java/lang/foreign/MemorySegment.java:622 method: long java.lang.foreign.MemorySegment.maxByteAlignment(): `@since` version: 22; found: 23
src/java.base/java/lang/invoke/MethodHandles.java:7923 method: java.lang.invoke.MethodHandle java.lang.invoke.MethodHandles.tableSwitch(java.lang.invoke.MethodHandle,java.lang.invoke.MethodHandle[]): `@since` version: 9; found: 17
src/java.base/java/lang/ref/Reference.java:527 method: java.lang.Object java.lang.ref.Reference.clone(): `@since` version is 11 but the element exists before JDK 10
src/java.base/java/lang/reflect/MalformedParameterizedTypeException.java:54 method: void java.lang.reflect.MalformedParameterizedTypeException.<init>(java.lang.String): `@since` version: 9; found: 10
src/java.base/java/nio/MappedByteBuffer.java:401 method: java.nio.MappedByteBuffer java.nio.MappedByteBuffer.slice(): `@since` version: 9; found: 17
src/java.base/java/nio/MappedByteBuffer.java:414 method: java.nio.MappedByteBuffer java.nio.MappedByteBuffer.slice(int,int): `@since` version: 9; found: 17
src/java.base/java/nio/MappedByteBuffer.java:420 method: java.nio.MappedByteBuffer java.nio.MappedByteBuffer.duplicate(): `@since` version: 9; found: 17
src/java.base/java/nio/MappedByteBuffer.java:427 method: java.nio.MappedByteBuffer java.nio.MappedByteBuffer.compact(): `@since` version: 9; found: 17
src/java.base/java/text/ChoiceFormat.java:589 method: boolean java.text.ChoiceFormat.isStrict(): `@since` version: 9; found: 23
src/java.base/java/text/ChoiceFormat.java:595 method: void java.text.ChoiceFormat.setStrict(boolean): `@since` version: 9; found: 23
src/java.base/java/util/Properties.java:189 method: void java.util.Properties.<init>(int): `@since` version: 9; found: 10
src/java.base/java/util/concurrent/FutureTask.java:208 method: java.lang.Object java.util.concurrent.FutureTask.resultNow(): `@since` version: 9; found: 19
src/java.base/java/util/concurrent/FutureTask.java:224 method: java.lang.Throwable java.util.concurrent.FutureTask.exceptionNow(): `@since` version: 9; found: 19
src/java.base/java/util/concurrent/FutureTask.java:239 method: java.util.concurrent.Future.State java.util.concurrent.FutureTask.state(): `@since` version: 9; found: 19
src/java.base/java/util/concurrent/ThreadLocalRandom.java:504 method: float java.util.concurrent.ThreadLocalRandom.nextFloat(float): `@since` version: 9; found: 17
src/java.base/java/util/concurrent/ThreadLocalRandom.java:514 method: float java.util.concurrent.ThreadLocalRandom.nextFloat(float,float): `@since` version: 9; found: 17
src/java.base/java/util/concurrent/ForkJoinTask.java:890 method: java.util.concurrent.Future.State java.util.concurrent.ForkJoinTask.state(): `@since` version: 9; found: 19
src/java.base/java/util/concurrent/ForkJoinTask.java:899 method: java.lang.Object java.util.concurrent.ForkJoinTask.resultNow(): `@since` version: 9; found: 19
src/java.base/java/util/concurrent/ForkJoinTask.java:913 method: java.lang.Throwable java.util.concurrent.ForkJoinTask.exceptionNow(): `@since` version: 9; found: 19
src/java.base/java/util/concurrent/DelayQueue.java:331 method: java.util.concurrent.Delayed java.util.concurrent.DelayQueue.remove(): `@since` version: 9; found: 21
src/java.base/java/util/concurrent/CompletableFuture.java:2137 method: java.lang.Object java.util.concurrent.CompletableFuture.resultNow(): `@since` version: 9; found: 19
src/java.base/java/util/concurrent/CompletableFuture.java:2152 method: java.lang.Throwable java.util.concurrent.CompletableFuture.exceptionNow(): `@since` version: 9; found: 19
src/java.base/java/util/concurrent/CompletableFuture.java:2399 method: java.util.concurrent.CompletableFuture java.util.concurrent.CompletableFuture.exceptionallyAsync(java.util.function.Function): `@since` version: 9; found: 12
src/java.base/java/util/concurrent/CompletableFuture.java:2404 method: java.util.concurrent.CompletableFuture java.util.concurrent.CompletableFuture.exceptionallyAsync(java.util.function.Function,java.util.concurrent.Executor): `@since` version: 9; found: 12
src/java.base/java/util/concurrent/CompletableFuture.java:2409 method: java.util.concurrent.CompletableFuture java.util.concurrent.CompletableFuture.exceptionallyCompose(java.util.function.Function): `@since` version: 9; found: 12
src/java.base/java/util/concurrent/CompletableFuture.java:2414 method: java.util.concurrent.CompletableFuture java.util.concurrent.CompletableFuture.exceptionallyComposeAsync(java.util.function.Function): `@since` version: 9; found: 12
src/java.base/java/util/concurrent/CompletableFuture.java:2419 method: java.util.concurrent.CompletableFuture java.util.concurrent.CompletableFuture.exceptionallyComposeAsync(java.util.function.Function,java.util.concurrent.Executor): `@since` version: 9; found: 12
src/java.base/java/util/concurrent/CompletableFuture.java:2544 method: java.util.concurrent.Future.State java.util.concurrent.CompletableFuture.state(): `@since` version: 9; found: 19
src/java.base/java/util/zip/Deflater.java:340 method: void java.util.zip.Deflater.setDictionary(java.nio.ByteBuffer): `@since` version: 9; found: 11
java.lang.Exception: The `@since` checker found 37 problems
        at SinceChecker.checkModule(SinceChecker.java:262)
        at SinceChecker.main(SinceChecker.java:123)
        at java.base/jdk.internal.reflect.DirectMethodHandleAccessor.invoke(DirectMethodHandleAccessor.java:103)
        at java.base/java.lang.reflect.Method.invoke(Method.java:580)
        at com.sun.javatest.regtest.agent.MainActionHelper$AgentVMRunnable.run(MainActionHelper.java:333)
        at java.base/java.lang.Thread.run(Thread.java:1575)

JavaTest Message: Test threw exception: java.lang.Exception
JavaTest Message: shutting down test


TEST RESULT: Failed. Execution failed: `main' threw exception: java.lang.Exception: The `@since` checker found 37 problems
--------------------------------------------------
Test results: failed: 1

Jun 04 '24 20:06 nizarbenalla

While this might seem like a lot, if a developer runs it before pushing, they should only encounter a few reports at most.

Jun 04 '24 20:06 nizarbenalla

@nizarbenalla this pull request can not be integrated into master due to one or more merge conflicts. To resolve these merge conflicts and update this pull request you can run the following commands in the local repository for your personal fork:

git checkout source-based-since-checker
git fetch https://git.openjdk.org/jdk.git master
git merge FETCH_HEAD
# resolve conflicts and follow the instructions given by git merge
git commit -m "Merge master"
git push

Jun 24 '24 05:06 openjdk[bot]

I have a couple of small changes after the first approval, mainly improving the error messages. And avoiding false reports in case a file doesn't exist in src.zip

Jun 28 '24 13:06 nizarbenalla

@nizarbenalla This pull request has been inactive for more than 4 weeks and will be automatically closed if another 4 weeks passes without any activity. To avoid this, simply add a new comment to the pull request. Feel free to ask for assistance if you need help with progressing this pull request towards integration!

Jul 26 '24 16:07 bridgekeeper[bot]

Keep alive, this will need a re-review eventually because of the new rules.

Aug 22 '24 11:08 nizarbenalla

Currently running tier1, I added the option to exclude certain packages in an attempt to integrate this faster while we fix other areas.

Sep 10 '24 16:09 nizarbenalla

I performed a merge and a tiny change to the error message by the test. The major changes since the last review are that I now skip packages if they are not found, and I added an exclude list to skip certain packages if we wish to do so.

Here is an example of the error output of the tool

STDERR:
src/java.base/java/lang/classfile/TypeKind.java:73 field: java.lang.classfile.TypeKind:BOOLEAN: `@since` version: 22; should be: 24
src/java.base/java/lang/classfile/TypeKind.java:80 field: java.lang.classfile.TypeKind:BYTE: `@since` version: 22; should be: 24
src/java.base/java/lang/classfile/TypeKind.java:87 field: java.lang.classfile.TypeKind:CHAR: `@since` version: 22; should be: 24
src/java.base/java/lang/classfile/TypeKind.java:94 field: java.lang.classfile.TypeKind:SHORT: `@since` version: 22; should be: 24
src/java.base/java/lang/classfile/TypeKind.java:99 field: java.lang.classfile.TypeKind:INT: `@since` version: 22; should be: 24
src/java.base/java/lang/classfile/TypeKind.java:103 field: java.lang.classfile.TypeKind:LONG: `@since` version: 22; should be: 24
src/java.base/java/lang/classfile/TypeKind.java:107 field: java.lang.classfile.TypeKind:FLOAT: `@since` version: 22; should be: 24
src/java.base/java/lang/classfile/TypeKind.java:111 field: java.lang.classfile.TypeKind:DOUBLE: `@since` version: 22; should be: 24
src/java.base/java/lang/classfile/TypeKind.java:117 field: java.lang.classfile.TypeKind:REFERENCE: `@since` version: 22; should be: 24
src/java.base/java/lang/classfile/TypeKind.java:125 field: java.lang.classfile.TypeKind:VOID: `@since` version: 22; should be: 24
src/java.base/java/lang/classfile/TypeKind.java:143 method: java.lang.constant.ClassDesc java.lang.classfile.TypeKind.upperBound(): `@since` version: 22; should be: 24
java.lang.Exception: The `@since` checker found 64 problems
        at SinceChecker.checkModule(SinceChecker.java:265)
        at SinceChecker.main(SinceChecker.java:126)
        at java.base/jdk.internal.reflect.DirectMethodHandleAccessor.invoke(DirectMethodHandleAccessor.java:103)
        at java.base/java.lang.reflect.Method.invoke(Method.java:573)
        at com.sun.javatest.regtest.agent.MainActionHelper$AgentVMRunnable.run(MainActionHelper.java:333)
        at java.base/java.lang.Thread.run(Thread.java:1576)

Sep 19 '24 16:09 nizarbenalla

For discussion:

I see that in GitHub Actions, the test passes on all platforms. (That's good!). But it's not clear to me that it needs to run on all platforms. Generally, the API should be the same on all platforms, right (After all, we only generate one set of API documentation.)

So, the question becomes, can a test determine if it is being run in a multi-platform context? We presumably don't want to stop the test running whenever a user runs it locally on their platform of choice, but equally, if the test is being run on many platforms, that's an unnecessary use/waste of resources. But, I guess we run a lot of tests that are essentially platform-independent on all platforms, although I guess there're are also testing the product running on top of the JVM, whereas here. we're primarily just checking the source.

Anyway, this is really just an abstract academic discussion, not a blocker in any way for the PR.

Sep 19 '24 22:09 jonathan-gibbons

Can we maybe set the reviewer count to 1? This needs an additional review and the last change was small.

Oct 15 '24 16:10 nizarbenalla

/reviewers 1

Oct 15 '24 20:10 lahodaj

@lahodaj The total number of required reviews for this PR (including the jcheck configuration and the last /reviewers command) is now set to 1 (with at least 1 Reviewer).

Oct 15 '24 20:10 openjdk[bot]

Thank you for the reviews; all. And the help to getting this work integrated.

/integrate

Oct 16 '24 10:10 nizarbenalla

Going to push as commit c81aa7551c37cc025c9054db08472b8abb2cbcb5. Since your change was applied there have been 198 commits pushed to the master branch:

ebc17c7c8d6febd5a887309d1b7a466bcd2cc0a9: 8339637: (tz) Update Timezone Data to 2024b
e7cf25ce0efdf568fc8eaff249d49e46d5a6eda1: 8340801: Disable ubsan checks in some awt/2d coding
577babf1968700e4b648305cd5a5c2ddf712e2dc: 8334010: VM crashes with ObjectAlignmentInBytes > GCCardSizeInBytes
b9b0bd0871886eb65f87864f262424b119f2c748: 8337221: CompileFramework: test library to conveniently compile java and jasm sources for fuzzing
724de682091623cd9877ee4e5f13123ef1d92ddf: 8342081: Shenandoah: Remove extra ShenandoahMarkUpdateRefsSuperClosure
e4ff553c121e29c497336fdde705e70d0abdc826: 8341931: os_linux gtest uses lambdas with explicit capture lists
e94e3bba3932f3d92c0a135d333d1ccd6e72b964: 8324672: Update jdk/java/time/tck/java/time/TCKInstant.java now() to be more robust
6d7e67956b1722b4e3d33253d68c095058f39f02: 8340790: Open source several AWT Dialog tests - Batch 4
86ce19e8db6950fc529b8c510137e91e97cae0c4: 8341142: Maintain a single source file for sun.net.www.protocol.jar.JarFileFactory
b9cabbecdac27ae8b93df88660a4a0f3f60e6828: 8341997: Tests create files in src tree instead of scratch dir
... and 188 more: https://git.openjdk.org/jdk/compare/d6820d1324711eac95a297dd68ec94e6f6be4b35...master

Your commit was automatically rebased without conflicts.

Oct 16 '24 10:10 openjdk[bot]

@nizarbenalla Pushed as commit c81aa7551c37cc025c9054db08472b8abb2cbcb5.

:bulb: You may see a message that your pull request was closed with unmerged commits. This can be safely ignored.

Oct 16 '24 10:10 openjdk[bot]

jdk jdk copied to clipboard

8331051: Add an `@since` checker test for `java.base` module

Progress

Issue

Reviewing

Webrev

Webrevs

jdk
jdk copied to clipboard