Using Java on IBM i

Java virtual machine (JVM) is where your Java programs run. JVM runs on servers , clients and web browsers when you try to run a Java applet.

IBM i Server Side Java

On IBM i server you can install JDK to create and run Java programs. You can install either IBM Developer Kit for Java or Classic Java Development Kit(JDK) depending upon version of IBM i. JVM is included as part of both these JDK. The JDK also provides Java Invocation API that allows IBM i native programs to spin JVM. IBM i native programs can be externalized using Web Services and invoked over https.

Installing multiple JDK on IBM i enables it to run multiple JVM simultaneously however only one JVM can run per job. Jobs can be setup to use specific JVM.

Client Side Java

You can build Java programs on a client machine and invoke them to interface with IBM i. On Clients you have option to use JDK  from IBM, Oracle or Open source community. Client application sometimes is shipped with specific version of Java embedded in it.

Classic JDK v/s IBM Technology for Java

IBM Developer Kit for java is a.k.a. IBM technology for Java (IT4J). This JDK includes both 32-bit and 64 bit JVM. Classic JDK has 64 bit JVM only.

Starting IBM i 7.1, IT4J is the only available JVM. OS400 V5R3 and older has Classic JDK only. i5/OS V5R4 and IBM i 6.1 can have Classic JDK or IT4J installed. With both Classic JDK and IT4J installed , applications should be explicitly use correct JDK  and not rely on system default JDK. Refer to the URL for a list of IBM JDK version that can be installed on various IBM i version & release.

JDK support is included as part of IBM i software maintenance agreements(SWMA) and SWMA support extension. Classic JDK is deprecated and support from IBM is available on best effort basis only.

Application & JDK Consideration

Server side applications should use or migrate to IBM Technology for Java owing to its superior performance and reduced resource utilization compared to the Classic JDK. Applications that require more than 1000 threads or Java object heap size larger than 3 gigabytes must use 64-bit JDK. 

Default JDK on i5/OS and IBM i

The default JDK chosen follows an order of preference when IBM i has multiple JDK installed. If you install only one JDK , then it is the default JDK. Table 1 list IBM default JDK version for different IBM i version and release.

Application and JVM requirement.

Your application may require specific JVM version and bit level which differ from IBM i system default JVM. System default JVM applies to all JVM unless overridden. It is recommend that application uses IT4J and preferably JDK 8.0 wherever possible.

To use specific IT4J JVM you must add environment variable JAVA_HOME with its value set to absolute path of the JVM required. Once added you can invoke your Java programs. For Classic JDK you should not use JAVA_HOME environment variable, instead use java.version property and set it to the path of required JVM.

At a system wide level do not set JAVA_HOME environment variable or java.version property. It is highly recommended to set  the JDK version and bit level required by your application by setting the JAVA_HOME environment variable at the job scope or by setting java.version property at user profile or job's user identity level.

Java System Properties

When JVM start it takes its attributes from Java system properties. These properties together provides JVM environment in which your Java programs run. There are a number of ways in which JVM environment can be set up on different platforms. You can use command line option across all platforms to set the properties. Additionally in i5/OS and IBM i you can also create the file  SystemDefault.properties and specify the properties for all JVM. The file does not exists by default. This file can be created for all JVM in /QIBM/UserData/Java400/ directory or for specific IBM i user profile  in his profile home directory. Starting i5/OS V5R4 a separate file can also be used to specify JVM properties. Each line in this file specifies one Java system property or Java option. Both IT4J and Classic JDK uses this file to set JVM properties at run time. 

How to use a specific IT4J JDK

Default JDK at IBM i 7.4 is 5770JV1 option 17. Absolute path for this JDK is /QOpenSys/QIBM/ProdData/JavaVM/jdk80/64bit. To change the default JDK version to 5770JV1 option 16 you can take one of the following approach depending upon how you invoke your Java program.

• Set environment variable from IBM i command line. 
  • System wide ( Not Recommended )
    • ADDENVVAR ENVVAR(JAVA_HOME) VALUE('/QOpenSys/QIBM/ProdData/JavaVM/jdk80/32bit’) LEVEL(*SYS) REPLACE(*YES)
    • Note : The parameter value is case sensitive.
  • Interactively for individual user
    • ADDENVVAR ENVVAR(JAVA_HOME) VALUE('/QOpenSys/QIBM/ProdData/JavaVM/jdk80/32bit') LEVEL(*JOB) REPLACE(*YES)
• As part of program running interactively or in batch.
  • At the beginning of the program add the statement  ADDENVVAR ENVVAR(JAVA_HOME) VALUE('/QOpenSys/QIBM/ProdData/JavaVM/jdk80/32bit') LEVEL(*JOB) REPLACE(*YES)
• Invoke shell and use export to set environment variable
  • STRQSH
  • export -s JAVA_HOME=/QOpenSys/QIBM/ProThanks for submitting the form.dData/JavaVM/jdk80/32bit
• Set environment variable when you invoke the shell
  
  • Create a .profile file in your home directory.
  • Add the command to the file
    • export -s JAVA_HOME=/QOpenSys/QIBM/ProdData/JavaVM/jdk80/32bit
    • Save and exit
• Set environment variable for all QShell users invoking JVM ( Not Recommended )
  • Create a .profile file in /etc directory.
  • Add the command to the file
    • export -s JAVA_HOME=/QOpenSys/QIBM/ProdData/JavaVM/jdk80/32bit

How to use specific Classic JDK

When using Classic JDK, default JDK version can be changed by creating the property file SystemDefault.properties. This file sets the default system properties for all Java virtual machines that run on your IBM i.

Properties specified in /QIBM/UserData/Java400/SystemDefault.properties can be overridden for a specific user or job user identity by creating this file in the user's home directory. If JVM is already active you must end and restart it for the desired version. It is not recommended to change default JDK at system wide level. However when required follow the steps below.

• STRQSH
• touch -C 819 /QIBM/UserData/Java400/SystemDefault.properties
• EDTF STMF('/QIBM/UserData/Java400/SystemDefault.properties')
• Add the property java.version=V.R , where V.R can be 1.3,1.4,1.5 or 1.6 only. 
• Note : Ensure that java.version property in the file is not having a space preceding "J"
• Press F3 twice to save and exit.

Precedence of Java system properties

IBM i and the JVM determine the values for Java system properties by using the following order of precedence:

1. Command line -D option for properties or JNI invocation API

2. QIBM_JAVA_PROPERTIES_FILE environment variable

3. user.home SystemDefault.properties file

4. /QIBM/UserData/Java400/SystemDefault.properties

JVM Property Alert.

Lastly be aware that java.home is a property valid in Oracle JDK but not for IBM i JDK. You must not add it in SystemDefault.properties. Instead use JAVA_HOME environment variable to set required JDK when using IT4J.

Need help with installing, upgrading Java on your IBMI (AS/400)?