feat(jpms): add `module-info.java` descriptors #556

sgammon · 2024-03-13T01:27:57Z

Summary

This PR offers a minimal changeset to safely ship a module-info.java descriptor for the org.reactivestreams API artifact. The JAR is shipped as an MRJAR, with a module-info.class descriptor located in META-INF/versions/9.

This keeps the JAR compatible with JDK 6, while supporting full modularity for newer versions of Java.

Based on the current structure of the codebase, I tried to keep this PR as minimal as possible. Unfortunately, Gradle 6 does not yet have the release flag for the Java compiler, so I've upgraded Gradle to 7.x. The latest version is 7.6.4. Other than this and the module-info.java itself, I've added a task to validate the multi-release JAR as a module.

The tests pass and everything seems fine from local, of course, but this should probably be tested with downstream artifacts. I can put together a small integration test harness which uses these JPMS-enabled artifacts with popular Reactive Streams projects to make sure there is a clear picture of impacts.

Fixes and closes #531

Build tooling

The Gradle upgrade clears the way for some other changes, which are more optional/unrelated; for example, using Gradle Toolchains to enforce JDK 6 compatibility. I'm not sure if the Reactive Stream authors/maintainers want these changes, so I have split them off into another PR, which is a superset of this one: #557

Both PRs enable JPMS support, and only one or the other should be merged (if any). That PR has its own explanation about the changes enclosed.

JAR Structure

After applying this PR, the JAR structure for the api artifact is:

Care has been taken not to duplicate classes in the Java 9 class root, and to preserve the FlowAdapters.

JAR manifest:

OSGi manifest (Java 9+):

Changelog

feat(jpms): add module-info.java to api
chore: adjust builds where needed to release as MRJAR artifacts
chore: adjust BND tools to not interfere with MRJAR classes
chore: upgrade gradle → 7.6.4
chore: apply updates to groovy dsl for publishing with gradle v7

- feat(jpms): add `module-info.java` to `api` - chore: adjust builds where needed to release as MRJAR artifacts - chore: adjust BND tools to not interfere with MRJAR classes - chore: upgrade gradle → `7.6.4` - chore: apply updates to groovy dsl for publishing with gradle v7 Signed-off-by: Sam Gammon <[email protected]>

sgammon · 2024-03-13T01:28:27Z

api/build.gradle

+    if (isJdk9OrGreater) java9 {
+        java {
+            srcDirs = ['src/main/java', 'src/main/java9']
+        }
+    }


This is now a second source set, instead of an additional directory in the main source set. This allows a second compile task to target a different JVM bytecode level.

sgammon · 2024-03-13T01:29:13Z

api/build.gradle

+configurations {
+  mrjarArtifact
 }


The MRJAR artifact is exported from the project, so that tests can depend on it. This is important to accurately test JPMS, otherwise Gradle will put these classes on the classpath downstream, which runs tests without modular encapsulation.

sgammon · 2024-03-13T01:29:29Z

api/build.gradle

+    if (isJdk9OrGreater) into('META-INF/versions/9') {
+        from(sourceSets.java9.output) {
+            include '**/FlowAdapters*'
+            include '**/module-info.class'
+        }
+    }


Amends the JAR with the META-INF/versions/9 root, from the output of the sourceSets.java9 compile. include is used here to avoid duplicating classes which reside in the root of the module, at JDK 6, which are identical anyway.

sgammon · 2024-03-13T01:30:43Z

api/build.gradle

-            'Export-Package': 'org.reactivestreams.*',
-            'Automatic-Module-Name': 'org.reactivestreams',
-            'Bundle-SymbolicName': 'org.reactivestreams.reactive-streams'
+            'Export-Package': 'org.reactivestreams.*,!META-INF.*',
+            'Multi-Release': true,
+            'Bundle-SymbolicName': 'org.reactivestreams.reactive-streams',
+            '-fixupmessages': '^Classes found in the wrong directory: .*'


Export-Package has added !META-INF.* to avoid processing the Java 9 class root; Multi-Release was added, to replace Automatic-Module-Name. -fixupmessages avoids a BND warning about classes in the Java 9 root.

sgammon · 2024-03-13T01:31:24Z

api/build.gradle

+if (isJdk9OrGreater) {
+    compileJava9Java {
+        group = "build"
+        description = "Compile Java 9 classes for MR JAR"
+
+        sourceCompatibility = 9
+        targetCompatibility = 9
+    }


Compile task; in this PR, the task is conditional based on whether the build-time JVM is at least Java 9. The existing build behavior is preserved in this way.

In the other PR, this is addressed by Gradle Toolchains, so the build task is not conditional and is always expected to run at JDK 9 or greater during build time.

sgammon · 2024-03-13T01:33:18Z

api/src/main/java9/module-info.java

+module org.reactivestreams {
+  exports org.reactivestreams;


The module name matches the previous Automatic-Module-Name. The exported package is the only package in the JAR, so export-related risk is minimal. If it needs to be an open module let me know.

sgammon · 2024-03-13T01:33:52Z

build.gradle

+def sonatypeRepo = 'https://oss.sonatype.org/service/local/staging/deploy/maven2/'
+def sonatypeSnapshots = 'https://oss.sonatype.org/content/repositories/snapshots/'
+
+def distributionRepository = properties["distributionRepository"] ?: sonatypeRepo
+def snapshotsRepository = properties["snapshotsRepository"] ?: sonatypeSnapshots


I included a small unrelated change which allows parameterization of the deploy repositories. This will allow me to easily test integration of this JPMS support with downstream libraries. It should be completely inert to this codebase.

The username and password for releases are still required, but only when the deployment repo is Sonatype.

sgammon · 2024-03-13T01:34:21Z

build.gradle

-        apply plugin: "maven"
        apply plugin: "signing"
+        apply plugin: "publishing"
        apply plugin: "maven-publish"


Small build cleanup because Gradle 7.x eliminates the maven plugin in favor of publishing. Other than DSL updates, the logic is unchanged.

sgammon · 2024-03-13T01:34:54Z

tck-flow/build.gradle

+compileJava {
+    options.release = 9
+}
+
+compileTestJava {
+    options.release = 9
+}


Always tests at --release=9, because Flow isn't available until then.

sgammon · 2024-03-13T01:35:31Z

tck/build.gradle

@@ -1,7 +1,7 @@
 description = 'reactive-streams-tck'
 dependencies {
    api group: 'org.testng', name: 'testng', version:'7.3.0'
-    api project(':reactive-streams')
+    api project(path: ':reactive-streams', configuration: 'mrjarArtifact')


Wires together that the TCK depends on the MRJAR, rather than the unwrapped classes.

sgammon · 2024-03-13T01:53:43Z

cc / @viktorklang, @ktoso This is ready for review. Let me know if you guys are open to this 😁

- chore: add `org.reactivestreams` submodule - chore: pin to reactive-streams/reactive-streams-jvm#556 - chore: sync repository - chore: add to version catalog Relates-To: #1 Signed-off-by: Sam Gammon <[email protected]>

sgammon commented Mar 13, 2024

View reviewed changes

sgammon mentioned this pull request Mar 13, 2024

feat(jpms): add module-info.java descriptors (w/build upgrades) #557

Open

sgammon mentioned this pull request Mar 13, 2024

Tracking: JPMS Ecosystem elide-dev/jpms#1

Open

sgammon mentioned this pull request Mar 13, 2024

feat: add org.reactivestreams elide-dev/jpms#9

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(jpms): add `module-info.java` descriptors #556

feat(jpms): add `module-info.java` descriptors #556

sgammon commented Mar 13, 2024 •

edited

Loading

sgammon Mar 13, 2024

sgammon Mar 13, 2024

sgammon Mar 13, 2024

sgammon Mar 13, 2024

sgammon Mar 13, 2024 •

edited

Loading

sgammon Mar 13, 2024

sgammon Mar 13, 2024 •

edited

Loading

sgammon Mar 13, 2024

sgammon Mar 13, 2024

sgammon Mar 13, 2024

sgammon commented Mar 13, 2024

feat(jpms): add module-info.java descriptors #556

Are you sure you want to change the base?

feat(jpms): add module-info.java descriptors #556

Conversation

sgammon commented Mar 13, 2024 • edited Loading

Summary

Build tooling

JAR Structure

Changelog

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

sgammon Mar 13, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

sgammon Mar 13, 2024 • edited Loading

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

sgammon commented Mar 13, 2024

feat(jpms): add `module-info.java` descriptors #556

feat(jpms): add `module-info.java` descriptors #556

sgammon commented Mar 13, 2024 •

edited

Loading

sgammon Mar 13, 2024 •

edited

Loading

sgammon Mar 13, 2024 •

edited

Loading