Java 21 for OH5 development (#2426)

* Java 21 for OH5 development

Signed-off-by: Holger Friedrich <mail@holger-friedrich.de>

* rework after OH5 release

Signed-off-by: Holger Friedrich <mail@holger-friedrich.de>

* review comment

Signed-off-by: Holger Friedrich <mail@holger-friedrich.de>

---------

Signed-off-by: Holger Friedrich <mail@holger-friedrich.de>

configuration/blockly/index.md

@@ -44,7 +44,7 @@ Important: For Blockly to work, you need to have the [Javascript Scripting Addon
 ### openHAB 3 / openHAB 4  to openHAB 4.3 or Later - Migration
 
 From openHAB 4 onwards, the script engine is GraalJS provided by the [JS Scripting Addon](https://www.openhab.org/addons/automation/jsscripting/), **ECMAScript 2022**, when Blockly creates new scripts.
-OpenHAB versions before 4.3 could use **ECMAScript 2022** or **NashornJS** with **ECMAScript 5.1**, either installed by default or installed through an Addon.
+openHAB versions before 4.3 could use **ECMAScript 2022** or **NashornJS** with **ECMAScript 5.1**, either installed by default or installed through an Addon.
 **NashornJS** is no longer an option with openHAB 4.3 or later. Therefore the generated Blockly code needs to be converted to **ECMAScript 2022**.
 
 Converting is as easy as making sure the [JS Scripting Addon](https://www.openhab.org/addons/automation/jsscripting/) is installed, and opening your Blockly script.

configuration/migration/index.md

@@ -46,6 +46,8 @@ You should probably do your usual OS backup too to make sure you can get back to
 
 openHAB (since version 4) requires Java 17. Most modern Linux OS have an `openjdk-17-jdk` package available for you to install but alternative solutions such as [Zulu's OpenJDK](https://www.azul.com/downloads/zulu-community/?version=java-17-lts&package=jdk) (which openHABian can install for you) are available and these may run faster on 32-bit armhf platforms such as the Raspberry Pi.
 
+openHAB 5 development requires Java 21.
+
 You must also be on the relevant repository for openHAB, this hasn't changed for openHAB 4.x so the [same instructions for moving to it](https://www.openhab.org/docs/installation/linux.html#package-repository-installation) are still valid.
 
 For DEB based installers (apt), your `.list` file should contain the line:

developers/ide/eclipse.md

@@ -15,10 +15,10 @@ If you already have Eclipse installed it is recommended to perform a separate Ec
 
 ## Eclipse IDE Setup
 
-1. Install the Java 17 JDK if you did not have it installed.
+1. Install the Java 21 JDK if you did not have it installed.
 
    ::: warning Attention
-   openHAB development requires **Java JDK version 17**.
+   openHAB development requires **Java JDK version 21**.
    :::
 
 1. Download the "Eclipse Installer": [can be downloaded from the Eclipse web site](https://wiki.eclipse.org/Eclipse_Installer)

developers/index.md

@@ -16,7 +16,7 @@ Try [git - the simple guide](https://rogerdudler.github.io/git-guide/) as a star
 Add-ons and the openHAB core itself are written in Java.
 Java is not hard to learn, but it helps if you have a general technical understanding of programming languages.
 
-The different guides of this chapter assume that you are somewhat familiar with Java 17 and that you have a rough understanding of Git's workflow (e.g. "checkout", "branches", "push").
+The different guides of this chapter assume that you are somewhat familiar with Java 21 and that you have a rough understanding of Git's workflow (e.g. "checkout", "branches", "push").
 
 ## Choose the Right Concept
 
@@ -49,13 +49,10 @@ Please ensure that you have the following prerequisites installed as well:
 
 1. [Git](https://git-scm.com/downloads) For retrieving our source code and push changes back. On Windows: Must be available in %PATH%
 1. [Maven 3.x](https://maven.apache.org/download.cgi) Our build system tool. On Windows: Must be available in %PATH%
-1. Java JDK 17 or JDK 21, for example from Oracle [Oracle JDK 17](https://www.oracle.com/java/technologies/javase/jdk17-archive-downloads.html) or [Oracle JDK 21](https://www.oracle.com/java/technologies/javase/jdk21-archive-downloads.html). On Windows: %JAVA% must be set.
+1. Java JDK 21, for example from Oracle [Oracle JDK 21](https://www.oracle.com/java/technologies/javase/jdk21-archive-downloads.html). On Windows: %JAVA% must be set.
 
 ::: tip Note
-Whereas we recommend Java 17 for running openHAB, development can be safely done on Java 21.
-With default settings, the Java 21 compiler will generate Java objects compatible with JRE 17.
-If you run your openHAB server on Java 21, you can enable native Java 21 objects by adding `-Pj21` to the Maven command line.
-Note that our CI checks Java 17 and Java 21 compatibility, and we only use language features available in Java 17.
+Whereas openHAB 4.x series was based on Java 17, starting with openHAB 5.0.0-SNAPSHOT, **Java 21 is required**.
 :::
 
 You can use any IDE that is suitable for OSGi/Java development.

installation/index.md

@@ -41,10 +41,11 @@ You could also [download Azul Zulu](https://www.azul.com/downloads/zulu-communit
 Oracle Java is also suitable for most configurations but it's not recommended. Licensing restrictions may apply.
 
 ::: warning
-Java 17 is recommended for openHAB.
-Using Java 21 is possible, but still considered experimental.
-OpenHABian can install Java 21, but only on the native 64-bit image.
+Java 17 is recommended for openHAB 4.x series.
+openHABian can install Java 21, but only on the native 64-bit image.
 Please note that versions of Java other than 17 and 21 are not supported at the moment.
+
+openHAB 5 requires Java 21.
 :::
 
 | Java Platform                               | Advantages                                                                                                                                                                            | Disadvantages                                                                                                                                                                                                                                                                                                                        |

installation/linux.md

@@ -34,7 +34,7 @@ When installing Zulu or Zulu Embedded from a .zip or .tar archive, make sure to
 
 ::: tip Note
 Make sure to download Zulu or Java **17**.
-Using Java 21 is possible, but still considered experimental.
+Java 21 can be used openHAB 4.x, and is required for openHAB 5.
 :::
 
 ## Installation

installation/synology.md

@@ -5,7 +5,8 @@ title: Synology DiskStation
 
 :::tip Note
 
-openHAB 4 and higher need Java 17.
+openHAB 4.x series requires Java 17.
+Java 21 can be used openHAB 4.x, and is required for openHAB 5.
 You will need to provide a working Java installation on your DiskStation.
 The sections below are written for Java 11 but the docs are not updated currently, since we have not secured knowledge about how to install Java 17 on the DiskStation.
 If you can provide some proper sources and explanation, we are happy to include your contribution into this article.

installation/windows.md

@@ -19,7 +19,7 @@ Please be sure you have installed the required supporting applications as descri
 
 ### Set the `JAVA_HOME` System Environment Variable in Windows
 
-Note: If you have installed Zulu Java 17 (highly recommended for OH 4.x) you may skip this step because the JAVA_HOME environment variable was created during installation.
+Note: If you have installed Java 17 (recommended for OH 4.x) or Java 21, you may skip this step because the JAVA_HOME environment variable was created during installation.
 
 - Navigate to: Control Panel ➡️ System and Security ➡️ System ➡️ Advanced System Settings ➡️ Environment Variables ➡️ System Variables
 - Create a New System Variable named JAVA_HOME (or update the existing one) to match the installation directory of the Java Platform chosen and installed in the step [Prerequisites]({{base}}/installation/index.html#prerequisites).