You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@datasketches.apache.org by le...@apache.org on 2021/08/07 18:27:21 UTC
[datasketches-memory] branch master updated: Add license headers.
This is an automated email from the ASF dual-hosted git repository.
leerho pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/datasketches-memory.git
The following commit(s) were added to refs/heads/master by this push:
new bdbb636 Add license headers.
bdbb636 is described below
commit bdbb636dce71ff4b8033ac9dfbc60c3c20f59fa7
Author: Lee Rhodes <le...@users.noreply.github.com>
AuthorDate: Sat Aug 7 11:27:08 2021 -0700
Add license headers.
Compacted line lengths to make raw text more readable. Other minor
edits.
---
README.md | 61 +++++++++++++++++++++-------------
docs/eclipse.md | 84 +++++++++++++++++++++++++++++++++--------------
docs/intellij.md | 54 +++++++++++++++++++++---------
docs/maven-toolchains.md | 61 +++++++++++++++++++++++++---------
docs/maven.md | 54 +++++++++++++++++++++---------
docs/module-system.md | 82 ++++++++++++++++++++++++++++++---------------
docs/multi-release-jar.md | 49 +++++++++++++++++++--------
7 files changed, 314 insertions(+), 131 deletions(-)
diff --git a/README.md b/README.md
index 734e819..92a028b 100644
--- a/README.md
+++ b/README.md
@@ -26,15 +26,15 @@
=================
# DataSketches Java Memory Component
- The goal of this component of the library is to provide high performance access to native memory for primitives
- and primitive arrays. It also provides consistent views into heap-based primitive arrays,
- Java ByteBuffers and memory mapped files. This package is general purpose, has minimal external
- runtime dependencies and can be used in any application that needs to manage data structures outside
- the Java heap.
+ The goal of this component of the library is to provide high performance access to heap memory or
+ native memory for primitives, primitive arrays, ByteBuffers and memory mapped files.
+ This package is general purpose, has minimal external runtime dependencies and can be used in any
+ application that needs to manage data structures outside the Java heap.
Please visit the main [DataSketches website](https://datasketches.apache.org) for more information.
-If you are interested in making contributions to this site please see our [Community](https://datasketches.apache.org/docs/Community/) page for how to contact us.
+If you are interested in making contributions to this site please see our
+[Community](https://datasketches.apache.org/docs/Community/) page for how to contact us.
---
@@ -42,7 +42,8 @@ If you are interested in making contributions to this site please see our [Commu
Datasketches memory currently supports Java 8 up to and including Java 13.
-In order to allocate off-heap memory using the library in Java 9 and above, you must provide the following runtime arguments to the JVM:
+In order to allocate off-heap memory using the library in Java 9 and above, you must provide the
+following runtime arguments to the JVM:
```shell
--add-opens java.base/java.nio=org.apache.datasketches.memory \
@@ -50,7 +51,8 @@ In order to allocate off-heap memory using the library in Java 9 and above, you
--add-opens java.base/jdk.internal.ref=org.apache.datasketches.memory
```
-For example, to run your local application with full compatibility for the Java module system, you might use the following command:
+For example, to run your local application with full compatibility for the Java module system,
+you might use the following command:
```shell
$JAVA \
@@ -69,25 +71,38 @@ module datasketches.memory.multirelease.test {
}
```
-Note that the `add-opens` arguments are not required for cases where memory is allocated on the heap.
+Note that the `add-opens` arguments are not required for cases where memory is allocated on the
+heap.
---
## Build Instructions
-__NOTE:__ This component accesses resource files for testing. As a result, the directory elements of the full absolute path of the target installation directory must qualify as Java identifiers. In other words, the directory elements must not have any space characters (or non-Java identifier characters) in any of the path elements. This is required by the Oracle Java Specification in order to ensure location-independent access to resources: [See Oracle Location-Independent Access to Reso [...]
-
-__IMPORTANT:__ This project is structured as a maven multi-module project. Building this project might affect plugins that require early dependency resolution, such as the javadoc and eclipse plugins. The build instructions below have been modified to use the `process-classes` phase (instead of `compile`) for these use cases. For more information, see [this Maven Reactor issue](https://issues.apache.org/jira/browse/MNG-3283).
+__NOTE:__ This component accesses resource files for testing. As a result, the directory elements
+of the full absolute path of the target installation directory must qualify as Java identifiers.
+In other words, the directory elements must not have any space characters (or non-Java identifier
+characters) in any of the path elements. This is required by the Oracle Java Specification in
+order to ensure location-independent access to resources:
+[See Oracle Location-Independent Access to Resources](https://docs.oracle.com/javase/8/docs/technotes/guides/lang/resources.html)
+
+__IMPORTANT:__ This project is structured as a maven multi-module project.
+Building this project might affect plugins that require early dependency resolution, such as the
+javadoc and eclipse plugins. The build instructions below have been modified to use the
+`process-classes` phase (instead of `compile`) for these use cases. For more information,
+see this [Maven Reactor Issue](https://issues.apache.org/jira/browse/MNG-3283).
### JDK versions required to compile
This DataSketches component is pure Java and requires the following JDKs to compile:
+
- JDK8/Hotspot
- JDK9/Hotspot
- JDK11/Hotspot
-Ensure that your local environment has been configured according to the [Maven toolchain configuration](docs/maven-toolchains.md).
+Ensure that your local environment has been configured according to the
+[Maven Toolchains Configuration](docs/maven-toolchains.md).
### Recommended Build Tool
-This DataSketches component is structured as a Maven project and Maven is the recommended Build Tool.
+This DataSketches component is structured as a Maven project and Maven is the recommended Build
+Tool.
There are two types of tests: normal unit tests and tests run by the strict profile.
@@ -121,8 +136,9 @@ This will create the following Jars:
### Toolchains
-This project makes use of Maven toolchains to ensure that the correct Java compiler version is used when compiling source files.
-See the [Maven toolchain configuration](docs/maven-toolchains.md) for more details.
+This project makes use of Maven toolchains to ensure that the correct Java compiler version is
+used when compiling source files.
+See the [Maven Toolchains Configuration](docs/maven-toolchains.md) for more details.
### Dependencies
@@ -135,14 +151,15 @@ See the pom.xml file for test dependencies.
## Further documentation for contributors
-For more information on the project configuration, the following topics are discussed in more detail:
+For more information on the project configuration, the following topics are discussed in more
+detail:
-* [Maven configuration](docs/maven.md)
-* [Maven toolchain configuration](docs/maven-toolchains.md)
-* [Multi-release jar](docs/multi-release-jar.md)
+* [Maven Configuration](docs/maven.md)
+* [Maven Toolchains Configuration](docs/maven-toolchains.md)
+* [Multi-Release Jar](docs/multi-release-jar.md)
* [Java Platform Module System](docs/module-system.md)
In order to build and contribute to this project, please read the relevant IDE documentation:
-- [Eclipse IDE](docs/eclipse.md)
-- [IntelliJ IDE](docs/intellij.md)
+- [Eclipse IDE Setup](docs/eclipse.md)
+- [IntelliJ IDE Setup](docs/intellij.md)
diff --git a/docs/eclipse.md b/docs/eclipse.md
index e949060..8edfc1b 100644
--- a/docs/eclipse.md
+++ b/docs/eclipse.md
@@ -1,27 +1,49 @@
-# Eclipse IDE setup
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
-The use of Maven submodules to build a Multi Release JAR was motivated by its compatibility with popular IDEs. There are two configuration properties to be aware of when
-configuring your local development environment:
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+-->
+
+
+# Eclipse IDE Setup
+
+The use of Maven submodules to build a Multi Release JAR was motivated by its compatibility with
+popular IDEs. There are two configuration properties to be aware of when configuring your local
+development environment:
### Java compiler versions
-Settings are usually synchronised with Maven Toolchain configuration, otherwise the Java version for a Maven module
-should be set as follows:
+Settings are usually synchronised with Maven Toolchain configuration, otherwise the Java version
+for a Maven module should be set as follows:
| Maven submodule | JDK |
| --------------------------------- | --- |
-| datasketches-memory-root | 8 |
-| datasketches-memory | 8 |
-| datasketches-memory-java8 | 8 |
-| datasketches-memory-java8-tests | 8 |
-| datasketches-memory-java9 | 9 |
-| datasketches-memory-java11 | 11 |
+| datasketches-memory-root | 8 |
+| 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 following arguments to the
-compiler. These are usually synchronised with the `pom.xml` configuration:
+In order to compile Maven modules in Java versions 9 and above, it is necessary to provide the
+following arguments to the compiler. These are usually synchronised with the `pom.xml`
+configuration:
```xml
<compilerArgs>
@@ -38,11 +60,15 @@ Note that the following configuration was verified using Eclipse Version: 2020-1
### The eclipse maven plugin
-The [Eclipse Maven plugin](https://maven.apache.org/plugins/maven-eclipse-plugin/) is used to generate Eclipse IDE files. In order to run the eclipse plugin use:
+The [Eclipse Maven plugin](https://maven.apache.org/plugins/maven-eclipse-plugin/) is used to
+generate Eclipse IDE files. In order to run the eclipse plugin use:
$ mvn clean process-classes eclipse:eclipse -DskipTests=true
-More information about using the eclipse plugin with multi-module Maven builds can be found [here](https://maven.apache.org/plugins/maven-eclipse-plugin/reactor.html).
+More information about using the eclipse plugin with multi-module Maven builds can be found
+in the Maven
+[Multiple Module Projects](https://maven.apache.org/plugins/maven-eclipse-plugin/reactor.html)
+document.
Please note that this plugin is retired and no longer maintained!
@@ -61,13 +87,17 @@ From the **Package Explorer** View:
### Setting compiler arguments for JPMS
-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).
+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).
-- First, right-click on the `datasketches-memory-java9` project, and select **Properties/Java Build Path**.
+- First, right-click on the `datasketches-memory-java9` 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**.
-- In the dialog box, enter package: ```jdk.internal.ref```, and `org.apache.datasketches.memory` as the target module.
+- In the dialog box, enter package: ```jdk.internal.ref```, and
+`org.apache.datasketches.memory` as the target module.
- Ensure that the **exports** checkbox is selected.
@@ -82,7 +112,8 @@ Note: These arguments need only be supplied for `datasketches-memory-java9`.
### Setting Java compiler settings
-This should be set automatically by the IDE. However, you may ensure that the correct Java compliance level is set for each module by using the Eclipse `Java Compiler` dialog.
+This should be set automatically by the IDE. However, you may ensure that the correct Java
+compliance level is set for each module by using the Eclipse `Java Compiler` dialog.
- Open the **Java Compiler** dialog, and ensure **Enable project specific settings** is checked:
@@ -98,24 +129,29 @@ You might need to verify this for each module, making sure the correct complianc
### Setting JRE library versions
-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.
+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 click on **Java Build Path**.
+- First, open the project properties dialog for the `datasketches-memory-java9` 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:
-- Follow a similar process for `datasketches-memory-java11`, and verify that **Execution Environment** is selected and set to Java 11:
+- Follow a similar process for `datasketches-memory-java11`, and verify that
+**Execution Environment** is selected and set to Java 11:
-- Lastly, for all other modules, verify that the **Execution Environment** is selected and set to the Java 8 JRE:
+- Lastly, for all other modules, verify that the **Execution Environment** is selected and set
+to the Java 8 JRE:
### Running unit tests
-- Under the `datasketches-memory-java-8-tests` module, right-click on the `src/test/java` directory.
+- Under the `datasketches-memory-java-8-tests` module, right-click on the `src/test/java`
+directory.
- Select **Run-As** / **TestNG Test**
- It should open a new window and run over 400 tests without error.
diff --git a/docs/intellij.md b/docs/intellij.md
index c7425b0..7b77219 100644
--- a/docs/intellij.md
+++ b/docs/intellij.md
@@ -1,28 +1,50 @@
-# IntelliJ IDE setup
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
-The use of Maven submodules to build a Multi Release JAR was motivated by its compatibility with popular IDEs.
+ http://www.apache.org/licenses/LICENSE-2.0
-There are two configuration properties to be aware of when configuring your local development environment:
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+-->
+
+# IntelliJ IDE Setup
+
+The use of Maven submodules to build a Multi Release JAR was motivated by its compatibility with
+popular IDEs.
+
+There are two configuration properties to be aware of when configuring your local development
+environment:
#### Java compiler versions
-Settings are usually synchronised with maven toolchain configuration, otherwise the Java version for a maven module
-should be set as follows:
+Settings are usually synchronised with maven toolchain configuration, otherwise the Java version
+for a maven module should be set as follows:
| Maven submodule | JDK |
| --------------------------------- | --- |
-| datasketches-memory-root | 8 |
-| datasketches-memory | 8 |
-| datasketches-memory-java8 | 8 |
-| datasketches-memory-java8-tests | 8 |
-| datasketches-memory-java9 | 9 |
-| datasketches-memory-java11 | 11 |
+| datasketches-memory-root | 8 |
+| 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 following arguments to the
-compiler. These are usually synchronised with the `pom.xml` configuration:
+In order to compile Maven modules in Java versions 9 and above, it is necessary to provide the
+following arguments to the compiler. These are usually synchronised with the `pom.xml`
+configuration:
```xml
<compilerArgs>
@@ -35,7 +57,8 @@ compiler. These are usually synchronised with the `pom.xml` configuration:
## Running Datasketches-Memory in IntelljJ-IDEA
-Note that the following configuration was verified using IntelliJ IDEA 2021.1.2 (Community Edition).
+Note that the following configuration was verified using IntelliJ IDEA 2021.1.2
+(Community Edition).
### Java compiler versions
@@ -47,6 +70,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). These should be detected and set automatically based on the `pom.xml` configuration.
+Ensure that the required JPMS arguments are set for the compiler (Java 9 only).
+These should be detected and set automatically based on the `pom.xml` configuration.
diff --git a/docs/maven-toolchains.md b/docs/maven-toolchains.md
index a9e5148..f36cb8c 100644
--- a/docs/maven-toolchains.md
+++ b/docs/maven-toolchains.md
@@ -1,23 +1,50 @@
-# Maven toolchains
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+-->
+
+# Maven Toolchains Configuration
From the [maven-toolchain-plugin documentation](https://maven.apache.org/plugins/maven-toolchains-plugin/usage.html):
-> A Toolchain is an object that Maven plugins can use to retrieve preconfigured tools (including location and other information).
-With the jdk toolchain, for example, instead of being stuck with the JDK used to run Maven, all plugins
-can use the same or other JDK instances without hardcoding absolute paths into the pom.xml and without configuring
-every plugin that require a path to JDK tools.
->
+> A Toolchain is an object that Maven plugins can use to retrieve preconfigured tools
+> (including location and other information).
+> With the jdk toolchain, for example, instead of being stuck with the JDK used to run Maven,
+> all plugins can use the same or other JDK instances without hardcoding absolute paths
+> into the pom.xml and without configuring every plugin that require a path to JDK tools.
+
### Motivation
-Toolchains are used in different maven modules to ensure that the correct Java compiler version is used when compiling source files. This is because `datasketches-memory` uses some JDK version-specific APIs, which require different JDKs to compile correctly.
+Toolchains are used in different maven modules to ensure that the correct Java compiler version
+is used when compiling source files. This is because `datasketches-memory` uses some JDK
+version-specific APIs, which require different JDKs to compile correctly.
-### Toolchain template
+### Toolchains template
-Your local environment requires toolchain entries for Java 8, 9 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 a local `~/.m2/toolchains.xml` file (recommended).
+Your local environment requires toolchain entries for Java 8, 9 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 a local
+`~/.m2/toolchains.xml` file (recommended).
-Alternatively, the toolchain template can be copied to your local maven `toolchains.xml` e.g. `~/.m2/toolchains.xml`. If there is already a locally configured `toolchains.xml` file, the requisite entries should be merged into the existing file if they do not already exist.
+Alternatively, the toolchain template can be copied to your local maven `toolchains.xml`,
+e.g. `~/.m2/toolchains.xml`. If there is already a locally configured `toolchains.xml` file,
+the requisite entries should be merged into the existing file if they do not already exist.
### Environment variables
@@ -35,22 +62,26 @@ The following environment variables should be set as follows:
| 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:
+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
-Users can discover what JDKs have been loaded into their environment by using the following command:
+Users can discover what JDKs have been loaded into their environment by using the following
+command:
- /usr/libexec/java_home -V
### Eclipse configuration
-If you are an Eclipse user, you may need further configuration for your IDE to use the appropriate JDK for each module - see the [Eclipse IDE setup](eclipse.md).
+If you are an Eclipse user, you may need further configuration for your IDE to use the
+appropriate JDK for each module - see the [Eclipse IDE Setup](eclipse.md).
### IntelliJ configuration
-Similarly, if you are an Eclipse user, you may need further configuration for your IDE to use the appropriate JDK for each module - see the [IntelliJ IDE setup](intellij.md).
+Similarly, if you are an Eclipse user, you may need further configuration for your IDE to use the
+appropriate JDK for each module - see the [IntelliJ IDE Setup](intellij.md).
diff --git a/docs/maven.md b/docs/maven.md
index d32899f..c33e3f3 100644
--- a/docs/maven.md
+++ b/docs/maven.md
@@ -1,30 +1,54 @@
-# Maven multi-module project
-
-This project is a multi-module Maven project. A multi-module Maven project consists of an aggregator project
-(the `datasketches-memory-root` project), together with a set of submodules. The aggregator's configuration is inherited
-by each submodule, thus reducing duplication.
-
-`datasketches-memory` makes use of some features of the Java platform, for example, `Unsafe`, 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.
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+-->
+
+# Maven Configuration: Multi-Module Project
+
+This project is a multi-module Maven project. A multi-module Maven project consists of an
+aggregator project (the `datasketches-memory-root` project), together with a set of submodules.
+The aggregator's configuration is inherited by each submodule, thus reducing duplication.
+
+`datasketches-memory` makes use of some features of the Java platform, for example, `Unsafe`,
+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.
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-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 (JAR assembly, does not contain source files)
* datasketches-memory-resources (Runs test suite against assembled JAR)
### Artifact assembly
-The [Maven assembly plugin](https://maven.apache.org/plugins/maven-assembly-plugin/) builds all artifacts for this
-project from the other modules within the project. These modules are complementary and not standalone.
+The [Maven assembly plugin](https://maven.apache.org/plugins/maven-assembly-plugin/) builds all
+artifacts for this project from the other modules within the project.
+These modules are complementary and not standalone.
Therefore, they are not installed and downloaded independently by the end user.
-Instead, the Maven assembly plugin builds all jars, and hides the multi-module configuration from the end user.
+Instead, the Maven assembly plugin builds all jars, and hides the multi-module configuration
+from the end user.
The following jars are assembled by the `datasketches-memory` module:
diff --git a/docs/module-system.md b/docs/module-system.md
index df683c0..fea7048 100644
--- a/docs/module-system.md
+++ b/docs/module-system.md
@@ -1,32 +1,56 @@
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+-->
+
# Java Platform Module System (JPMS)
-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 [JEP-261](https://openjdk.java.net/jeps/261).
+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
+[JEP-261](https://openjdk.java.net/jeps/261).
#### Reliable configuration
-> Reliable configuration, to replace the brittle, error-prone class-path mechanism with a means for program components
+> Reliable configuration, to replace the brittle, error-prone class-path mechanism with a means
+for program components
> to declare explicit dependences upon one another;
-This prevents ClassLoader errors such as `NoClassDefFoundError` that typically occur at runtime and make applications
-less reliable.
+This prevents ClassLoader errors such as `NoClassDefFoundError` that typically occur at runtime
+and make applications less reliable.
#### Strong encapsulation
-> Strong encapsulation, to allow a component to declare which of its APIs are accessible by other components, and which
-> are not;
+> Strong encapsulation, to allow a component to declare which of its APIs are accessible by other
+components, and which are not;
-JDK internals are now strongly encapsulated, except for critical internal APIs such as `sun.misc.Unsafe`
-(see [JEP-396](https://openjdk.java.net/jeps/396) and [JEP-403](https://openjdk.java.net/jeps/403)).
+JDK internals are now strongly encapsulated, except for critical internal APIs such as
+`sun.misc.Unsafe` (see [JEP-396](https://openjdk.java.net/jeps/396) and
+[JEP-403](https://openjdk.java.net/jeps/403)).
`datasketches-memory` can no longer access these APIs by default, and requires explicit access.
### Module declarations
-A module declaration is a java file (typically `module-info.java`) that explicitly defines a dependency graph.
+A module declaration is a java file (typically `module-info.java`) that explicitly defines a
+dependency graph.
#### org.apache.datasketches.memory
-In the `datasketches-memory-java9` maven submodule root, the following module declaration has been added:
+In the `datasketches-memory-java9` maven submodule root, the following module declaration has
+been added:
```java
module org.apache.datasketches.memory {
@@ -39,13 +63,15 @@ module org.apache.datasketches.memory {
}
```
-This declaration explicitly defines the dependencies for `datasketches-memory`, as well as the external API.
-The `org.apache.datasketches.internal` package is now inaccessible to the end user, providing better encapsulation.
+This declaration explicitly defines the dependencies for `datasketches-memory`, as well as the
+external API. The `org.apache.datasketches.internal` package is now inaccessible to the end user,
+providing better encapsulation.
#### org.apache.datasketches.memory.tests
-The module declaration above makes provision for unit testing. The `org.apache.datasketches.internal` package is not
-accessible to the end user, but is accessible to the `org.apache.datasketches.memory.tests` module:
+The module declaration above makes provision for unit testing.
+The `org.apache.datasketches.internal` package is not accessible to the end user,
+but is accessible to the `org.apache.datasketches.memory.tests` module:
```java
module org.apache.datasketches.memory.tests {
@@ -57,13 +83,16 @@ module org.apache.datasketches.memory.tests {
### Compiler arguments
-Some dependencies are encapsulated by default, and this causes compilation to fail for Java versions 9 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 of the unexported types of another module. Datasketches memory has come
-to depend on several internal APIs and therefore requires special exposition.
+Some dependencies are encapsulated by default, and this causes compilation to fail for
+Java versions 9 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 of the unexported types of another module.
+Datasketches memory has come to depend on several internal APIs and therefore requires special
+exposition.
-For example, in order to compile the `datasketches-memory-java9` submodule, the following compiler arguments are added
-to the Maven compiler plugin in the module's pom.xml file:
+For example, in order to compile the `datasketches-memory-java9` submodule, the following compiler
+arguments are added to the Maven compiler plugin in the module's pom.xml file:
```xml
<compilerArgs>
@@ -74,9 +103,10 @@ to the Maven compiler plugin in the module's pom.xml file:
### Runtime arguments (off-heap memory only)
-When allocating off-heap memory, reflection is used by the datasketches memory library in cases where fields and methods that do not have `public` visibility
-in a class. Reflective access requires additional arguments to be provided by the user at runtime, in order to use the
-`datasketches-memory` JPMS module in Java versions 9 and above.
+When allocating off-heap memory, reflection is used by the datasketches memory library in cases
+where fields and methods that do not have `public` visibility in a class.
+Reflective access requires additional arguments to be provided by the user at runtime,
+in order to use the `datasketches-memory` JPMS module in Java versions 9 and above.
The following runtime arguments should be provided when allocating memory off-heap:
@@ -91,5 +121,5 @@ Note that these arguments are not required for cases where memory is allocated o
### JPMS and Java 8
Java 8 does not support module declarations and the JPMS module system.
-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.
+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.
diff --git a/docs/multi-release-jar.md b/docs/multi-release-jar.md
index 02bf709..0f6ed4c 100644
--- a/docs/multi-release-jar.md
+++ b/docs/multi-release-jar.md
@@ -1,31 +1,52 @@
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+-->
+
# 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).
+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.
+> 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`:
+This is specifically the case for the DataSketches Memory component.
-> 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.
+> 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.
### Assembly
-The Maven assembly plugin uses the Maven submodules during the `package` phase. The following maven submodules to
-source the compiled class files for the MR-JAR:
+The Maven assembly plugin uses the Maven submodules during the `package` phase.
+The following maven submodules to source the compiled class files for the MR-JAR:
### Manifest
-The Maven assembly plugin copies version specific class files into JAR manifest META-INF directory, as
-shown in the diagram below:
+The Maven assembly plugin copies version specific class files into JAR manifest META-INF
+directory, as shown in the diagram below:
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@datasketches.apache.org
For additional commands, e-mail: commits-help@datasketches.apache.org