Wrapping a C++ library with JNI, part 2

In this series…

Introduction, outlining the general steps from starting with a C++ library to being able to build and run simple tests on some JNI wrappers;
Part 1, in which I design some simple Java classes and generate the stub wrapper code;
Part 2 (this post), in which I add just enough of the implementation to be able to do a test build;
Part 3, discussing object lifecycles in C++ and Java;
Part 4, the final episode covering a few remaining points of interest.

By the end of my previous post, I had cooked up some simple Java classes corresponding to those parts of the C++ library API that I wanted to wrap up first.

(That means as little of the API as is necessary to get a simple build and test going: I can add to it after that.)

Now I need to fill in the JNI function implementations, code up a little test program, build it, and see what ensues.

4. Write JNI function bodies

This is the point at which we need to start referring quite seriously to the JNI specification and Programmer’s Guide.

Our task is to write function bodies for the functions whose declarations have been generated by javah. The first thing we’ll need is a way to get and set the native handles we are storing in each Java class, so that we can keep track of the native object that each Java object corresponds to.

This can go in a common header, handle.h:

#ifndef _HANDLE_H_INCLUDED_
#define _HANDLE_H_INCLUDED_

jfieldID getHandleField(JNIEnv *env, jobject obj)
{
    jclass c = env->GetObjectClass(obj);
    // J is the type signature for long:
    return env->GetFieldID(c, "nativeHandle", "J");
}

template <typename T>
T *getHandle(JNIEnv *env, jobject obj)
{
    jlong handle = env->GetLongField(obj, getHandleField(env, obj));
    return reinterpret_cast<T *>(handle);
}

template <typename T>
void setHandle(JNIEnv *env, jobject obj, T *t)
{
    jlong handle = reinterpret_cast<jlong>(t);
    env->SetLongField(obj, getHandleField(env, obj), handle);
}

#endif

For PluginLoader.cpp, we start with the appropriate headers and namespaces:

#include "org_vamp_plugins_PluginLoader.h"
#include <vamp-hostsdk/PluginLoader.h>
#include "handle.h"

using Vamp::Plugin;
using Vamp::HostExt::PluginLoader;

Now we need two function implementations. We have the declarations for these already: they were generated by javah in the previous post.

One, the initialise function called from the Java class constructor, simply creates a native object and stows it in the Java object.

void
Java_org_vamp_1plugins_PluginLoader_initialise(JNIEnv *env, jobject obj)
{
    PluginLoader *inst = PluginLoader::getInstance();
    setHandle(env, obj, inst);
}

The other does the real work. Here we grab the previously stowed native object from the handle in the Java object, convert the plugin key argument from its opaque jstring type to a C string, call out to the native loadPlugin, and return the result.

jlong
Java_org_vamp_1plugins_PluginLoader_loadPluginNative(JNIEnv *env, jobject obj,
                             jstring key, jfloat rate)
{
    PluginLoader *inst = getHandle<PluginLoader>(env, obj);
    const char *kstr = env->GetStringUTFChars(key, 0);
    Plugin *p = inst->loadPlugin(kstr, rate);
    env->ReleaseStringUTFChars(key, kstr);
    return (jlong)p;
}

In contrast, Plugin.cpp is largely a cut-and-paste job:

#include "org_vamp_plugins_Plugin.h"
#include <vamp-hostsdk/Plugin.h>
#include "handle.h"

using Vamp::Plugin;
using std::string;

jstring
Java_org_vamp_1plugins_Plugin_getIdentifier(JNIEnv *env, jobject obj)
{
    Plugin *p = getHandle<Plugin>(env, obj);
    return env->NewStringUTF(p->getIdentifier().c_str());
}

jstring
Java_org_vamp_1plugins_Plugin_getName(JNIEnv *env, jobject obj)
{
    Plugin *p = getHandle<Plugin>(env, obj);
    return env->NewStringUTF(p->getName().c_str());
}

jstring
Java_org_vamp_1plugins_Plugin_getDescription(JNIEnv *env, jobject obj)
{
    Plugin *p = getHandle<Plugin>(env, obj);
    return env->NewStringUTF(p->getDescription().c_str());
}

jint
Java_org_vamp_1plugins_Plugin_getPluginVersion(JNIEnv *env, jobject obj)
{
    Plugin *p = getHandle<Plugin>(env, obj);
    return p->getPluginVersion();
}

5. Make a test program

This should be a Java program that refers only to the Java classes I’ve put together. It just needs to load a plugin using the PluginLoader class, and call some test methods on the resulting plugin.

package org.vamp_plugins;

public class test
{
    public static void main(String[] args) {

        // This is the name of a Vamp plugin we know we have installed
        String key = "vamp-example-plugins:percussiononsets";

        PluginLoader loader = PluginLoader.getInstance();

        try {
            Plugin p = loader.loadPlugin(key, 44100);
            System.out.println("identifier: " + p.getIdentifier());
            System.out.println("name: " + p.getName());
            System.out.println("description: " + p.getDescription());
            System.out.println("version: " + p.getPluginVersion());
        } catch (PluginLoader.LoadFailedException e) {
            System.out.println("Plugin load failed");
        }
    }
}

That should be enough.

6. Build and test

So, we need to compile and link our C++ wrapper implementations into a dynamic library (DLL, or shared object); and we need to build our Java test program.

How you would do this depends on the platform and development environment you’re using. For the purposes of this post, I’m using Linux and command-line tools.

So, for the C++ parts I’ll create a small Makefile:

LIBRARY := libvamp-jni.so
OBJFILES := src/PluginLoader.o src/Plugin.o
INCLUDES := -I$(JAVA_HOME)/include -I$(JAVA_HOME)/include/linux
CXXFLAGS := $(INCLUDES)

$(LIBRARY): $(OBJFILES)
    $(CXX) -shared -o $@ $^ -lvamp-hostsdk

Thus:

$ make
g++ -I/usr/lib/jvm/java-6-openjdk/include -I/usr/lib/jvm/java-6-openjdk/include/linux   -c -o src/PluginLoader.o src/PluginLoader.cpp
g++ -I/usr/lib/jvm/java-6-openjdk/include -I/usr/lib/jvm/java-6-openjdk/include/linux   -c -o src/Plugin.o src/Plugin.cpp
g++ -shared -o libvamp-jni.so src/PluginLoader.o src/Plugin.o -lvamp-hostsdk
$

Now build the Java classes and test program, and run it:

$ javac org/vamp_plugins/*.java
$ java -classpath . org.vamp_plugins.test
Exception in thread "main" java.lang.UnsatisfiedLinkError: org.vamp_plugins.PluginLoader.initialise()V
    at org.vamp_plugins.PluginLoader.initialise(Native Method)
    at org.vamp_plugins.PluginLoader.<init>(PluginLoader.java:23)
    at org.vamp_plugins.PluginLoader.getInstance(PluginLoader.java:10)
    at org.vamp_plugins.test.main(test.java:11)
$

Uh-oh. I forgot to load the JNI wrapper DLL. To make this happen, I need to add a static section to the end of the PluginLoader class:

    static {
        System.loadLibrary("vamp-jni");
    }

The JVM class loader is quite sensitive to the exact name and location of the library file.

If I supply the name vamp-jni to loadLibrary as above, then on my Linux machine the JVM will expect the library to be called libvamp-jni.so (and not, say, vamp-jni.so).

Other rules apply on other platforms.

Rebuilding and trying again:

$ javac org/vamp_plugins/*.java
$ java -classpath . org.vamp_plugins.test
identifier: percussiononsets
name: Simple Percussion Onset Detector
description: Detect percussive note onsets by identifying broadband energy rises
version: 2
$

Hurrah!

In my next post on this subject, I talk about managing the disposal of our underlying C++ objects to avoid memory leaks.

Wrapping a C++ library with JNI, part 2

In this series…

4. Write JNI function bodies

5. Make a test program

6. Build and test

Next

Published by Chris Cannam

Like this:

In this series…

4. Write JNI function bodies

5. Make a test program

6. Build and test

Next

Share this:

Like this:

Related

Published by Chris Cannam

Share this:

Like this: