Merge branch 'master' into releases/r4.0.0

Signed-off-by: Franz Wilhelmstötter <[email protected]>

# Conflicts:
#	.github/workflows/gradle.yml
#	build.gradle.kts
#	buildSrc/src/main/kotlin/Env.kt
#	jpx/src/main/java/io/jenetics/jpx/GPX.java
#	jpx/src/main/java/io/jenetics/jpx/format/Location.java
#	jpx/src/main/java/io/jenetics/jpx/geom/MathUtils.java
#	jpx/src/main/java/io/jenetics/jpx/package-info.java
#	jpx/src/main/java/module-info.java
#	settings.gradle.kts

.github/workflows/gradle.yml

@@ -17,7 +17,7 @@ jobs:
         strategy:
             matrix:
                 os: [ ubuntu-latest, macos-latest ]
-                java-version: [ 21  ]
+                java-version: [ 21, 23  ]
         steps:
             - uses: actions/checkout@v2
 

README.md

@@ -4,19 +4,19 @@
 [![Maven Central](https://maven-badges.herokuapp.com/maven-central/io.jenetics/jpx/badge.svg)](http://search.maven.org/#search%7Cga%7C1%7Ca%3A%22jpx%22)
 [![Javadoc](https://www.javadoc.io/badge/io.jenetics/jpx.svg)](http://www.javadoc.io/doc/io.jenetics/jpx)
 
-**JPX** is a Java library for creating, reading and writing [GPS](https://en.wikipedia.org/wiki/Global_Positioning_System) data in [GPX](https://en.wikipedia.org/wiki/GPS_Exchange_Format) format. It is a *full* implementation of version [1.1](http://www.topografix.com/GPX/1/1/) and version [1.0](http://www.topografix.com/gpx_manual.asp) of the GPX format. The data classes are completely immutable and allows a functional programming style. They  are working also nicely with the Java [Stream](https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/util/stream/Stream.html) API. It is also possible to convert the location information into strings which are compatible to the [ISO 6709](http://en.wikipedia.org/wiki/ISO_6709) standard.
+**JPX** is a Java library for creating, reading and writing [GPS](https://en.wikipedia.org/wiki/Global_Positioning_System) data in [GPX](https://en.wikipedia.org/wiki/GPS_Exchange_Format) format. It is a *full* implementation of version [1.1](http://www.topografix.com/GPX/1/1/) and version [1.0](http://www.topografix.com/gpx_manual.asp) of the GPX format. The data classes are completely immutable and allows a functional programming style. They are working also nicely with the Java [Stream](https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/util/stream/Stream.html) API. It is also possible to convert the location information into strings which are compatible to the [ISO 6709](http://en.wikipedia.org/wiki/ISO_6709) standard.
 
 Besides the basic functionality of reading and writing GPX files, the library also allows manipulating the read GPX object in a functional way.
 
 
 ## Dependencies
 
-No external dependencies are needed by the _JPX_ library. It only needs **Java 17** to compile and run. It also runs and compiles with **Java 21**.
+The _JPX_ library needs no external dependencies. It only needs **Java 17** to compile and run. It also runs and compiles with **Java 21** and **Java 23**.
 
 
 ## Building JPX
 
-For building the JPX library you have to check out the `master` branch from GitHub.
+For building the JPX library, you have to check out the `master` branch from GitHub.
 
     $ git clone https://github.com/jenetics/jpx.git
 
@@ -32,22 +32,22 @@ For building the JPX library you have to check out the `master` branch from GitH
 
 ## Examples
 
-### Creating new GPX object with 3 track-points
+### Creating a new GPX object with 3 track-points
 
 ```java
 final GPX gpx = GPX.builder()
     .addTrack(track -> track
         .addSegment(segment -> segment
-        .addPoint(p -> p.lat(48.20100).lon(16.31651).ele(283))
-        .addPoint(p -> p.lat(48.20112).lon(16.31639).ele(278))
-        .addPoint(p -> p.lat(48.20126).lon(16.31601).ele(274))))
+            .addPoint(p -> p.lat(48.20100).lon(16.31651).ele(283))
+            .addPoint(p -> p.lat(48.20112).lon(16.31639).ele(278))
+            .addPoint(p -> p.lat(48.20126).lon(16.31601).ele(274))))
     .build();
 ```
 
 **Writing GPX object to a file**
 
 ```java
-GPX.write(gpx, "track.gpx");
+GPX.write(gpx, Path.of("track.gpx"));
 ```
 
 *GPX output*
@@ -75,7 +75,7 @@ GPX.write(gpx, "track.gpx");
 This example writes a given `GPX` object to a file, reads it again and prints the `WayPoint`s of all tracks and all track-segments to the console.
 
 ```java
-GPX.write(gpx, "track.gpx");
+GPX.write(gpx, Path.of("track.gpx"));
 GPX.read("gpx.xml").tracks()
     .flatMap(Track::segments)
     .flatMap(TrackSegment::points)
@@ -145,7 +145,7 @@ final GPX gpx11 = gpx10.toBuilder()
     .build();
 
 // Writing GPX to file.
-GPX.write(gpx11, "track-v11.gpx");
+GPX.write(gpx11, Path.of("track-v11.gpx"));
 ```
 
 ### ISO 6709 location strings
@@ -283,7 +283,7 @@ final GPX gpx1 = gpx.toBuilder()
 
 ### XML configuration
 
-The _JPX_ library uses the XML classes available in the Java [`java.xml`](https://docs.oracle.com/en/java/javase/11/docs/api/java.xml/module-summary.html) module. This API is highly configurable and it is possible to replace the underlying implementation. Especially for Android, using different XML implementation is a necessity. _JPX_ uses three _factory_ classes for reading/writing GPX files:
+The _JPX_ library uses the XML classes available in the Java [`java.xml`](https://docs.oracle.com/en/java/javase/11/docs/api/java.xml/module-summary.html) module. This API is highly configurable, and it is possible to replace the underlying implementation. Especially for Android, using different XML implementation is a necessity. _JPX_ uses three _factory_ classes for reading/writing GPX files:
 
 1. [`XMLInputFactory`](https://docs.oracle.com/en/java/javase/11/docs/api/java.xml/javax/xml/stream/XMLInputFactory.html): This class is needed for reading GPX files.
 1. [`XMLOutputFactory`](https://docs.oracle.com/en/java/javase/11/docs/api/java.xml/javax/xml/stream/XMLOutputFactory.html): This class is needed for writing GPX files.
@@ -304,7 +304,7 @@ final class ValidatingDocumentBuilder extends XMLProvider {
     }
 }
 ```
-And don't forget to create a `META-INF/services/io.jenetics.jpx.XMLProvider` file with the following content:
+And remember to create a `META-INF/services/io.jenetics.jpx.XMLProvider` file with the following content:
 
 ```
 org.acme.NonValidatingDocumentBuilder
@@ -314,7 +314,7 @@ org.acme.NonValidatingDocumentBuilder
 
 The library is licensed under the [Apache License, Version 2.0](http://www.apache.org/licenses/LICENSE-2.0.html).
 
-    Copyright 2016-2023 Franz Wilhelmstötter
+    Copyright 2016-2024 Franz Wilhelmstötter
 
     Licensed under the Apache License, Version 2.0 (the "License");
     you may not use this file except in compliance with the License.
@@ -330,6 +330,13 @@ The library is licensed under the [Apache License, Version 2.0](http://www.apach
 
 ## Release notes
 
+### [3.2.0](https://github.com/jenetics/jpx/releases/tag/v3.2.0)
+
+#### Improvements
+
+* [#183](https://github.com/jenetics/jpx/issues/183): Update Gradle to 8.11 and improve build scripts.
+* [#181](https://github.com/jenetics/jpx/pull/181): Update code examples in README.
+
 ### [3.1.0](https://github.com/jenetics/jpx/releases/tag/v3.1.0)
 
 #### Improvements

RELEASE_NOTES.md

@@ -1,5 +1,12 @@
 ## Release notes
 
+### [3.2.0](https://github.com/jenetics/jpx/releases/tag/v3.2.0)
+
+#### Improvements
+
+* [#183](https://github.com/jenetics/jpx/issues/183): Update Gradle to 8.11 and improve build scripts.
+* [#181](https://github.com/jenetics/jpx/pull/181): Update code examples in README.
+
 ### [3.0.1](https://github.com/jenetics/jpx/releases/tag/v3.0.1)
 
 #### Bugs

build.gradle.kts

@@ -1,3 +1,6 @@
+import io.jenetics.gradle.dsl.isModule
+import io.jenetics.gradle.dsl.moduleName
+
 /*
  * Java GPX Library (@__identifier__@).
  * Copyright (c) @__year__@ Franz Wilhelmstötter
@@ -30,7 +33,7 @@ plugins {
 rootProject.version = JPX.VERSION
 
 tasks.named<Wrapper>("wrapper") {
-	version = "8.4"
+	version = "8.11"
 	distributionType = Wrapper.DistributionType.ALL
 }
 
@@ -110,8 +113,8 @@ fun setupJava(project: Project) {
 		"Build-OS-Arch" to Env.BUILD_OS_ARCH,
 		"Build-OS-Version" to Env.BUILD_OS_VERSION
 	)
-	if (project.extra.has("moduleName")) {
-		attr["Automatic-Module-Name"] = project.extra["moduleName"].toString()
+	if (project.isModule) {
+		attr["Automatic-Module-Name"] = project.moduleName
 	}
 
 	project.tasks.withType<Jar> {
@@ -128,7 +131,7 @@ fun setupTestReporting(project: Project) {
 	project.apply(plugin = "jacoco")
 
 	project.configure<JacocoPluginExtension> {
-		toolVersion = "0.8.9"
+		toolVersion = "0.8.12"
 	}
 
 	project.tasks {

buildSrc/build.gradle.kts

@@ -1,3 +1,4 @@
+import org.jetbrains.kotlin.gradle.dsl.JvmTarget
 import org.jetbrains.kotlin.gradle.tasks.KotlinCompile
 
 /*
@@ -23,7 +24,7 @@ import org.jetbrains.kotlin.gradle.tasks.KotlinCompile
 /**
  * @author <a href="mailto:[email protected]">Franz Wilhelmstötter</a>
  * @since 2.1
- * @version 2.1
+ * @version 3.2
  */
 plugins {
 	`java-gradle-plugin`
@@ -35,8 +36,10 @@ repositories {
 	gradlePluginPortal()
 }
 
-tasks.withType<KotlinCompile>().configureEach {
-	kotlinOptions.jvmTarget = "17"
+tasks.withType<KotlinCompile> {
+	compilerOptions {
+		jvmTarget.set(JvmTarget.JVM_17)
+	}
 }
 
 configure<JavaPluginExtension> {

buildSrc/src/main/kotlin/Env.kt

@@ -26,25 +26,25 @@ import java.time.format.DateTimeFormatter
  * Common environment values.
  */
 object Env {
-	val NOW = ZonedDateTime.now()
+	private val NOW: ZonedDateTime = ZonedDateTime.now()
 
-	val YEAR = Year.now();
+	private val YEAR: Year = Year.now();
 
 	val COPYRIGHT_YEAR = "2016-${YEAR}"
 
-	val DATE_FORMAT = DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm")
+	private val DATE_FORMAT: DateTimeFormatter = DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm")
 
-	val BUILD_DATE = DATE_FORMAT.format(NOW)
+	val BUILD_DATE: String = DATE_FORMAT.format(NOW)
 
-	val BUILD_JDK = System.getProperty("java.version")
+	val BUILD_JDK: String = System.getProperty("java.version")
 
-	val BUILD_OS_NAME = System.getProperty("os.name")
+	val BUILD_OS_NAME: String = System.getProperty("os.name")
 
-	val BUILD_OS_ARCH = System.getProperty("os.arch")
+	val BUILD_OS_ARCH: String = System.getProperty("os.arch")
 
-	val BUILD_OS_VERSION = System.getProperty("os.version")
+	val BUILD_OS_VERSION: String = System.getProperty("os.version")
 
-	val BUILD_BY = System.getProperty("user.name")
+	val BUILD_BY: String = System.getProperty("user.name")
 
 }
 

buildSrc/src/main/kotlin/io/jenetics/gradle/dsl/Extensions.kt

@@ -0,0 +1,43 @@
+/*
+ * Java GPX Library (@__identifier__@).
+ * Copyright (c) @__year__@ Franz Wilhelmstötter
+ *
+ * Licensed 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.
+ *
+ * Author:
+ *    Franz Wilhelmstötter ([email protected])
+ */
+
+/**
+ * @author <a href="mailto:[email protected]">Franz Wilhelmstötter</a>
+ * @since 3.2
+ * @version 3.2
+ */
+package io.jenetics.gradle.dsl
+
+import org.gradle.api.Project
+import org.gradle.kotlin.dsl.extra
+
+/**
+ * Gets the module name of the project, as configured in the build file.
+ */
+var Project.moduleName: String
+	get() = if (this.isModule) this.extra.get("moduleName").toString()
+			else this.name
+	set(value) = this.extra.set("moduleName", value)
+
+/**
+ * Checks if the project is configured as a module.
+ */
+val Project.isModule: Boolean
+	get() = this.extra.has("moduleName")

gradle/wrapper/gradle-wrapper.properties

@@ -1,6 +1,6 @@
 distributionBase=GRADLE_USER_HOME
 distributionPath=wrapper/dists
-distributionUrl=https\://services.gradle.org/distributions/gradle-8.4-all.zip
+distributionUrl=https\://services.gradle.org/distributions/gradle-8.11-all.zip
 networkTimeout=10000
 validateDistributionUrl=true
 zipStoreBase=GRADLE_USER_HOME

gradlew

@@ -15,6 +15,8 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 #
+# SPDX-License-Identifier: Apache-2.0
+#
 
 ##############################################################################
 #
@@ -55,7 +57,7 @@
 #       Darwin, MinGW, and NonStop.
 #
 #   (3) This script is generated from the Groovy template
-#       https://github.com/gradle/gradle/blob/HEAD/subprojects/plugins/src/main/resources/org/gradle/api/internal/plugins/unixStartScript.txt
+#       https://github.com/gradle/gradle/blob/HEAD/platforms/jvm/plugins-application/src/main/resources/org/gradle/api/internal/plugins/unixStartScript.txt
 #       within the Gradle project.
 #
 #       You can find Gradle at https://github.com/gradle/gradle/.
@@ -84,7 +86,8 @@ done
 # shellcheck disable=SC2034
 APP_BASE_NAME=${0##*/}
 # Discard cd standard output in case $CDPATH is set (https://github.com/gradle/gradle/issues/25036)
-APP_HOME=$( cd "${APP_HOME:-./}" > /dev/null && pwd -P ) || exit
+APP_HOME=$( cd -P "${APP_HOME:-./}" > /dev/null && printf '%s
+' "$PWD" ) || exit
 
 # Use the maximum available, or set MAX_FD != -1 to use that value.
 MAX_FD=maximum

gradlew.bat

@@ -13,6 +13,8 @@
 @rem See the License for the specific language governing permissions and
 @rem limitations under the License.
 @rem
+@rem SPDX-License-Identifier: Apache-2.0
+@rem
 
 @if "%DEBUG%"=="" @echo off
 @rem ##########################################################################
@@ -43,11 +45,11 @@ set JAVA_EXE=java.exe
 %JAVA_EXE% -version >NUL 2>&1
 if %ERRORLEVEL% equ 0 goto execute
 
-echo.
-echo ERROR: JAVA_HOME is not set and no 'java' command could be found in your PATH.
-echo.
-echo Please set the JAVA_HOME variable in your environment to match the
-echo location of your Java installation.
+echo. 1>&2
+echo ERROR: JAVA_HOME is not set and no 'java' command could be found in your PATH. 1>&2
+echo. 1>&2
+echo Please set the JAVA_HOME variable in your environment to match the 1>&2
+echo location of your Java installation. 1>&2
 
 goto fail
 
@@ -57,11 +59,11 @@ set JAVA_EXE=%JAVA_HOME%/bin/java.exe
 
 if exist "%JAVA_EXE%" goto execute
 
-echo.
-echo ERROR: JAVA_HOME is set to an invalid directory: %JAVA_HOME%
-echo.
-echo Please set the JAVA_HOME variable in your environment to match the
-echo location of your Java installation.
+echo. 1>&2
+echo ERROR: JAVA_HOME is set to an invalid directory: %JAVA_HOME% 1>&2
+echo. 1>&2
+echo Please set the JAVA_HOME variable in your environment to match the 1>&2
+echo location of your Java installation. 1>&2
 
 goto fail
 

jpx/build.gradle.kts

@@ -1,3 +1,5 @@
+import io.jenetics.gradle.dsl.moduleName
+
 /*
  * Java GPX Library (@__identifier__@).
  * Copyright (c) @__year__@ Franz Wilhelmstötter
@@ -31,7 +33,7 @@ plugins {
 
 description = "JPX - Java GPX (GPS) Library"
 
-extra["moduleName"] = "io.jenetics.jpx"
+moduleName = "io.jenetics.jpx"
 
 dependencies {
 	testImplementation(libs.assertj)

jpx/src/main/java/io/jenetics/jpx/Bounds.java

@@ -218,7 +218,7 @@ public static Bounds of(
 	 * @return a new {@code Bounds} object with the given extent
 	 * @throws IllegalArgumentException if the latitude values are not within
 	 *         the range of {@code [-90..90]}
-	 * @throws IllegalArgumentException if the longitudes value are not within
+	 * @throws IllegalArgumentException if the longitude values are not within
 	 *         the range of {@code [-180..180]}
 	 */
 	public static Bounds of(