Metagnostic
home

JNIPort for Dolphin Smalltalk

Overview

Contents

Players

Layers

Examples

Configuration

InFAQ

Changes

Licence


Back to Goodies

The Java Native Interface (JNI)

JNI, the “Java Native Interface”, is the API by which programs written in C, or a similar language, can interact with a Java runtime. Dolphin's external interfacing feature is able to use the JNI API and the whole of JNIPort is built on it.

The JNI specification is included in the J2SDK documentation; by all means read it (if you don't know it already) but be warned: JNI is one of the most unpleasant APIs I've ever worked with. To be fair, a lot of that is because Sun were in the difficult position of specifying a low-level interface to a garbage collected virtual machine without constraining the implementation of the VM or garbage collector. On the other hand, I don't doubt that much of the difficulty is because the JNI API was rushed and poorly thought-out.

I have no intention of writing an introduction to JNI; if you are interested then you may like to look at the JNI trail in the Java tutorial. Sun have also put the JNI book online.

The rest of this section assumes that you know both JNI and Dolphin's external interfacing (which may be an unrealistic expectation, I admit).

The package 'CU JNI' contains ExternalStructure subclasses corresponding to the JNI structures:

  • JavaVMInitArgs
  • JavaVMOption
  • JNINativeMethod
  • jvalue (and arrays thereof)

plus the two vtable-like structures:

  • JavaVM
  • JNIEnv

which, luckily, are close enough to the layout of a real COM or C++ object for Dolphin to be able to handle them without trouble.

By the way, don't confuse the JavaVM structure with the JNIPort JVM object; the JVM object is of a different class (JVM!) and contains a JavaVM object. The name “JavaVM” is just a poor choice by Sun.

The package also contains an ExternalLibrary subclass that exposes the functions exported by the Java runtime DLL. In fact there are several such libraries, one for each kind of Java runtime I've tried. These differ only in the way that they locate the Java DLL at runtime.

The package also includes ExternalAddress subclasses corresponding to the various kinds of opaque pointer used by JNI. Most importantly the “local” and “global” references to Java objects.

The idea of this package is to provide only a very thin layer around raw JNI. It is important (should you use this layer without the rest of JNIPort) that you realise that it does not manage the lifetime of references to Java objects automatically, you have to track references yourself and release them explicitly.

The package does go a little beyond the raw JNI specification. It provides a set of subclasses of JNIReference corresponding to both the local and global flavours of the “typed” references (jclass, jarray, jstring, and so on). It also provides type-preserving conversions between local and global references.

The central objects at this level are the JNIEnv “pointers”. A JNIEnv is like a COM object or a pointer to a C++ object; it has no (public) data, just a load of methods (about 300) that are the meat of the JNI API. This package exposes the methods as Smalltalk methods. The way that JNI works requires the programmer to check for errors/exceptions after each step, so the JNIEnv class also has checked versions of all the methods.

For two simple (Ha!) examples of raw JNI programming using this package, see JNIReference>>toString: and JNIReference>>equals:jniEnv:. Of course, the rest of JNIPort contains many more examples.


Copyright © Chris Uppal, 2003-2005

Java, JNI (probably), JVM (possibly), and God knows what else, are trademarks of Sun Microsystems, Inc.