GTMJI - GT.M Java Interface Plug-in

GTMJI - GT.M Java Interface Plug-In

Overview

GTMJI provides a mechanism to call-in to GTM from Java application code, and to call out from GT.M to Java application code. GTMJI requires a minimum GT.M release of V6.0-002 and is supported on Linux on x86 and x86_64, and AIX. The following table lists the platforms and Java distributions on which FIS tested the GTMJI plug-in:

Although GTMJI may as well work on other combinations of platforms and Java implementations, the above are the platforms on which GTMJI is tested. Versions of each platform are those on which your GT.M is supported per the release notes for that release.

Installation

GTMJI is a source code distribution. GTMJI comes with a Makefile that you can use with GNU Make to build, test, install, and uninstall the package. You need to have GNU Make, C compiler, and a JDK environment (for the JNI [https://en.wikipedia.org/wiki/Java_Native_Interface components] components). On some platforms, GNU make may be accessed with the command gmake, not make. You can build and test GTMJI as a normal (non-root) user, and then as root install it as a GT.M plug-in. The targets in Makefile that are intended for external use are:

• all: creates libgtmj2m.so and libgtmm2j.so (shared libraries of C code that acts as a gateway for Java call-ins and call-outs, respectively) and gtmji.jar (a Java archive containing GTMJI type wrapper and thread management classes).
• clean: deletes all files created as a result of running the test and/or all target.
• install: executed as root, installs GTMJI as a plug-in under the GT.M installation directory.
• install-test: executed as root, ensures the operation of GTMJI after building and installation. Messages “GTMJI-INSTALL-SUCCESS: Call-ins test succeeded.” and “GTMJI-INSTALL-SUCCESS: Call-outs test succeeded.” confirm successful installation. If you are using UTF-8, make sure to set the environment; two additional GTMJI-INSTALL-SUCCESS messages should be printed.
• test: ensures the operation of GTMJI after building and before installation. As with the install-test target, “GTMJI-INSTALL-SUCCESS: Call-ins test succeeded.” and “GTMJI-INSTALL-SUCCESS: Call-outs test succeeded.” messages should appear. If you are using UTF-8, make sure to set the environment; two additional GTMJI-INSTALL-SUCCESS messages should be printed.
• uninstall: executed as root, removes the installed plug-in from under the GT.M installation directory.

The following targets also exist but are intended for use within the Makefile rather than for external invocation: libgtmj2m.so, libgtmm2j.so, gtmji.jar, $(PLUGINDIR)/libgtmj2m.so, $(PLUGINDIR)/libgtmm2j.so, $(PLUGINDIR)/gtmji.jar, $(UTFPLUGINDIR)/libgtmj2m.so, $(UTFPLUGINDIR)/libgtmm2j.so, and $(UTFPLUGINDIR)/gtmji.jar.

To run the Makefile, set the following environment variables:

• gtm_dist: Installation directory of GT.M that contains libgtmshr.so and such include files as gtm_common_defs.h and gtmxc_types.h. If you plan to install GTMJI for multiple GT.M versions, please clean the build each time, since both gtmxc_types.h and gtm_common_defs.h are included from $gtm_dist to build the shared library.

• JAVA_HOME: Top directory of your Java installation, such as /usr/lib/jvm/jdk1.6.0_25.

• JAVA_SO_HOME: Directory that contains libjava.so; typically,

  • AIX: $JAVA_HOME/jre/lib/ppc64
  • Linux: $JAVA_HOME/jre/lib/amd64, $JAVA_HOME/jre/lib/i386, or $JAVA_HOME/jre/lib/i686

• JVM_SO_HOME: Directory that contains libjvm.so; typically,

  • AIX: $JAVA_HOME/jre/lib/ppc64/j9vm
  • Linux: $JAVA_HOME/jre/lib/amd64/server, $JAVA_HOME/jre/lib/i386/server, or $JAVA_HOME/jre/lib/i686/server

Note that if you also have a GT.M installation with UTF-8 support (that is, GT.M executables under $gtm_dist/utf8), then you might need to configure a few additional environment variables for targets that run GTMJI tests, such as test and install-test. Setting gtm_icu_version suffices in most situations.

The steps for a typical GTMJI installation are as follows:

1. Set gtm_dist, JAVA_HOME, JAVA_SO_HOME, and JVM_SO_HOME environment variables.
2. Run make all.
3. Run make test. When make test completes, two (four if you have a UTF-8-enabled installation) “GTMJI-INSTALL-SUCCESS …” messages get displayed.
4. Run make install.
5. Run make install-test. When make install-test completes, two (four if you have a UTF-8-enabled installation) “GTMJI-INSTALL-SUCCESS …” messages get displayed.
6. Run make clean to remove all temporary GTMJI files created in the current directory by other make commands.