Rewrite the JavaDoc logic in Java 11 APIs and use multi-release jar t…

…o ensure backward compatibility (#929)

.github/workflows/build.yml

@@ -11,7 +11,7 @@ jobs:
       fail-fast: false
       matrix:
         os: [ubuntu-latest]
-        java: [8] # TODO: Add 11 once build issues are resolved
+        java: [8, 11] # TODO: Add 11 once build issues are resolved
     name: Java ${{ matrix.java }} on ${{ matrix.os }}
     steps:
       - uses: actions/checkout@v2
@@ -23,5 +23,4 @@ jobs:
           distribution: zulu
           java-version: ${{ matrix.java }}
           cache: gradle
-      - run: ./.github/scripts/build.sh
-
+      - run: ./.github/scripts/build.sh

.github/workflows/publish.yml

@@ -13,7 +13,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        java: [8]
+        java: 11
     name: Java ${{ matrix.java }}
     steps:
       - uses: actions/checkout@v2

CHANGELOG.md

@@ -14,6 +14,9 @@ and what APIs have changed, if applicable.
 
 ## [Unreleased]
 
+## [29.46.0] - 2023-09-05
+- Rewrite the Java Doc logic in Java 11 APIs and use multi-release jar to be backward compatible with Java 8 consumers
+
 ## [29.45.1] - 2023-09-05
 - add @Nullable annotations to pegasus java getters and setters with mode
 
@@ -5527,7 +5530,8 @@ patch operations can re-use these classes for generating patch messages.
 
 ## [0.14.1]
 
-[Unreleased]: https://github.com/linkedin/rest.li/compare/v29.45.1...master
+[Unreleased]: https://github.com/linkedin/rest.li/compare/v29.46.0...master
+[29.46.0]: https://github.com/linkedin/rest.li/compare/v29.45.1...v29.46.0
 [29.45.1]: https://github.com/linkedin/rest.li/compare/v29.45.0...v29.45.1
 [29.45.0]: https://github.com/linkedin/rest.li/compare/v30.0.0...v29.45.0
 [30.0.0]: https://github.com/linkedin/rest.li/compare/v29.44.0...v30.0.0

build.gradle

@@ -153,7 +153,16 @@ allprojects {
       throw new GradleScriptException("Pegasus required Java 8 or later to build, current version: ${JavaVersion.current()}", null)
     }
     // for all supported versions that we test build, fail the build if any compilation warnings are reported
-    compile.options.compilerArgs = ['-Xlint', '-Xlint:-path', '-Xlint:-static', '-Werror']
+    compile.options.compilerArgs = ['-Xlint', '-Xlint:-path', '-Xlint:-static']
+    // Set the default Java bytecode level to version 8 to ensure backward compatibility
+    if (JavaVersion.current() >= JavaVersion.VERSION_11) {
+      sourceCompatibility = 8
+      targetCompatibility = 8
+      // Ideally we should uncomment the line below to set the release option to Java 8 to restrict the use of new APIs after Java 8.
+      // However, com.sun.javadoc APIs were moved from tools.jar in Java 8 to JDK internals in Java 11.
+      // Therefore, if we set the release option to Java 8, we will not be able to use the APIs in JDK internals when compiling in Java 11.
+      // compile.options.compilerArgs.addAll(['--release', '8'])
+    }
   }
 
   tasks.withType(Javadoc)

build_script/restModel.gradle

@@ -79,7 +79,8 @@ project.sourceSets.all { SourceSet sourceSet ->
     project.tasks[sourceSet.compileJavaTaskName].dependsOn(rootProject.ext.build.restModelGenerateTasks[sourceSet])
   }
 
-  final Task jarTask = project.tasks[sourceSet.getTaskName('', 'jar')]
+  // Use 'jar' instead of a custom task name for Java 11 source set in the multi-release jar
+  final Task jarTask = project.tasks[sourceSet.getName().endsWith('11') ? 'jar' : sourceSet.getTaskName('', 'jar')]
   jarTask.from(inputParentDirPath) {
     include "${pegasusDirName}${File.separatorChar}**${File.separatorChar}*.pdsc"
     include "${pegasusDirName}${File.separatorChar}**${File.separatorChar}*.pdl"

gradle-plugins/src/integTest/groovy/com/linkedin/pegasus/gradle/PegasusPluginCacheabilityTest.groovy

@@ -96,6 +96,6 @@ class PegasusPluginCacheabilityTest extends Specification {
     preparedSchema.exists()
 
     where:
-    gradleVersion << [ '4.0', '5.2.1', '5.6.4', '6.9', '7.0.2' ]
+    gradleVersion << [ '5.2.1', '5.6.4', '6.9', '7.0.2' ]
   }
 }

gradle-plugins/src/integTest/groovy/com/linkedin/pegasus/gradle/PegasusPluginIntegrationTest.groovy

@@ -34,7 +34,7 @@ class PegasusPluginIntegrationTest extends Specification {
     result.task(':mainDataTemplateJar').outcome == SUCCESS
 
     where:
-    gradleVersion << [ '4.0', '5.2.1', '5.6.4', '6.9', '7.0.2', '7.5.1' ]
+    gradleVersion << [ '5.2.1', '5.6.4', '6.9', '7.0.2', '7.5.1' ]
   }
 
   @Unroll
@@ -102,7 +102,7 @@ class PegasusPluginIntegrationTest extends Specification {
     assertZipContains(dataTemplateArtifact, 'extensions/com/linkedin/LatLongExtensions.pdl')
 
     where:
-    gradleVersion << [ '4.0', '5.2.1', '5.6.4', '6.9', '7.0.2', '7.5.1' ]
+    gradleVersion << [ '5.2.1', '5.6.4', '6.9', '7.0.2', '7.5.1' ]
   }
 
   def 'mainCopySchema task will remove stale PDSC'() {
@@ -262,7 +262,7 @@ class PegasusPluginIntegrationTest extends Specification {
     result.task(':impl:compileJava').outcome == SUCCESS
 
     where:
-    gradleVersion << [ '4.0', '5.2.1', '5.6.4', '6.9', '7.0.2', '7.5.1' ]
+    gradleVersion << [ '5.2.1', '5.6.4', '6.9', '7.0.2', '7.5.1' ]
   }
 
   private static boolean assertZipContains(File zip, String path) {

gradle-plugins/src/main/java/com/linkedin/pegasus/gradle/tasks/GenerateRestClientTask.java

@@ -206,7 +206,9 @@ public void generate()
       }).assertNormalExitValue()
     );
 
-    // Fluent API generator will not generate classes for schemas referenced from IDLs (eg, FooArray for list params).
+    // We are commenting out the following block because FluentApiGenerator is not actively being used and it is causing
+    // "FileNotFoundException: JAR entry a not found in restli-tools-30.0.1.jar" when using multi-release jar.
+/*    // Fluent API generator will not generate classes for schemas referenced from IDLs (eg, FooArray for list params).
     // These are already generated by the request builder generators and will be reused.
     if (!fluentApiFiles.isEmpty())
     {
@@ -229,7 +231,7 @@ public void generate()
           javaExecSpec.args("--targetDir", _destinationDir.getAbsolutePath());
           javaExecSpec.args(sources);
         }).assertNormalExitValue();
-      }
+      }*/
   }
 
 

gradle.properties

@@ -1,4 +1,4 @@
-version=29.45.1
+version=29.46.0
 group=com.linkedin.pegasus
 org.gradle.configureondemand=true
 org.gradle.parallel=true

restli-common/src/main/java/com/linkedin/restli/internal/common/URIDecoderUtils.java

@@ -67,6 +67,7 @@
 package com.linkedin.restli.internal.common;
 
 import java.nio.ByteBuffer;
+import java.nio.Buffer;
 import java.nio.CharBuffer;
 import java.nio.charset.Charset;
 import java.util.Arrays;
@@ -198,7 +199,9 @@ private static ByteBuffer decodeConsecutiveOctets(String s, int start)
       byte b = decodeOctet(s, i + 1);
       bb.put(b);
     }
-    bb.flip();
+    // Fix java.lang.NoSuchMethodError: java.nio.ByteBuffer.flip()Ljava/nio/ByteBuffer based on the suggestions from
+    // https://stackoverflow.com/questions/61267495/exception-in-thread-main-java-lang-nosuchmethoderror-java-nio-bytebuffer-flip
+    ((Buffer)bb).flip();
     return bb;
   }