Skip to main content

IBM Systems  >  System z  >  Software  >  

Migrating JNI applications to Java 2 Technology Edition for OS/390,
SDK 1.3

 

This information about the IBM Developer Kit for OS/390, Java 2 Technology Edition will help you if you are currently using the Java Native Interface (JNI) with Java for OS/390 at the JDK 1.1.6 or JDK 1.1.8 level and you want to migrate to Java 2 Technology Edition for OS/390 at the SDK 1.3 level.

The information here relates specifically to IBM's Java products for OS/390. For general information on migrating JNI applications to Java 2, see Sun's web page JNI Enhancements in Java 2 SDK 1.2.

Related information:

Definition of compatibility

Two terms for compatibility are used here:

  • Binary compatibility
    This means the ability to use your existing JNI application without first needing to rebuild it.  Rebuilding means compiling, linking or packaging the application.  If your application is binary compatible you can use it with SDK 1.3 without making any changes other than to the runtime environment.  Examples of runtime changes are to path settings and environment variables.
  • Source compatibility
    This means the ability to use your existing JNI application without first needing to change the source code of the application or the scripts required to build it.  If your application is source compatible you can use it with SDK 1.3 without changing it or your build scripts in any way.  If it is not also binary compatible then you do have to rebuild it before you can use it with SDK 1.3.  You might also need to change its runtime environment.

Compatibility between prior releases

A knowledge of the structure of prior releases of Java on OS/390 is important to understand the migration path to SDK 1.3.  JDK 1.1.6 and JDK 1.1.8 were shipped in three flavors or builds according to the releases of OS/390 each was suitable for.  In addition, the build targeted for V2R6 and above contained two versions of most JDK libraries, one to exploit new hardware and operating system features and one to provide compatibility with older equipment.  The various builds are summarised in the following table:

JDK 1.1 builds
Build For OS/390 release Implementation of data types
Java double, float Java long
R01 V1R1, V1R2, V1R3 Emulated Emulated
R04 V2R4, V2R5 Emulated Emulated
R06 V2R6 and later Emulated Emulated
R06 BFP V2R6 and later Exploits IEEE754 native floating point support available on G5 and later hardware from V2R6 onwards Implemented as C/C++ type long long available from V2R6 onwards

A JNI application is built for a given JDK build.  Information on building a JNI application for JDK 1.1 is contained in the file jni_example/jni_oe.html shipped with JDK 1.1.6 and JDK 1.1.8.

A JNI application is fully binary and source compatible when used with a build matching that it was built for.  For example, an application built with JDK 1.1.6 R04 operates unchanged with JDK 1.1.8 R04, and an application built with JDK 1.1.6 R06 BFP operates unchanged with JDK 1.1.8 R06 BFP.

A JNI application is source compatible and upwardly binary compatible if built for R01, R04 or R06 and used with another in this set.  For example, an application built with JDK 1.1.6 R01 operates unchanged with JDK 1.1.8 R04.  Conversely, an application built with JDK 1.1.8 R04 requires rebuilding to operate with JDK 1.1.6 R01 but does not require source code or build script changes.

A JNI application built for R06 BFP is neither binary compatible nor source compatible with any other build.  For example, an application built with JDK 1.1.6 R06 BFP requires changes to the build scripts and rebuilding to operate with JDK 1.1.8 R06.

These statements are summarised in the following table:

JDK 1.1 binary and source compatibility
If JNI application is built for... ...and used with... ...then it is...
R01, R04 or R06 same binary and source compatible
another in same set source compatible, upwardly binary compatible
R06 BFP incompatible
R06 BFP same binary and source compatible
any other incompatible

Migrating from prior releases to SDK 1.3

In contrast to prior releases SDK 1.3 is shipped in a single build which is suitable for OS/390 V2R8 and higher.  Releases prior to V2R8 are not supported.  Only the BFP format of floating point implementation is provided so there is just a single library set.  On systems that do not have IEEE754 native floating point support, floating point operations are emulated in the Language Environment (LE) layer of the operating system.

A JNI application built for JDK 1.1 can be both binary and source compatible with SDK 1.3 if certain conditions are met.  But the most general case is that a rebuild of the application is required.  In addition some migration paths require changes to the build scripts and an optional change to the source code.  The degree of change required depends on several factors:

  • Does the application use Java long, double or float?
  • Does the application exploit the macros and functions provided in float_md.h and longlong_md.h?
  • Is the application built for BFP or floating point emulation (non-BFP)?
  • Does the application use the JNI invocation API?
  • Does the application use the JNI helper functions (JNI_a2e_vsprintf and the string conversion functions)?

The following tables summarise binary and source compatibility under all conditions. They also give the exact changes you need to make to your source code and build scripts.  A further table details the minimal changes required to the runtime environment.  For a concise description of building a JNI application under SDK 1.3 see Using JNI with Java 2 Technology Edition for OS/390, SDK 1.3.

JDK 1.1 to SDK 1.3 binary compatibility
JNI application type Needs to be rebuilt?
Uses native methods Yes if...
 
The application uses Java long, double or float and exploits the macros and functions provided in longlong_md.h and float_md.h Some functions are replaced by macros, and some Java virtual machine entry points have moved
The application uses Java long, double or float and is built for non-BFP Although the storage representations of the types are the same in non-BFP and BFP, the conventions used by the runtime environment for passing the types differ
The application uses the JNI helper functions The entry points of the functions have moved.

Otherwise no
Uses the Invocation API Yes
JDK 1.1 to SDK 1.3 source compatibility (1)
JNI application type Needs source code change?
Uses native methods Optional if...
 
The application uses Java long and exploits the macros and functions provided in longlong_md.h The macros and functions are now built-in but an empty version of longlong_md.h is supplied to maintain source compatibility
The application uses Java double or float and exploits the macros and functions provided in float_md.h The macros and functions are now built-in but an empty version of float_md.h is supplied to maintain source compatibility
The application uses the alternative JNI native type float_t, double_t or int64_t The types are now deprecated and jfloat, jdouble or jlong should be used instead

Mandatory if...
 

The application uses the system property os390.ieee754 to determine whether BFP or non-BFP is in effect and load a corresponding version of an application native library The property is no longer set.  A single set of application native libraries should be built.
The application is built for non-BFP and uses Java double or float and ESA/390 native double or float in the same module The change to BFP format requires that the -W "c,float(ieee)" compiler option be specified for those source modules that work with Java double or float.  This is incompatible with those parts that use ESA/390 native double or float.  They must be separated and not compiled with this option.

Otherwise no
Uses the Invocation API Same as above plus...

Mandatory if...
 

The application explicitly loads the Java virtual machine DLL The name of the DLL was libjava.so or libjavaBFP.so, is now libjvm.so [ note 1]
The application is built for BFP and explicitly loads its native library rather than relying on the Java virtual machine to load it The name of the native library to load is different - it does not end with BFP.  The Java virtual machine no longer appends this string to the name it expects to find.
The application uses the JNI helper function JNI_a2e_vsprintf The function prototype has moved to jni_convert.h.

There are additional cross-platform compatibility issues imposed by Invocation API differences in Java 2. For example:

  1. In JDK 1.1 the second argument to JNI_CreateJavaVM has type pointer to JNIEnv * whereas in Java 2 it is pointer to void *.   A change to the source code is necessary to avoid a compile warning.
  2. Java 2 supports both "1.1 style" and "1.2 style" initialisation arguments.   There is more to this than just the format:  which style you choose has important implications for the semantics of the Java environment.  1.2 style gives you access to all features of the Java 2 platform.  1.1 style supports programming techniques that are incompatible with some Java 2 platform features (does not support the extension mechanism, uses the bootstrap class loader for all classes, classes loaded from the class path do not have a protection domain and therefore have all permissions).  The differences are the same as between the java and oldjava commands.

For more information see Sun's web pages JNI Enhancements in Java 2 SDK 1.2 and Java 2 SDK Tools and Utilities - java.
JDK 1.1 to SDK 1.3 source compatibility (2)
JNI application type Needs build script change?
Uses native methods Yes
 
All applications Include path was <hlq>J1.1/include, is now <hlq>/J1.3/include

Compiler option -DNEEDSLONGLONG is obsolete

Compile command must specify -W "c,langlvl(extended)" to enable support for C/C++ type long long (omitting it will cause a compiler syntax error)

Compile command should specify -W "c,float(ieee)" to enable support for IEEE754-compliant types double and float (omitting it will not cause a compiler error but will make the results of operations on Java doubles and floats meaningless)

Path for the JNI side deck was <hlq>/J1.1/lib/mvs/native_threads, is now <hlq>/J1.3/bin/classic
Applications built for non-BFP Compiler option -DNEEDSIEEE754 is obsolete

JNI side deck was libjava.x, is now libjvm.x [ note 1]
Applications built for BFP  Compiler option -DIBM_IEEE_HSP is obsolete

JNI side deck was libjavaBFP.x, is now libjvm.x

The name of the application native library must drop the trailing BFP because the Java virtual machine no longer appends this string to the name it expects to find
Applications building dual native libraries for BFP and non-BFP Only the BFP libraries should now be built
Applications using the JNI string conversion functions The string conversion functions are now built into the Java virtual machine so jni_convert.o and libJNIConvert.x are no longer shipped. References to them should be replaced with libjvm.x
Uses the Invocation API Yes, same as above
JDK 1.1 to SDK 1.3 runtime environment changes
JNI application type Needs environment change?
Uses native methods No
Uses the Invocation API Yes
 
All applications Library path for the Java virtual machine was <hlq>/J1.1/lib/mvs/native_threads, is now <hlq>/J1.3/bin:<hlq>/J1.3/bin/classic

Environment variable JAVA_IEEE754 (for forcing the JDK to load the non-BFP library set even on a BFP machine) is obsolete
Applications using 1.1 style initialisation arguments Path to the JDK system classes was <hlq>/J1.1/lib/classes.zip, is now <hlq>/J1.3/lib/rt.jar
Applications using 1.2 style initialisation arguments Practice of adding the JDK system classes to the class path is obsolete

Notes

  1. The name change of the Java virtual machine DLL from libjava.so to libjvm.so was imposed by Sun in Java 2 SDK 1.2 and is common to all implementations of Java 2.  In the Java 2 SDK v1.2 and JNI FAQ Sun wrote:  "In the Java 2 Runtime Environment v1.2, jvm.dll [=libjvm.so] takes the role of javai.dll [=libjava.so] in JDK 1.1.  The JNI invocation functions such as JNI_CreateJavaVM, and old NMI methods such as makeJavaString are now present in jvm.dll.  We understand that this an issue for customers with pre-existing shared libraries and applications that are linked against javai.dll.  One workaround, if you have the object files, is to re-link the application."