...

Within JEMH you are able to install and use additional scripting languages. This pages covers the relevant files and versions that are needed to install Nashorn, Groovy and Graal when using Java 8,11 or 17. How Note: how these different languages are installed will depend on the Java version that is in use.

Install into JDK

Adding module-info.class within the Jar file

When jar files are made they sometimes do not contain a Module-info.class file which is used to identify that the jar file can be used as a Java module. You are able to create the module-info.class file by using the following commands and this will then mean that the jar file can be used as a module within the Java Runtime Environment.

Creating module-info.java

The following terminal command will generate a module-info.java file that contains the relevant information about the jar file.

jdeps --generate-module-info out <jar_file_path>

Compile module-info.java to create module-info.class

This will compile the module-info.java file into a module-info.class which can then be used to identify the jar file as a module. Note: <module name> is identified when the above jdeps command has been run.

javac --patch-module <module_name>=<jar_file_path> out/module-info.java

Add the missing module-info.class into the jar file.

This will place the created module-info.class file into the jar file.

jar uf <jar_file_location> module-info.class

Nashorn

Java 8 / Java 11

Both Java 8 and Java 11 come with Nashorn, an engine supporting ECMAScript-262 5.1 standard. That the Jira installer ships with, and which is recommended cross platform ships with an ECMAScript implementation, so no additional configuration is strictly necessary to script JEMH Field Processors, Project Mappings, and future script-capable areas.

Java 17

Download the Relevant files which can be downloaded by using the following:

wget https://repo1.maven.org/maven2/org/openjdk/nashorn/nashorn-core/15.4/nashorn-core-15.4.jar
wget https://repo1.maven.org/maven2/org/ow2/asm/asm/7.3.1/asm-7.3.1.jar
wget https://repo1.maven.org/maven2/org/ow2/asm/asm-commons/7.3.1/asm-commons-7.3.1.jar
wget https://repo1.maven.org/maven2/org/ow2/asm/asm-tree/7.3.1/asm-tree-7.3.1.jar
wget https://repo1.maven.org/maven2/org/ow2/asm/asm-util/7.3.1/asm-util-7.3.1.jar
wget https://repo1.maven.org/maven2/org/ow2/asm/asm-analysis/7.3.1/asm-analysis-7.3.1.jar

Place downloaded files into $JAVA_HOME/jmods and then run the following script to create a new Java Runtime Environment with all of the Java Modules (including the newly added modules):

jlink --module-path $JAVA_HOME/jmods/ --add-modules ALL-MODULE-PATH --output jre

Update $JAVA_HOME to point to the new JRE location.

GraalVM

GraalVM is a full virtual machine in its own right, a component of which is the Graal Script Engine, which can be dropped into existing Java Virtual Machine installations to enable it to be used in place of Nashorn. By not bundling the script runtime we (a) reduce memory footprint of our app, by deploying Graal ScriptEngine into Jira or your Java Runtime, it is then available for other apps to use, (b) we do this to not exclude other 3rd party apps from making use of the script engine as incompatibilities will arise if apps include script engines.

Java 8

Below are the steps to download and install Graal on Java 8:

• Download from https://www.graalvm.org/downloads/ (eg the GraalVM Community 20.1.0 version), the archive that is appropriate for your OS, eg (Java8) graalvm-ce-java8-linux-amd64-20.1.0.tar.gz

• Unzip the archive and enter the folder created (graalvm-ce-java8-20.1.0) and run the following, assuming $JAVA_HOME points to your JDK installation:

export DEST=$JAVA_HOME/lib/ext
cp ./jre/languages/js/graaljs.jar $DEST
cp ./jre/languages/js/icu4j.jar $DEST
cp ./jre/lib/truffle/truffle-api.jar $DEST
cp ./jre/lib/boot/graal-sdk.jar $DEST
cp ./jre/lib/boot/graaljs-scriptengine.jar $DEST

Directory $JAVA_HOME/jre/lib/ext should then look like:

...

Java 11 / Java 17

Download the Relevant files which can be downloaded by using the following:

wget https://repo1.maven.org/maven2/org/graalvm/sdk/graal-sdk/22.3.0/graal-sdk-22.3.0.jar
wget https://repo1.maven.org/maven2/com/ibm/icu/icu4j/71.1/icu4j-71.1.jar
wget https://repo1.maven.org/maven2/org/graalvm/js/js/22.3.0/js-22.3.0.jar
wget https://repo1.maven.org/maven2/org/graalvm/truffle/truffle-api/22.3.0/truffle-api-22.3.0.jar
wget https://repo1.maven.org/maven2/org/graalvm/js/js-scriptengine/22.3.0/js-scriptengine-22.3.0.jar
wget https://repo1.maven.org/maven2/org/graalvm/regex/regex/22.3.0/regex-22.3.0.jar

Place downloaded files into $JAVA_HOME/jmods and then run the following script to create a new Java Runtime Environment with all of the Java Modules (including the newly added modules):

jlink --module-path $JAVA_HOME/jmods/ --add-modules ALL-MODULE-PATH --output jre

Update $JAVA_HOME to point to the new JRE location.

Note: The jar file named “icu4j-71.1.jar” may not have the module-info.class file and will require the steps highlighted under the Adding module-info.class within the Jar file heading heading to create and include a module-info.class file within the jar file.

Error: automatic module cannot be used with jlink: com.ibm.icu from file:///usr/local/apps/jdk11_with_graal/jmods/icu4j-71.1.jar

If you an error when trying to implement Graal it is likely due to the icu4j-71.1.jar not including the module-info.class file. This causes this to not be seen as a module and as a result fails.

To solve this, use the steps below

1. Generate the Module-info class for this module using the following: jdeps --generate-module-info out icu4j-71.1.jar

2. Compile module-info.java to create module-info.class using: javac --patch-module com.ibm.icu=icu4j-71.1.jar out/com.ibm.icu/module-info.java

3. Add the module-info.class into the jar file using: jar uf icu4j-71.1.jar module-info.class

   1. Ensure that the jar file and module-info.class are within the same folder.

All Command lines:

jdeps --generate-module-info out icu4j-71.1.jar
javac --patch-module com.ibm.icu=icu4j-71.1.jar out/com.ibm.icu/module-info.java
jar uf icu4j-71.1.jar module-info.class

Install into Jira /lib

Installation of additional languages

System Administrators can make additional scripting languages available by adding their respective JSR-223 compliant JAR file into <jira_installation_directory>/lib folder. Once done, the Extensions screen of JEMH should show the language as being installed:

...

Nashorn

Java 8 / Java 11

Both Java 8 and Java 11 come with Nashorn, an engine supporting ECMAScript-262 5.1 standard. That the Jira installer ships with, and which is recommended cross platform ships with an ECMAScript implementation, so no additional configuration is strictly necessary to script JEMH Field Processors, Project Mappings, and future script-capable areas.

Java 17

Nashorn is not included within Java 17 and requires the download of the Nashorn jar file and it relevant Dependencies.

Below are the steps that are needed to install Nashorn:

• Download nashorn-core and it’s relavant files by the running the following commands within a Linux Terminal:

  • Code Block

    wget https://repo1.maven.org/maven2/org/openjdk/nashorn/nashorn-core/15.4/nashorn-core-15.4.jar wget https://repo1.maven.org/maven2/org/ow2/asm/asm/7.3.1/asm-7.3.1.jar wget https://repo1.maven.org/maven2/org/ow2/asm/asm-commons/7.3.1/asm-commons-7.3.1.jar wget https://repo1.maven.org/maven2/org/ow2/asm/asm-tree/7.3.1/asm-tree-7.3.1.jar wget https://repo1.maven.org/maven2/org/ow2/asm/asm-util/7.3.1/asm-util-7.3.1.jar

• Copy these downloaded files into your <jira_install_directory>/lib folder

Groovy

Java 8

Groovy is not included within Java 8 and requires the Groovy distribution to be downloaded and installed within the Jira instance to then be used for scripting.

Below are the steps that are needed to install Groovy:

• Download the Groovy distribution (must contain an embeddable runtime .jar file) - https://archive.apache.org/dist/groovy/3.0.0-alpha-1/distribution/apache-groovy-binary-3.0.0-alpha-1.zip

• Extract the contents of the zip file and copy ./groovy-3.0.0-alpha-1/embeddable/groovy-all-3.0.0-alpha-1.jar to your <jira_install_directory>/lib folder

Java 11 / Java 17

Groovy is not included within Java or Jira and this means that the relevant Groovy will need to be downloaded and placed within Jira.

Below are the steps to download and install Groovy:

• Download the relevant Groovy files by running the following commands within a Linux Terminal:

  • Code Block
    wget https://repo1.maven.org/maven2/org/codehaus/groovy/groovy/3.0.14/groovy-3.0.14.jar wget https://repo1.maven.org/maven2/org/codehaus/groovy/groovy-xml/3.0.14/groovy-xml-3.0.14.jar wget https://repo1.maven.org/maven2/org/codehaus/groovy/groovy-jsr223/3.0.14/groovy-jsr223-3.0.14.jar

• Copy these downloaded files into your <jira_install_directory>/lib folder

Graal

Java 8

Graal is not included within Java or Jira and this means that the relevant Graal files will need to be downloaded and placed within Jira.

Below are the steps to download and install Graal:

• Download the relevant Graal files by running the following commands within a Linux Terminal:

wget https://repo1.maven.org/maven2/org/graalvm/sdk/graal-sdk/21.2.0/graal-sdk-21.2.0.jar
wget https://repo1.maven.org/maven2/com/ibm/icu/icu4j/69.1/icu4j-69.1.jar
wget https://repo1.maven.org/maven2/org/graalvm/js/js/21.2.0/js-21.2.0.jar
wget https://repo1.maven.org/maven2/org/graalvm/truffle/truffle-api/21.2.0/truffle-api-21.2.0.jar
wget https://repo1.maven.org/maven2/org/graalvm/js/js-scriptengine/21.2.0/js-scriptengine-21.2.0.jar

• Copy these downloaded files into your <jira_install_directory>/lib folder

Java 11 / Java 17

Graal is not included within Java or Jira and this means that the relevant Graal files will need to be downloaded and placed within Jira.

Below are the steps to download and install Graal:

• Download the relevant Graal files by running the following commands within a Linux Terminal:

  • Code Block

    wget https://repo1.maven.org/maven2/org/graalvm/sdk/graal-sdk/22.3.0/graal-sdk-22.3.0.jar wget https://repo1.maven.org/maven2/com/ibm/icu/icu4j/71.1/icu4j-71.1.jar wget https://repo1.maven.org/maven2/org/graalvm/js/js/22.3.0/js-22.3.0.jar wget https://repo1.maven.org/maven2/org/graalvm/truffle/truffle-api/22.3.0/truffle-api-22.3.0.jar wget https://repo1.maven.org/maven2/org/graalvm/js/js-scriptengine/22.3.0/js-scriptengine-22.3.0.jar

• Copy these downloaded files into your <jira_install_directory>/lib folder

Known Issues

Compatibility with ScriptRunner

So, if ScriptRunner is to be used, the above method will cause ScriptRunner to not start as ScriptRunner bundles a Groovy runtime within it.  After removing the manually added JAR (if done), JEMH will happily detect ScriptRunner and use the available runtime it contains.  Again, the JEMH Extensions screen shows what runtimes have been found, from what source, here you can see ScriptRunner is listed as the source for Groovy (notice the Language version difference between the 3.0 alpha above).

...

Java-17

ScriptRunner is compatible with Jira 9.5 when running on JDK 8 or 11. However, ScriptRunner is not compatible with Java-17 and you will run into issue when attempting to use ScriptRunner. See the following page for an update on ScriptRunner compatibility with Java-17: https://productsupport.adaptavist.com/browse/SRPLAT-2179?_ga=2.30628607.1391292556.1672936005-1180316414.1664793682

...

Installation of additional languages

System Administrators can make additional scripting languages available by adding their respective JSR-223 compliant JAR file into <jira_installation_directory>/lib folder or adding directly into the JDK that is Jira/JEMH is using. Once done, the Extensions screen of JEMH should show the language as being installed:

...

Scripting Languages

Below are three Scripting Languages that we have tested and have created guides for.

Nashorn

Within Java 8/Java 11 they come with Nashorn, an engine supporting ECMAScript-262 5.1 standard. Within Java 17 this is not included by default, which means that to use Nashorn you will need to add the relevant files to the Java that is used by Jira or by adding the file to Jira-install/lib

For more info about installing Nashorn within Java 17 see: https://thepluginpeople.atlassian.net/wiki/spaces/JEMH/pages/3971612685/Installing+Nashorn+Script+Engine

Groovy

By default Groovy is not included within any Java and currently cannot be added directly into the JDK. Due to this it means that you would need to download and place the relevant files within jira-install/lib in order to use Groovy within JEMH/Jira.

For more info about installing Groovy see: Installing Groovy Script Engine

Note: If you have ScriptRunner installed, then you will not need to included the files within jira-install/lib as JEMH is able to utilise the Groovy version that is bundled within the ScriptRunner application.

Graal

By default Groovy is not included within any Java version. Due to this it means that you would need to either install Graal directly into Java or by adding the relevant files into jira-install/lib

For more info about installing Graal see: Installing Graal Script Engine

Methods of installing additional Scripting Languages

There are two possible methods of installing additional Scripting Languages.

1. Installing the files directly into the JDK - This method is to modify the JDK so that it includes the relevant files for the scripting Languages.

   1. This method only works for Nashorn and Graal.

   2. Note: Not all Jar files contain a module-info.class file, which is required to install the modules within Java. For more info about how to resolve this see the Adding module-info.class within the Jar file section below.

2. Installing the files into Jira-Install/lib - This method is to add the specific file to the lib folder of a particular Jira install. With this method it means that you do not need to modify the Java version that is used. This is done by placing the relevant Scripting files within Jira-install/lib.

   1. This method will work for Nashorn, Graal and Groovy.

Adding module-info.class within the Jar file

When adding the files directly into Java you will need to ensure that they contain a Module-info.class file as this is used to identify that the jar file can be used as a Java module. If the jar file does not contain the Module-info.class file then you would need to create this file by using the following commands. This will then allow the jar files to be used as a module within the Java Runtime Environment.

Creating module-info.java

The following terminal command will generate a module-info.java file that contains the relevant information about the jar file.

jdeps --generate-module-info out <jar_file_path>

Compile module-info.java to create module-info.class

This will compile the module-info.java file into a module-info.class which can then be used to identify the jar file as a module. Note: <module name> is identified when the above jdeps command has been run.

javac --patch-module <module_name>=<jar_file_path> out/module-info.java

Add the missing module-info.class into the jar file.

This will place the created module-info.class file into the jar file.

jar uf <jar_file_location> module-info.class

Known Issues

Compatibility with ScriptRunner

So, if ScriptRunner is to be used, the above method will cause ScriptRunner to not start as ScriptRunner bundles a Groovy runtime within it.  After removing the manually added JAR (if done), JEMH will happily detect ScriptRunner and use the available runtime it contains.  Again, the JEMH Extensions screen shows what runtimes have been found, from what source, here you can see ScriptRunner is listed as the source for Groovy (notice the Language version difference between the 3.0 alpha above).

...

Compatibility with JavaAgent:

...

Jira does not start with Java 17

When you first install using Jira 9.5.0 to 9.10.2 with Java 17 you may encounter an error when attempting to start and access Jira:

...

...

Solution

The solution to this is to add some arguments within the setenv.sh file as these arguments will allow Jira to startup when using Java 17. See the following Atlassian page for more information about the required arguments: https://confluence.atlassian.com/jiracore/java-17-runtime-opens-and-exports-arguments-1188413810.html

...