You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@datasketches.apache.org by dc...@apache.org on 2021/06/17 02:48:25 UTC

[datasketches-memory] branch support-newer-java-versions updated: Add support for Multi-Release JAR assembly

This is an automated email from the ASF dual-hosted git repository.

dcromberge pushed a commit to branch support-newer-java-versions
in repository https://gitbox.apache.org/repos/asf/datasketches-memory.git


The following commit(s) were added to refs/heads/support-newer-java-versions by this push:
     new 352dddd  Add support for Multi-Release JAR assembly
352dddd is described below

commit 352dddd6ac4daa196dd3e4aea7d8388be92c04ae
Author: David Cromberge <dc...@apache.org>
AuthorDate: Thu Jun 17 03:47:03 2021 +0100

    Add support for Multi-Release JAR assembly
    
    Extend the assembled JAR to allow multiple, Java-release-specific
    versions of class files to coexist in a single archive.
    
    See JEP-238.
---
 README.md                                          |   7 +++++
 datasketches-memory/pom.xml                        |   4 +--
 .../{assemble-jar.xml => assemble-mr-jar.xml}      |  18 +++++++++++
 docs/img/mr-jar-manifest.png                       | Bin 0 -> 86092 bytes
 docs/img/mr-jar-sources.png                        | Bin 0 -> 51055 bytes
 docs/multi-release-jar.md                          |  33 +++++++++++++++++++++
 6 files changed, 60 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index 0eb082b..d70e3c9 100644
--- a/README.md
+++ b/README.md
@@ -69,6 +69,13 @@ This will create the following Jars:
 * datasketches-memory-X.Y.Z-test-sources.jar The test source files
 * datasketches-memory-X.Y.Z-javadoc.jar  The compressed Javadocs.
 
+### Further documentation for contributors
+
+For more information on the project configuration, the following topics are discussed in more detail:
+
+* [Maven configuration](docs/maven.md)
+* [Multi-release jar](docs/multi-release-jar.md)
+
 ### Dependencies
 
 #### Run-time
diff --git a/datasketches-memory/pom.xml b/datasketches-memory/pom.xml
index dc1f98c..fdbd422 100644
--- a/datasketches-memory/pom.xml
+++ b/datasketches-memory/pom.xml
@@ -110,7 +110,7 @@
         </configuration>
         <executions>
 
-          <!-- primary jar -->
+          <!-- multi-release (MR) jar -->
           <execution>
             <id>assemble-jar</id>
             <phase>package</phase>
@@ -121,7 +121,7 @@
               <appendAssemblyId>false</appendAssemblyId>
               <attach>true</attach>
               <descriptors>
-                <descriptor>src/assembly/assemble-jar.xml</descriptor>
+                <descriptor>src/assembly/assemble-mr-jar.xml</descriptor>
               </descriptors>
             </configuration>
           </execution>
diff --git a/datasketches-memory/src/assembly/assemble-jar.xml b/datasketches-memory/src/assembly/assemble-mr-jar.xml
similarity index 80%
rename from datasketches-memory/src/assembly/assemble-jar.xml
rename to datasketches-memory/src/assembly/assemble-mr-jar.xml
index 0772f6a..6acae7d 100644
--- a/datasketches-memory/src/assembly/assemble-jar.xml
+++ b/datasketches-memory/src/assembly/assemble-mr-jar.xml
@@ -28,6 +28,7 @@
 
   <!-- Compiled java classes from dependency modules -->
   <moduleSets>
+    <!-- java8 -->
     <moduleSet>
       <useAllReactorProjects>true</useAllReactorProjects>
       <includes>
@@ -43,6 +44,23 @@
         </fileSets>
       </sources>
     </moduleSet>
+    <!-- java9 -->
+    <moduleSet>
+      <useAllReactorProjects>true</useAllReactorProjects>
+      <includes>
+        <include>org.apache.datasketches:datasketches-memory-java9</include>
+      </includes>
+      <binaries>
+        <outputDirectory>META-INF/versions/9</outputDirectory>
+        <unpack>true</unpack>
+        <includeDependencies>false</includeDependencies>
+        <unpackOptions>
+          <excludes>
+            <exclude>/META-INF/**</exclude>
+          </excludes>
+        </unpackOptions>
+      </binaries>
+    </moduleSet>
   </moduleSets>
 
   <fileSets>
diff --git a/docs/img/mr-jar-manifest.png b/docs/img/mr-jar-manifest.png
new file mode 100644
index 0000000..02e4745
Binary files /dev/null and b/docs/img/mr-jar-manifest.png differ
diff --git a/docs/img/mr-jar-sources.png b/docs/img/mr-jar-sources.png
new file mode 100644
index 0000000..78cf4f7
Binary files /dev/null and b/docs/img/mr-jar-sources.png differ
diff --git a/docs/multi-release-jar.md b/docs/multi-release-jar.md
new file mode 100644
index 0000000..1afebc7
--- /dev/null
+++ b/docs/multi-release-jar.md
@@ -0,0 +1,33 @@
+Multi-release JAR
+=================
+
+The `datasketches-memory` module assembles a JAR for release that consists of multiple Java-release-specific versions
+of class files to coexist in a single archive (the MR-JAR).
+
+From [JEP-238](https://openjdk.java.net/jeps/238):
+
+> Third party libraries and frameworks typically support a range of Java platform versions, generally going several 
+  versions back. As a consequence they often do not take advantage of language or API features available in newer 
+  releases since it is difficult to express conditional platform dependencies, which generally involves reflection, or
+  to distribute different library artifacts for different platform versions.
+
+And, specifically for libraries like `datasketches-memory`:
+
+> Some libraries and frameworks, furthermore, use internal APIs of the JDK that will be made inaccessible in Java 9
+  when module boundaries are strictly enforced. This also creates a disincentive to support new platform versions when
+  there are public, supported API replacements for such internal APIs.
+
+MR-JAR Assembly
+---------------
+
+The maven assembly plugin uses the following maven submodules to source the compiled class files for the MR-JAR:
+
+![MR-JAR maven module mapping](img/mr-jar-sources.png "MR-JAR maven module mapping")
+
+MR-JAR Manifest
+---------------
+
+The maven-assembly plugin Assembly plugin copies version specific class files into JAR manifest META-INF directory, as
+shown in the diagram below:
+
+![MR-JAR manifest file contents](img/mr-jar-manifest.png "MR-JAR manifest file contents")

---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@datasketches.apache.org
For additional commands, e-mail: commits-help@datasketches.apache.org