Rewrite the JavaDoc logic in Java 11 APIs and use multi-release jar to ensure backward compatibility #929
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
JoeJoe1989
changed the title
JoeJoe1989
force-pushed
the
yanzhou/use_multi_release_jar
branch
from
03a3494
to
7a44056
Compare
junchuanwang
had a problem deploying
to
jfrog-publish
GitHub Actions
Failure
JoeJoe1989
force-pushed
the
yanzhou/use_multi_release_jar
branch
from
a9e6c7e
to
c3cc6e4
Compare
added 4 commits
August 25, 2023 18:17
…to be backward compatible with Java 8 upstreams
JoeJoe1989
force-pushed
the
yanzhou/use_multi_release_jar
branch
from
c3cc6e4
to
033487c
Compare
junchuanwang
temporarily deployed
to
jfrog-publish
GitHub Actions
Inactive
JoeJoe1989
force-pushed
the
yanzhou/use_multi_release_jar
branch
from
d8f542f
to
1b70e14
Compare
junchuanwang
temporarily deployed
to
jfrog-publish
GitHub Actions
Inactive
…tModelCodegenClasspath
JoeJoe1989
force-pushed
the
yanzhou/use_multi_release_jar
branch
from
bb668b5
to
18655b4
Compare
...lugins/src/integTest/groovy/com/linkedin/pegasus/gradle/PegasusPluginCacheabilityTest.groovy
Show resolved
Hide resolved
restli-tools/src/main/java11/com/linkedin/restli/tools/idlgen/DocletDocsProvider.java
Outdated
Show resolved
Hide resolved
restli-tools/src/main/java11/com/linkedin/restli/tools/idlgen/DocletDocsProvider.java
Show resolved
Hide resolved
junchuanwang
approved these changes
Sep 19, 2023
added 3 commits
September 19, 2023 14:51
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Background
Currently, RestLi uses Java 8 APIs, such as com.sun.javadoc, to generate JavaDoc. However, these APIs have been removed in Java 17, making RestLi incompatible with Java 17. This PR aims to resolve the issue by rewriting the JavaDoc related logic using Java 11 APIs, which are compatibility with JDK 17.
Furthermore, since RestLi has a mix of Java 8 and Java 11 consumers and we are using Java 11 APIs, we will utilize a multi-release JAR to ensure backward compatibility with Java 8 consumers. On a high level, a multi-release JAR compiles the code using Java 11 and sets the target version to either Java 11 or Java 8, depending on whether Java 11 APIs are used or not. As a result, the JAR contains different versions of bytecode and is compatible with different versions of consumers.
Changes
Tests Done
Build in Java 11:
I tested the build process of 16 consumers who are using Java 8, Java 11, and Java 17 against the local snapshot of RestLi.
I also ran a wc-test of container against RestLi and noticed some IDL changes caused by the difference between Java 8 and Java 11 APIs in terms of handling comments in unexpected formats in source files. For example, there is an extra comma after the parameter name
count:* @param count, the number of the recommendationsJava 8 APIs are not able to handle this case, so no JavaDoc is generated for
count. However, Java 11 APIs can handle it and generate JavaDoc as follows:"doc" : ", the number of the recommendations""Consumers who encounter such IDL changes during build can commit the changes as normal. Ideally, they should fix the comments in unexpected formats in source files.