JDK-8250768: javac should be adapted to changes in JEP 12 #703

lahodaj · 2020-10-16T15:20:03Z

This is an update to javac and javadoc, to introduce support for Preview APIs, and generally improve javac and javadoc behavior to more closely adhere to JEP 12.

The notable changes are:

adding support for Preview APIs (javac until now supported primarily only preview language features, and APIs associated with preview language features). This includes:
- the @PreviewFeature annotation has boolean attribute "reflective", which should be true for reflective Preview APIs, false otherwise. This replaces the existing "essentialAPI" attribute with roughly inverted meaning.
- the preview warnings for preview APIs are auto-suppressed as described in the JEP 12. E.g. the module that declares the preview API is free to use it without warnings
improving error/warning messages. Please see [1] for a list of cases/examples.
class files are only marked as preview if they are using a preview feature. [1] also shows if a class file is marked as preview or not.
the PreviewFeature annotation has been moved to jdk.internal.javac package (originally was in the jdk.internal package).
Preview API in JDK's javadoc no longer needs to specify @Preview tag in the source files. javadoc will auto-generate a note for @PreviewFeature elements, see e.g. [2] and [3] (non-reflective and reflective API, respectively). A summary of preview elements is also provided [4]. Existing uses of @Preview have been updated/removed.
non-JDK javadoc is also enhanced to auto-generate preview notes for uses of Preview elements, and for declaring elements using preview language features [5].

Please also see the CSR [6] for more information.

[1] http://cr.openjdk.java.net/~jlahoda/8250768/JEP12-errors-warnings-v6.html
[2] http://cr.openjdk.java.net/~jlahoda/8250768/jdk.javadoc.00/api/java.base/java/lang/Record.html
[3] http://cr.openjdk.java.net/~jlahoda/8250768/jdk.javadoc.00/api/java.compiler/javax/lang/model/element/RecordComponentElement.html
[4] http://cr.openjdk.java.net/~jlahoda/8250768/jdk.javadoc.00/api/preview-list.html
[5] http://cr.openjdk.java.net/~jlahoda/8250768/test.javadoc.00/
[6] https://bugs.openjdk.java.net/browse/JDK-8250769

Progress

Change must not contain extraneous whitespace
Commit message must refer to an issue
Change must be properly reviewed

Issue

JDK-8250768: javac should be adapted to changes in JEP 12

Reviewers

Maurizio Cimadamore (@mcimadamore - Reviewer) ⚠️ Review applies to be1d865
Erik Joelsson (@erikj79 - Reviewer) ⚠️ Review applies to efb37a9
Jonathan Gibbons (@jonathan-gibbons - Reviewer) ⚠️ Review applies to a8046dd
Magnus Ihse Bursie (@magicus - Reviewer) ⚠️ Review applies to 0c1c4d5

Download

$ git fetch https://git.openjdk.java.net/jdk pull/703/head:pull/703
$ git checkout pull/703

bridgekeeper · 2020-10-16T15:21:45Z

👋 Welcome back jlahoda! 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.

jonathan-gibbons · 2020-11-06T15:32:16Z

The page and comments are generally good, but there is a bug that needs to be fixed. After clicking on the PREVIEW link in the top bar to go to the Preview page, the word DEPRECATED is highlighted in the top navbar instead of PREVIEW.

…

-- Jon

On 11/5/20 10:13 AM, mlbridge[bot] wrote: /Mailing list message from Alex Buckley ***@***.***> on kulla-dev ***@***.***>:/ On 11/5/2020 4:45 AM, Jan Lahoda wrote: FWIW, a javadoc generated with the current version of the patch: http://cr.openjdk.java.net/~jlahoda/8250768/jdk.javadoc.01/api/index.html Allow me to draw people's attention to the PREVIEW link in the banner of the generated javadoc. It shows all the preview APIs in the release on one page. This is very helpful for understanding the surface area of a preview feature. For example, with Sealed Classes being the only preview feature likely to target JDK 16, the PREVIEW page shows that the feature's API is solely about reflection. It's clear that Sealed Classes do not introduce, say, a java.lang.Sealed class analogous to the java.lang.Record class introduced by Records in JDK 14/15 (and which would have appeared on the PREVIEW page had it existed then). Alex — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <https://urldefense.com/v3/__https://github.com/openjdk/jdk/pull/703*issuecomment-722549484__;Iw!!GqivPVa7Brio!ONrE9EESNKSCZJPGXBa8TTa4Ey9OqEVTynHLfgVOrBRIkb1Cr2iqLALb01M_DlGDeQEPpw$>, or unsubscribe <https://urldefense.com/v3/__https://github.com/notifications/unsubscribe-auth/AOUXBRRTA7I6T2AUM3QT7QTSOLTLXANCNFSM4STPEYJQ__;!!GqivPVa7Brio!ONrE9EESNKSCZJPGXBa8TTa4Ey9OqEVTynHLfgVOrBRIkb1Cr2iqLALb01M_DlE4QxPnyw$>.

lahodaj · 2020-11-06T18:38:10Z

Thanks for noticing Chris and @jonathan-gibbons. Fixed in 61264fe, updated javadoc:
http://cr.openjdk.java.net/~jlahoda/8250768/jdk.javadoc.02/api/preview-list.html

jonathan-gibbons

I have a mild queasiness about this new overloaded use of the word "Summary", since "summary tables" are normally the summary of the contents of a declaration, like fields and methods of a class.

That being said, the usage is primarily internal, and I have no overwhelmingly wonderful alternative, and (overloading aside) the term is accurate.

So, OK for now. We can change it later if we want to.

I like how you managed to merge both the builder and writer for the new summary classes.

jonathan-gibbons · 2020-11-11T02:18:19Z

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/Utils.java

@@ -2942,4 +2944,256 @@ public String toString() {
            return first + ":" + second;
        }
    }
+
+    /**
+     * Return the set of preview language features used to declare the given element.


magicus

Build changes still good.

openjdk · 2020-12-09T13:30:46Z

@lahodaj 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 JDK-8250768
git fetch https://git.openjdk.java.net/jdk master
git merge FETCH_HEAD
# resolve conflicts and follow the instructions given by git merge
git commit -m "Merge master"
git push

bridgekeeper · 2021-01-06T14:17:40Z

@lahodaj 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!

lahodaj · 2021-01-07T20:19:36Z

I've merged the PR with the recent mainline, and I'd like to integrate sometime soon. Please let me know if there's any issue with that. Thanks!

jonathan-gibbons

I've looked at all the files that were marked as changed since I last looked at them.

There's one suggested enhancement to reduce string bashing between Utils and ClassWriterImpl that could be done now or later.

There's a pending conflict with a PR of mine to change to use a new type HtmlId for HTML ids. This JEP12 work has been in progress for a while, and so it would be good to get it in before the HtmlId work, and I'll deal with the merge conflict in due course.

jonathan-gibbons · 2021-01-08T01:44:09Z

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/ClassWriterImpl.java

@@ -188,15 +192,34 @@ protected TypeElement getCurrentPageElement() {

    @Override @SuppressWarnings("preview")
    public void addClassSignature(String modifiers, Content classInfoTree) {


It seems less than ideal for this method to take a String and to then have to take it apart and reassemble it. It looks like it should be possible (and conceptually better) to change the signature to List<String> and to make the corresponding change to utils.modifiersToString, probably renaming it as utils.modifiersToStrings or something like that, and dropping the always-true argument for trailingSpace.

But, the code is OK as is, and the suggestion is just for an enhancement, so is OK to defer it, if you would prefer.

jonathan-gibbons · 2021-01-08T01:46:43Z

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/SummaryListWriter.java

@@ -0,0 +1,303 @@
+/*
+ * Copyright (c) 1997, 2020, Oracle and/or its affiliates. All rights reserved.


(minor) now 2021

jonathan-gibbons · 2021-01-08T01:48:41Z

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/SummaryListWriter.java

+ */
+public abstract class SummaryListWriter<L extends SummaryAPIListBuilder> extends SubWriterHolderWriter {
+
+    private String getAnchorName(SummaryElementKind kind) {


Heads-up: at some point this will conflict with another change in progress/review, to introduce a new type HtmlId to use instead of String for ids.

jonathan-gibbons · 2021-01-08T01:49:49Z

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/SummaryListWriter.java

+     * @param headerKey table header key for the summary table
+     * @param contentTree the content tree to which the summary table will be added
+     */
+    protected void addSummaryAPI(SortedSet<Element> apiList, String id,


Heads-up, here's another occurrence of where there will be a conflict for ids.

jonathan-gibbons · 2021-01-08T01:51:52Z

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/resources/doclets.properties

@@ -151,8 +151,6 @@ doclet.AnnotationInterfaces=Annotation Interfaces
 doclet.Exceptions=Exceptions
 doclet.Errors=Errors
 doclet.Classes=Classes
-doclet.packages=packages


I guess I'm mildly surprised to see all these items being removed...

These were used from DeprecatedListWriter.getSummaryKey which is removed by this patch (and is unused in the current mainline, as far as I know).

jonathan-gibbons · 2021-01-08T01:52:20Z

...k.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/SummaryAPIListBuilder.java

@@ -0,0 +1,225 @@
+/*
+ * Copyright (c) 1998, 2020, Oracle and/or its affiliates. All rights reserved.


jonathan-gibbons · 2021-01-08T01:53:34Z

test/langtools/jdk/javadoc/doclet/testPreview/TestPreview.java

@@ -0,0 +1,123 @@
+/*
+ * Copyright (c) 2003, 2020, Oracle and/or its affiliates. All rights reserved.


I assume you will do a bulk update for affected files.

jonathan-gibbons · 2021-01-08T04:11:07Z

+1

…

-- Jon

On 1/7/21 12:19 PM, Jan Lahoda wrote: I've merged the PR with the recent mainline, and I'd like to integrate sometime soon. Please let me know if there's any issue with that. Thanks! — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <https://urldefense.com/v3/__https://github.com/openjdk/jdk/pull/703*issuecomment-756360085__;Iw!!GqivPVa7Brio!Oxxf6GpefmtstD2fCT8IKF4r-blOVCGWCibSjA4m4l24mI8j6j-RDEJAiBRtFfHCMqNb7Q$>, or unsubscribe <https://urldefense.com/v3/__https://github.com/notifications/unsubscribe-auth/AOUXBRTWQAZF7NEGTD3FSGDSYYJOPANCNFSM4STPEYJQ__;!!GqivPVa7Brio!Oxxf6GpefmtstD2fCT8IKF4r-blOVCGWCibSjA4m4l24mI8j6j-RDEJAiBRtFfFTnE3pGg$>.

lahodaj · 2021-01-11T10:10:14Z

/integrate

openjdk · 2021-01-11T10:11:15Z

@lahodaj Since your change was applied there have been 22 commits pushed to the master branch:

18a37f9: 8259368: Zero: UseCompressedClassPointers does not depend on UseCompressedOops
a03e22b: 8253910: UseCompressedClassPointers depends on UseCompressedOops in vmError.cpp
e0d748d: 8258606: os::print_signal_handlers() should resolve the function name of the handlers
bd34418: 8258445: Move make/templates to make/data
d21a0ea: 8258449: Move make/hotspot/symbols to make/data
3974fd4: 8259451: Zero: skip serviceability/sa tests, set vm.hasSA to false
bb247b0: 8259392: Zero error reporting is broken after JDK-8255711
2806bf2: 8259475: Fix bad merge in compilerOracle
b72de3c: 8259385: Cleanup unused assignment
9154f64: 8254973: CompletableFuture.ThreadPerTaskExecutor does not throw NPE in #execute
... and 12 more: https://git.openjdk.java.net/jdk/compare/090bd3afc37555582bde61d03e2e32350ae5d714...master

Your commit was automatically rebased without conflicts.

Pushed as commit 2354882.

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

lahodaj added 29 commits September 3, 2020 12:35

8250768: a prototype of updates for JEP 12.

0694db0

Updates to the preview javadoc appearance.

b9dbff5

Experimenting with UI for preview links.

70286c0

Experimenting with UI for preview links.

637b8c3

Merging master into JDK-8250768

7ffc68f

More experiments on Preview stuff in javadoc.

df6db2e

More updates to the javadoc Preview UI.

d27c4dc

Merge branch 'master' into JDK-8250768

00e2b94

Merge branch 'master' into JDK-8250768

34f4355

More updateds to the preview javadoc appearance.

82f1c3a

Merging master into JDK-8250768

976755d

More updates to javadoc appearance

d88fdd4

Merging master into JDK-8250768

26a2280

A post-merge fix.

1b9a052

Cleaning up preview in javadoc.

7cb5085

Fixing tests.

79b89dd

More cleanup.

1425c23

Cleaning up whitespaces.

ca11180

Merge branch 'master' into JDK-8250768

6edf97a

Post-merge fix.

26dcc5b

Updating build.

6ba11d6

Adding forgotten files.

994cc72

Fixing tests.

ca78e89

Merging master into JDK-8250768

a99bfe3

No, jdk.incubator.vector does not need jdk.internal package.

42b5add

There is not jdk.internal package anymore

2d179d6

The Preview taglet is not needed anymore.

d23d55b

Various cleanup.

c50d5ec

Fixing tests.

efb37a9

Fixing navigator for the PREVIEW page.

61264fe

jonathan-gibbons approved these changes Nov 11, 2020

View reviewed changes

Merging recent master changes into JDK-8250768

0c1c4d5

magicus approved these changes Dec 9, 2020

View reviewed changes

openjdk bot added merge-conflict Pull request has merge conflict with target branch and removed ready Pull request is ready to be integrated labels Dec 9, 2020

lahodaj added 2 commits January 7, 2021 14:05

Merging master into JDK-8250768

4ccb150

Fixing tests after a merge.

a8046dd

openjdk bot added ready Pull request is ready to be integrated and removed merge-conflict Pull request has merge conflict with target branch labels Jan 7, 2021

jonathan-gibbons approved these changes Jan 8, 2021

View reviewed changes

openjdk bot added merge-conflict Pull request has merge conflict with target branch and removed ready Pull request is ready to be integrated labels Jan 8, 2021

lahodaj added 2 commits January 8, 2021 16:13

Updating copyright years.

56371c4

Merging master into JDK-8250768

4f65495

openjdk bot added ready Pull request is ready to be integrated and removed merge-conflict Pull request has merge conflict with target branch labels Jan 8, 2021

openjdk bot closed this Jan 11, 2021

openjdk bot added integrated Pull request has been integrated and removed ready Pull request is ready to be integrated rfr Pull request is ready for review labels Jan 11, 2021

mcimadamore mentioned this pull request Mar 24, 2022

8282191: Implementation of Foreign Function & Memory API (Preview) #7888

Closed

4 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

JDK-8250768: javac should be adapted to changes in JEP 12 #703

JDK-8250768: javac should be adapted to changes in JEP 12 #703

lahodaj commented Oct 16, 2020 •

edited by openjdk bot

Loading

bridgekeeper bot commented Oct 16, 2020

jonathan-gibbons commented Nov 6, 2020 via email

lahodaj commented Nov 6, 2020

jonathan-gibbons left a comment •

edited

Loading

jonathan-gibbons Nov 11, 2020

magicus left a comment

openjdk bot commented Dec 9, 2020

bridgekeeper bot commented Jan 6, 2021

lahodaj commented Jan 7, 2021

jonathan-gibbons left a comment

jonathan-gibbons Jan 8, 2021

jonathan-gibbons Jan 8, 2021

jonathan-gibbons Jan 8, 2021

jonathan-gibbons Jan 8, 2021

jonathan-gibbons Jan 8, 2021

lahodaj Jan 8, 2021

jonathan-gibbons Jan 8, 2021

jonathan-gibbons Jan 8, 2021

jonathan-gibbons commented Jan 8, 2021 via email

lahodaj commented Jan 11, 2021

openjdk bot commented Jan 11, 2021

		@@ -188,15 +192,34 @@ protected TypeElement getCurrentPageElement() {

		@Override @SuppressWarnings("preview")
		public void addClassSignature(String modifiers, Content classInfoTree) {

		@@ -0,0 +1,303 @@
		/*
		* Copyright (c) 1997, 2020, Oracle and/or its affiliates. All rights reserved.

		@@ -0,0 +1,225 @@
		/*
		* Copyright (c) 1998, 2020, Oracle and/or its affiliates. All rights reserved.

		@@ -0,0 +1,123 @@
		/*
		* Copyright (c) 2003, 2020, Oracle and/or its affiliates. All rights reserved.

JDK-8250768: javac should be adapted to changes in JEP 12 #703

JDK-8250768: javac should be adapted to changes in JEP 12 #703

Conversation

lahodaj commented Oct 16, 2020 • edited by openjdk bot Loading

Progress

Issue

Reviewers

Download

bridgekeeper bot commented Oct 16, 2020

jonathan-gibbons commented Nov 6, 2020 via email

lahodaj commented Nov 6, 2020

jonathan-gibbons left a comment • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

magicus left a comment

Choose a reason for hiding this comment

openjdk bot commented Dec 9, 2020

bridgekeeper bot commented Jan 6, 2021

lahodaj commented Jan 7, 2021

jonathan-gibbons left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jonathan-gibbons commented Jan 8, 2021 via email

lahodaj commented Jan 11, 2021

openjdk bot commented Jan 11, 2021

lahodaj commented Oct 16, 2020 •

edited by openjdk bot

Loading

jonathan-gibbons left a comment •

edited

Loading