since JEMH 2.5.3 for Jira 7.7.x

Summary

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 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.

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:

  • 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:

  • 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:

  • 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

Compatibility with JavaAgent:

When using a JavaAgent you may have to specify some JVM arguments within the setenv.sh file and when these arguments are incorrect or missing then it can cause issues with the JEMH functionality. Below are some known issues we have found when the JVM arguments have been defined incorrectly.

Errors when using Scripts

When attempting to use JEMH scripting features there may be an exception that identifies that Nashorn scripting could not be found and as a result the scripting features will not work and will show the exception. When adding the JVM arguments for the JavaAgent you may use -Datlassian.org.osgi.framework.bootdelegation which is not supported by Jira. You should use -Datlassian.org.osgi.framework.bootdelegation.extra instead as this will retain the scripting functionality and will also successfully incorporate the JavaAgent within Jira. More information about this can be found on the following Atlassian page: https://confluence.atlassian.com/jirakb/adding-classes-to-osgi-boot-class-loader-bootdelegation-973483231.html

Below is the exception that is shown when -Datlassian.org.osgi.framework.bootdelegation is used:

Script Execution failure: ScriptException: An unhandled exception occurred during script execution, it could a script fault, or an attempt to use a Class not specifically cleared, see cause: 
java.lang.ClassNotFoundException: jdk.nashorn.api.scripting.NashornScriptEngineFactory not found by com.javahollic.jira.jemh-ui [222]:
javax.script.ScriptException: An unhandled exception occurred during script execution, it could a script fault, or an attempt to use a Class not specifically cleared, see cause: 
java.lang.ClassNotFoundException: jdk.nashorn.api.scripting.NashornScriptEngineFactory not found by com.javahollic.jira.jemh-ui [222]
	at com.javahollic.jira.emh.service.DefaultJEMHScriptEngineManager.runScript(DefaultJEMHScriptEngineManager.java:314)
	at com.javahollic.jira.emh.rest.ui.scriptfp.ScriptFPResource.renderPreview(ScriptFPResource.java:268)
	at java.base/jdk.internal.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
	at java.base/jdk.internal.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:62)
	at java.base/jdk.internal.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43)
	at java.base/java.lang.reflect.Method.invoke(Method.java:566)
	at com.sun.jersey.spi.container.JavaMethodInvokerFactory$1.invoke(JavaMethodInvokerFactory.java:60)
	at com.sun.jersey.server.impl.model.method.dispatch.AbstractResourceMethodDispatchProvider$ResponseOutInvoker._dispatch(AbstractResourceMethodDispatchProvider.java:205)
	at com.sun.jersey.server.impl.model.method.dispatch.ResourceJavaMethodDispatcher.dispatch(ResourceJavaMethodDispatcher.java:75)
	at com.sun.jersey.server.impl.uri.rules.HttpMethodRule.accept(HttpMethodRule.java:302)

Errors when making Profile Configuration changes

When attempting to save, export or delete your Profile you may encounter an exception which will stop these features from working. This is due to com.sun.xml.bind being missing within the JavaAgent JVM arguments and adding com.sun.xml.bind to the JavaAgent argurments will solve this issue will return the Profile configuration features.

Below is the exception that is shown when com.sun.xml.bind is not defined:

java.lang.NoClassDefFoundError: com/sun/xml/bind/DatatypeConverterImpl
	at com.javahollic.jira.emh.api.export.beans.ProfileBean_JaxbXducedAccessor_version.print(TransducedAccessor_method_Integer.java:68) [?:?]
	at com.javahollic.jira.emh.api.export.beans.ProfileBean_JaxbXducedAccessor_version.print(TransducedAccessor_method_Integer.java:66) [?:?]
	at com.sun.xml.bind.v2.runtime.property.AttributeProperty.serializeAttributes(AttributeProperty.java:101) [jaxb-impl-2.3.0.jar:2.3.0]
	at com.sun.xml.bind.v2.runtime.ClassBeanInfoImpl.serializeAttributes(ClassBeanInfoImpl.java:383) [jaxb-impl-2.3.0.jar:2.3.0]
	at com.sun.xml.bind.v2.runtime.XMLSerializer.childAsSoleContent(XMLSerializer.java:591) [jaxb-impl-2.3.0.jar:2.3.0]
	at com.sun.xml.bind.v2.runtime.ClassBeanInfoImpl.serializeRoot(ClassBeanInfoImpl.java:341) [jaxb-impl-2.3.0.jar:2.3.0]
	at com.sun.xml.bind.v2.runtime.XMLSerializer.childAsRoot(XMLSerializer.java:494) [jaxb-impl-2.3.0.jar:2.3.0]
	at com.sun.xml.bind.v2.runtime.MarshallerImpl.write(MarshallerImpl.java:328) [jaxb-impl-2.3.0.jar:2.3.0]
	at com.sun.xml.bind.v2.runtime.MarshallerImpl.marshal(MarshallerImpl.java:256) [jaxb-impl-2.3.0.jar:2.3.0]
	at javax.xml.bind.helpers.AbstractMarshallerImpl.marshal(AbstractMarshallerImpl.java:131) [jaxb-api-2.3.0.jar:2.3.0]
	at com.javahollic.jira.emh.ui.ao.export.ProfileExporter.marshallBean(ProfileExporter.java:190) [?:?]
	at com.javahollic.jira.emh.ui.ao.export.ProfileExporter.exportForDiff(ProfileExporter.java:182) [?:?]
	at com.javahollic.jira.emh.servlet.ProfileAuditingServletFilter.exportToMap(ProfileAuditingServletFilter.java:218) [?:?]

Example JavaAgent JVM arguments

Below is a working example JVM_SUPPORT_APPD_RECOMMENDED_ARGS argument that is used when configuring AppDynamics JavaAgent for Jira.

JVM_SUPPORT_APPD_RECOMMENDED_ARGS="-Datlassian.org.osgi.framework.bootdelegation.extra=META-INF.services,com.yourkit,jdk.internal.reflect,jdk.internal.reflect.*,com.singularity.*,com.jprofiler,com.jprofiler.*,org.apache.xerces,org.apache.xerces.*,org.apache.xalan,org.apache.xalan.*,sun.*,com.sun.jndi,com.icl.saxon,com.icl.saxon.*,javax.servlet,javax.servlet.*,com.sun.xml.bind,com.sun.xml.bind.*"

Jira does not start with Java 17

When you first install Jira 9.5.0 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

Below are the relevant arguments that needs to be added to the setenv.sh file:

JDK_JAVA_OPTIONS="--add-opens=java.base/java.lang=ALL-UNNAMED --add-opens=java.base/java.lang.reflect=ALL-UNNAMED --add-opens=java.base/java.util=ALL-UNNAMED --add-opens=java.base/java.util.concurrent.atomic=ALL-UNNAMED --add-opens=java.base/java.io=ALL-UNNAMED --add-opens=java.management/javax.management=ALL-UNNAMED --add-opens=java.desktop/sun.font=ALL-UNNAMED --add-opens=java.base/sun.reflect.generics.parser=ALL-UNNAMED --add-opens=jdk.management/com.sun.management.internal=ALL-UNNAMED --add-opens=java.base/java.time=ALL-UNNAMED --add-exports=java.base/sun.util.calendar=ALL-UNNAMED --add-exports=java.base/sun.security.action=ALL-UNNAMED --add-exports=java.xml/jdk.xml.internal=ALL-UNNAMED"