Skip to content
Permalink
Browse files
Update references to Java9 in docs
  • Loading branch information
davecromberge committed May 4, 2022
1 parent 00c001b commit 427d435d7b70d2429fa512170ef58ef7f1c56d19
Showing 7 changed files with 38 additions and 51 deletions.
@@ -53,9 +53,9 @@ Also see the [usage examples](docs/usage-examples.md) for more information.
In this environment, the user is using the Jars from Maven Central as a library dependency and not attempting to build the Memory component from the source code or run the Memory component tests.

* If you are running Java 8, no extra JVM arguments are required.
* If you are running Java 9-13 and only using the **Heap** related API, no extra JVM arguments are required.
* If you are running Java 11-13 and only using the **Heap** related API, no extra JVM arguments are required.

Otherwise, if you are running Java 9-13 and ...
Otherwise, if you are running Java 11-13 and ...

* If your application **is not a JPMS module** use the following table. Choose the columns that describe your use of the Memory API. If any of the columns contain a *Yes*, then the JVM argument in the first column of the row containing a *Yes* will be required. If you are not sure the extent of the Memory API being used, there is no harm in specifying all 4 JVM arguments. Note: do not embed any spaces in the full argument.

@@ -89,7 +89,7 @@ In this environment the developer needs to build the Memory component from sourc
* IntelliJ (version)
* Maven (version)
* Command-line or scripts
* The developer must have installed in their development system at least JDK versions 8, 9 and 11.
* The developer must have installed in their development system at least JDK versions 8 and 11.
* Unless building with the provided script, the developer must have a valid [Maven toolchain configuration](docs/maven-toolchains.md).


@@ -118,7 +118,6 @@ There are no run-time dependencies. See the pom.xml file for test dependencies.
The Maven build requires the following JDKs to compile:

- JDK8/Hotspot
- JDK9/Hotspot
- JDK11/Hotspot

Before building, first ensure that your local environment has been configured according to the [Maven Toolchains Configuration](docs/maven-toolchains.md).
@@ -138,9 +137,9 @@ To run javadoc on this multi-module project, use:

mvn clean process-classes javadoc:javadoc -DskipTests=true

To run the CI tests against the multi-release JAR for specific JVM versions [9-13], use:
To run the CI tests against the multi-release JAR for specific JVM versions [11-13], use:

mvn clean package -Denvironment=ci -Dmatrix.jdk.version=9
mvn clean package -Denvironment=ci -Dmatrix.jdk.version=11

To run the eclipse plugin on this multi-module project, use:

@@ -38,13 +38,12 @@ for a Maven module should be set as follows:
| datasketches-memory | 8 |
| datasketches-memory-java8 | 8 |
| datasketches-memory-java8-tests | 8 |
| datasketches-memory-java9 | 9 |
| datasketches-memory-java11 | 11 |
| datasketches-memory-resources | 8 |

### Compiler arguments for JPMS

In order to compile Maven modules in Java versions 9 and above, it is necessary to provide the
In order to compile Maven modules in Java versions 11 and above, it is necessary to provide the
following arguments to the compiler. These are usually synchronised with the `pom.xml`
configuration:

@@ -93,9 +92,9 @@ From the **Package Explorer** View:
Although these should be set automatically, the Eclipse IDE does not currently configure these
settings according to the `pom.xml` - see this
[Eclipse Bug](https://github.com/eclipse-m2e/m2e-core/issues/129).
Ensure that the required JPMS arguments are set for the compiler (Java 9 only).
Ensure that the required JPMS arguments are set for the compiler (Java 11 only).

- First, right-click on the `datasketches-memory-java9` project, and select
- First, right-click on the `datasketches-memory-java11` project, and select
**Properties/Java Build Path**.
- Next, open the **Module Dependencies** tab and select the `java.base` package.
- Click on **Configured details**, followed by **Expose package**.
@@ -109,7 +108,7 @@ Ensure that the required JPMS arguments are set for the compiler (Java 9 only).

![Eclipse java compiler arguments](img/eclipse-java-compiler-arguments-2.png "Eclipse project compiler arguments")

Note: These arguments need only be supplied for `datasketches-memory-java9`.
Note: These arguments need only be supplied for `datasketches-memory-java11`.

---

@@ -124,7 +123,6 @@ compliance level is set for each module by using the Eclipse `Java Compiler` dia

You might need to verify this for each module, making sure the correct compliance level is used:

- `datasketches-memory-java9` should use level 9 compliance.
- `datasketches-memory-java11` should use level 11 compliance.
- all other modules should use level 1.8 compliance.

@@ -135,17 +133,12 @@ You might need to verify this for each module, making sure the correct complianc
This should be set automatically by the IDE. However, you may ensure that the correct JRE is
used for each module by using the Eclipse **Java Build Path** dialog.

- First, open the project properties dialog for the `datasketches-memory-java9` project, and
- First, open the project properties dialog for the `datasketches-memory-java11` project, and
click on **Java Build Path**.
- Next, open the **Libraries** tab and select the **JRE System Library** under **Modulepath**.
- Click **Edit** and ensure that the **Execution Environment** is selected and set to Java 9:
- Click **Edit** and ensure that the **Execution Environment** is selected and set to Java 11:

![Eclipse build path](img/eclipse-build-path-1.png "Java 9 Eclipse project build path")

- Follow a similar process for `datasketches-memory-java11`, and verify that
**Execution Environment** is selected and set to Java 11:

![Eclipse build path](img/eclipse-build-path-2.png "Java 11 Eclipse project build path")
![Eclipse build path](img/eclipse-build-path-1.png "Java 11 Eclipse project build path")

- Lastly, for all other modules, verify that the **Execution Environment** is selected and set
to the Java 8 JRE:
@@ -39,13 +39,12 @@ for a maven module should be set as follows:
| datasketches-memory | 8 |
| datasketches-memory-java8 | 8 |
| datasketches-memory-java8-tests | 8 |
| datasketches-memory-java9 | 9 |
| datasketches-memory-java11 | 11 |
| datasketches-memory-resources | 8 |

#### Compiler arguments for JPMS

In order to compile Maven modules in Java versions 9 and above, it is necessary to provide the
In order to compile Maven modules in Java versions 11 and above, it is necessary to provide the
following arguments to the compiler. These are usually synchronised with the `pom.xml`
configuration:

@@ -73,7 +72,7 @@ Ensure that the correct SDK is used for each module using the IntelliJ project s

### Compiler arguments for JPMS

Ensure that the required JPMS arguments are set for the compiler (Java 9 only).
Ensure that the required JPMS arguments are set for the compiler (Java 11 only).
These should be detected and set automatically based on the `pom.xml` configuration.

![IntelliJ java compiler arguments](img/intellij-java-compiler-arguments.png "Intellij project compiler arguments")
@@ -36,7 +36,7 @@ version-specific APIs, which require different JDKs to compile correctly.

### Toolchains template

Your local environment requires toolchain entries for Java 8, 9 and 11 to build this project.
Your local environment requires toolchain entries for Java 8 and 11 to build this project.
These can be found in a reference `toolchains.xml` template in the `tools` directory.
Any maven commands used during development can be supplemented with:
`--toolchains tools/toolchains.xml`, without permanently modifying the local
@@ -54,14 +54,12 @@ In order to compile the project using Maven toolchains, the following environmen
| Environment variable | Value |
| --------------------------------- | ------------------------------------- |
| JAVA8_HOME | Home directory for Java 8 (openJDK) |
| JAVA9_HOME | Home directory for Java 9 (openJDK) |
| JAVA11_HOME | Home directory for Java 11 (openJDK) |

For example, if you are using [SDKMAN!](https://sdkman.io/), your environment
might be configured as follows:

- JAVA8_HOME: `/Users/me/.sdkman/candidates/java/8.0.282.hs-adpt`
- JAVA9_HOME: `/Users/me/.sdkman/candidates/java/9.0.4-open`
- JAVA11_HOME: `/Users/me/.sdkman/candidates/java/11.0.10.hs-adpt`

#### For MacOS or Linux variants
@@ -27,14 +27,12 @@ Datasketches Memory makes use of some features of the Java platform, for example
which have evolved in Java versions 9 and above. Therefore, a multi-module project allows us to
add support for later versions of Java by using independent Maven modules to target
platform-specific APIs. For example, to deallocate references a `sun.misc.Cleaner` will be used
in Java8, but the `jdk.internal.ref.Cleaner` is used in Java 9.
in Java8, but the `jdk.internal.ref.Cleaner` is used in Java 11.

This project has been divided into the following submodules:

* datasketches-memory-java8 (base version of the JVM that is currently supported)
* datasketches-memory-java8-tests
* datasketches-memory-java9 (Java9 equivalent of some platform specific classes in
datasketches-memory-java8)
* datasketches-memory-java11 (Java11 equivalent of some platform specific classes in
datasketches-memory-java8)
* datasketches-memory (MR-JAR assembly, does not contain source files)
@@ -17,7 +17,7 @@
under the License.
-->

# Java Platform Module System (JPMS) For JDK 9+
# Java Platform Module System (JPMS) For JDK 11+

The [Java Platform Module System](https://openjdk.java.net/projects/jigsaw/spec/) defines a module
system for the Java Platform. For more documentation on the implementation, see
@@ -49,7 +49,7 @@ dependency graph.

#### org.apache.datasketches.memory

In the `datasketches-memory-java9` maven submodule root, the following module declaration has
In the `datasketches-memory-java11` maven submodule root, the following module declaration has
been added:

```java
@@ -69,14 +69,14 @@ providing better encapsulation.
### Compiler arguments

Some dependencies are encapsulated by default, and this causes compilation to fail for
Java versions 9 and above.
Java versions 11 and above.
These dependencies can be made accessible at compile time through the use of the
`add-exports` compiler argument.
This argument allows one module to access some un-exported types of another module.
Datasketches Memory depends on several internal APIs and therefore requires special
exposition.

For example, in order to compile the `datasketches-memory-java9` submodule, the following compiler
For example, in order to compile the `datasketches-memory-java11` submodule, the following compiler
arguments are added to the Maven compiler plugin in the module's pom.xml file:

```xml
@@ -90,7 +90,7 @@ arguments are added to the Maven compiler plugin in the module's pom.xml file:

When allocating off-heap memory using `WritableMemory.allocateDirect(...)`,
reflection is used by the Datasketches Memory component to access JVM internal class
fields and methods that do not have `public` visibility. For JDK 9+, the JPMS
fields and methods that do not have `public` visibility. For JDK 11+, the JPMS
requires that the user add additional JVM run-time arguments (`add-opens...`, which permit this reflection.

Note that if the user has allocated off-heap memory using ByteBuffer.allocateDirect(...),
@@ -103,4 +103,4 @@ See the use **Use as a Library** and **Developer Usage** sections in the main [R
Java 8 does not support module declarations and the JPMS module system, and no additional
runtime arguments are necessary.
However, support is retained for Java 8 users by only including the compiled declaration
(`module-info.class`) in the `datasketches-memory` multi-release JAR for Java9 and above.
(`module-info.class`) in the `datasketches-memory` multi-release JAR for Java11 and above.
@@ -25,8 +25,8 @@ This document provides examples for the following scenarios:

1. Using the library from a Java 8 application
2. Using the library with on-heap memory only
3. Using off-heap memory in a non-modularized Java 9+ application
4. Using off-heap memory in a modularized Java 9+ application
3. Using off-heap memory in a non-modularized Java 11+ application
4. Using off-heap memory in a modularized Java 11+ application

### 1) Using the library from a Java 8 application

@@ -64,18 +64,18 @@ As an example, consider the following launch script that compiles and runs a sim

### 2) Using the library with on-heap memory only

Similarly, no additional runtime arguments are required in this scenario - regardless of whether the library is used from a Java 8 or Java 9+ application.
Similarly, no additional runtime arguments are required in this scenario - regardless of whether the library is used from a Java 8 or Java 11+ application.

As an example, consider the following launch script that compiles and runs a simple Java 9 application that only exclusively
As an example, consider the following launch script that compiles and runs a simple Java 11 application that only exclusively
uses on-heap memory:

```shell
JH=$JAVA9_HOME
JH=$JAVA11_HOME
JAVAC=$JH/bin/javac
JAVA=$JH/bin/java
JAR=$JH/bin/jar
patha=nomvn-nomod-heap-jdk9
patha=nomvn-nomod-heap-jdk11
cd $patha
@@ -96,11 +96,11 @@ uses on-heap memory:
org.xyz.memory.RunMain
```

### 3) Using off-heap memory in a non-modularized Java 9+ application
### 3) Using off-heap memory in a non-modularized Java 11+ application

The following section applies to applications that are not modularized JPMS applications.

In order to allocate off-heap memory using the `WritableMemory.allocateDirect(...)` method in Java 9 and above, you must provide the
In order to allocate off-heap memory using the `WritableMemory.allocateDirect(...)` method in Java 11 and above, you must provide the
following runtime arguments to the JVM:

```shell
@@ -113,15 +113,15 @@ following runtime arguments to the JVM:
These arguments expose encapsulated packages in the `java.base` package to the `org.apache.datasketches.memory` module,
which runs as an UNNAMED module in a non-JPMS (non-modularized) application.

The following launch script compiles and runs a non-modularized Java 9 application:
The following launch script compiles and runs a non-modularized Java 11 application:

```shell
JH=$JAVA9_HOME
JH=$JAVA11_HOME
JAVAC=$JH/bin/javac
JAVA=$JH/bin/java
JAR=$JH/bin/jar
patha=nomvn-nomod-jdk9
patha=nomvn-nomod-jdk11
cd $patha
@@ -150,11 +150,11 @@ where the traditional classpath (`-cp`) argument contains all modules, libraries
Note: `mods` is a local directory containing external modules, and `libs` is a local directory for external library
dependencies. No distinction is made between modules and libraries since they are both appended to the classpath.

### 4) Using off-heap memory in a modularized Java 9+ application
### 4) Using off-heap memory in a modularized Java 11+ application

The following section applies to modularized JPMS applications.

In order to allocate off-heap memory using the `WritableMemory.allocateDirect(...)` method in Java 9 and above, you must provide the
In order to allocate off-heap memory using the `WritableMemory.allocateDirect(...)` method in Java 11 and above, you must provide the
following runtime arguments to the JVM:

```shell
@@ -166,15 +166,15 @@ following runtime arguments to the JVM:

These arguments expose encapsulated packages in the `java.base` package to the `org.apache.datasketches.memory` module.

The following launch script compiles and runs a modularized Java 9 application:
The following launch script compiles and runs a modularized Java 11 application:

```shell
JH=$JAVA9_HOME
JH=$JAVA11_HOME
JAVAC=$JH/bin/javac
JAVA=$JH/bin/java
JAR=$JH/bin/jar
patha=nomvn-mod-jdk9
patha=nomvn-mod-jdk11
cd $patha
echo PWD:$(pwd)

0 comments on commit 427d435

Please sign in to comment.