Java Native Interface

JNI: Java Native Interface

Puede dar una miarada a Notas técnicas de Oracle

Introducción

Java Native Interface es una característica de Java que permite incorporar, en aplicaciones Java, código escrito en lenguaje C o C++. También es posible invocar código Java desde aplicaciones escritas en C (esta parte no es cubierta aquí).
JNI es parte de la máquina virtual Java y permite invocaciones en ambos sentidos: aplicaciones Java pueden invocar código nativo escrito en otro lenguaje y vice versa.

Figura 1: Usos de JNI, Aplicación Java más biblioteca puede correr sobre el host a través de la JVM, o una Aplicación Nativa más una biblioteca puede correr sobre el host.

Podemos usar JNI para escribir métodos nativos. Éstos tienen prototipo en Java pero su implementación es hecha en otro lenguaje. Estas implementaciones son pasadas a la máquina virtual a través de bibliotecas nativas (.dll en Windows o .so en Linux), lado izquierdo de la figura 1.

JNI también soporta una interfaz nativas que permite incrustar una implementación de la máquina virtual dentro de aplicaciones nativas (lado derecho de la Figura 1). Aplicaciones nativas pueden enlazarse con una biblioteca nativa que implementa la máquina virtual Java y luego usar la interfaz de invocación para ejecutar componentes escritas en lenguaje Java. Así es como un browser escrito en C podía ejecutar applets en una máquina virtual embebida (hace unos años los navegadores dejaron de soportar esta característica).

¿Cuándo usar JNI?

Hay dos efectos secundarios del uso de JNI: las aplicaciones que dependen de métodos nativos dejan de correr en otros ambientes. Se hace necesario re-hacer la biblioteca para cada ambiente. En segundo lugar se pierden algunas características del lenguaje, un mal comportamiento de un método nativo afecta toda la aplicación. ¿Qué pasa si el método nativo genera fuga de memoria? Como regla general se debe limitar a un mínimo el uso de métodos nativos.

Se recomienda usar JNI cuando la aplicación requiere alguna característica del host no accesible a través de la máquina virtual, cuando se desea acceder a bibliotecas nativas, o cuando deseamos dar mayor velocidad a porciones críticas del código.

Existen alternativas a JNI que implican comunicación entre procesos. Por ejemplo cuando usamos la clase Runtime para ejecutar procesos nativos en forma concurrente. También podemos comunicar procesos vía TCP/IP o usar tecnologías para distribuir objetos como la API de Java IDL (Interface Description Language). En todos estos casos se sacrifica eficiencia por la necesaria comunicación entre procesos.

Usando JNI para invocar métodos nativos

En general el uso es simple, la mayor atención se debe poner en el paso de parámetros entre el método en Java y su implementación en C. Los pasos a seguir se resumen en la Figura 2.

Figura 2: Pasos para incluir métodos nativos en una aplicación Java

A través de un ejemplo simple veremos estos pasos uno a uno.
1.- Creación de una clase que declara un método nativo, usando ejemplo HelloWorld.java

class HelloWorld {
     private native void print();  // notar uso de palabra reservada "native", su uso permite no implementar método en Java.
     public static void main(String[] args) {
         new HelloWorld().print();
     }
     static {  // asegura la carga de la biblioteca dinámica al inicio del programa.
         System.loadLibrary("HelloWorld");  // OJO: en Linux la biblioteca debe llamarse libHelloWord.so
     }
 }

2.- Compilación usando javac.

$ javac HelloWorld.java

Se genera archivo HelloWorld.class

3.- Creación del encabezado del método nativo. Notar uso de -h

$ javac -h . HelloWorld.java

Se genera archivo HelloWorld.h. En este caso su contenido esencial es:

JNIEXPORT void JNICALL Java_HelloWorld_print
  (JNIEnv *, jobject);

La implementación C del método tiene un nombre que alude al código Java de origen, nombre de la clase y nombre del método. Aún cuando el método Java no tiene argumentos, su implementación considera dos. El primer argumento de toda implementación de método nativo es un puntero a una variable tipo JNIEnv, el segundo es una referencia al objeto HelloWorld mismo (como el puntero "this" en C++).

4.- Implementar método nativo HelloWorld.c.

#include <jni.h>
#include <stdio.h>
#include "HelloWorld.h"
 
 JNIEXPORT void JNICALL  // JNIEXPORT y JNICALL corresponde a macros requeridas, en medio el tipo retornado.
 Java_HelloWorld_print(JNIEnv *env, jobject obj)
 {
     printf("Hello World!\n");
     return;
 }

Se debe incluir encabezados según la implementación que hagamos. El código es C convencional.

5.- Compilación del código C y creación de la biblioteca de ligado dinámico. Esto depende del sistema operativo nativo. En este caso será linux. Además se debe incluir los directorios donde se encuentras los archivos de encabezados requeridos por JNI. En este caso son <Ubicación de directorio Java>/include y <Ubicación de directorio Java>/include/linux.

$cc -shared -I/usr/lib/jvm/java-6-sun/include -I/usr/lib/jvm/java-6-sun/include/linux -o libHelloWorld.so HelloWorld.c
/* version 2014 , Java 7 */
$cc -shared -fPIC -I/usr/lib/jvm/java-1.7.0-openjdk-amd64/include -I/usr/lib/jvm/java-1.7.0-openjdk-amd64/include/linux -o libHelloWorld.so HelloWorld.c

/* version 2015, java version "1.7.0_91" */
$cc -shared -fPIC -I/usr/lib/jvm/java-1.7.0-openjdk-amd64/include -I/usr/lib/jvm/java-1.7.0-openjdk-amd64/include/linux -o libHelloWorld.so HelloWorld.c
Funcionó, tambien funcionó:
$cc -shared -fPIC  -I/usr/lib/jvm/java-7-openjdk-amd64/include -I/usr/lib/jvm/java-7-openjdk-amd64/include/linux  -o libHelloWorld.so HelloWorld.c

Se debe cambiar el directorio según donde esté instalado Java. Aquí funcionan ambos porque hay dos versiones de Java instaladas en este computador. -fPIC fue agregado a sugerencia del compilador.

/* version 2016, java version "1.8.0_77" */
$cc -shared -fPIC -I/home/agustin/tools/Java/jdk1.8.0_77/include -I/home/agustin/tools/Java/jdk1.8.0_77/include/linux -o libHelloWorld.so HelloWorld.c

/* version 2018 en servidor aragorn, OpenJDK 64-Bit Server VM (build 24.151-b01, mixed mode) "$javac -version" arroja "javac 1.7.0_151"*/
$cc -shared -fPIC -I/usr/lib/jvm/java-7-openjdk-amd64/include -I/usr/lib/jvm/java-7-openjdk-amd64/include/linux -o libHelloWorld.so HelloWorld.c

/* version 2021 en servidor aragorn,  "$javac -version" arroja OpenJDK 64-Bit Server VM 21.9 (build 17+35, mixed mode, sharing)*/
 cc -shared -fPIC -I/usr/lib/jvm/java-17-openjdk-17.0.0.0.35-1.rolling.el7.x86_64/include -I/usr/lib/jvm/java-17-openjdk-17.0.0.0.35-1.rolling.el7.x86_64/include/linux -o libHelloWorld.so HelloWorld.c

/* version 2022 en servidor aragorn,  "$javac -version" arroja javac 17.0.2*/
 cc -shared -fPIC -I/usr/lib/jvm/java-17-openjdk/include -I/usr/lib/jvm/java-17-openjdk/include/linux -o libHelloWorld.so HelloWorld.c

/* En general usar:*/
 cc -shared -fPIC -I${JAVA_HOME}/include -I${JAVA_HOME}/include/linux -o libHelloWorld.so HelloWorld.c

Como resultado se genera la biblioteca libHelloWorld.so

Notar la diferencia entre el nombre de la biblioteca y el nombre usado para cargarla en programa Java. Por convención como nombre de archivo se usa lib{NombreDeBiblioteca}.so Usamos .so para indicar que se trata de un Shared Object, por eso se debe usar opción -shared.

6.- Ejecución de la aplicación
Se debe poner cuidado en que la máquina virtual sepa dónde encontrar la biblioteca dinámica libHelloWorld.so. Para esto se debe configurar la variable de ambiente LD_LIBRARY_PATH. En linux esto es:

$ export LD_LIBRARY_PATH=.

Luego podemos ejecutar la aplicación:

$ java HelloWorld 
Hello World ELO330!
$

Java también permite especificar el path de la biblioteca en la línea de comando de la ejecución, en este caso poniendo la opción -Djava.library.path=. Es decir la variable java.library.path adopta la ruta del directorio actual.

$ java -Djava.library.path=. HelloWorld 
Hello World ELO330!
$

Paso de parámetros entre métodos nativos y sus implementaciones nativas

El tratamiento cambia según si los tipos de datos son primitivos u objetos. A continuación de los dos argumentos presentes en toda implementación nativa, se listan los parámetros declarados en el método nativo. Cuando son tipos básicos éstos son reflejados en C con tipos equivalentes definidos en jni.h. El listado de equivalencias se puede ver aquí.

Consideremos el ejemplo Prompt.java:

class Prompt {
    // native method that prints a prompt and reads a line
  private native String getLine(String prompt, int i);
 
  public static void main(String args[]) {
    int i = 20;  // sólo para agregar otro tipo de dato
    Prompt p = new Prompt();
    String input = p.getLine("Type a line: ", i);
    System.out.println("User typed: " + input);
  }
  static {
    System.loadLibrary("Prompt");
  }
}

Luego de compilar y correr javah, se genera el archivo Prompt.h, cuyo contenido fundamental es:

JNIEXPORT jstring JNICALL Java_Prompt_getLine
  (JNIEnv *, jobject, jstring, jint);

String son objetos en Java, en C corresponden a char *. La implementación del método nativo está en Prompt.c. Para acceder adecuadamente a este objeto debemos hacer una conversión.

#include <jni.h>
#include <stdio.h>
#include "Prompt.h"

JNIEXPORT jstring JNICALL 
Java_Prompt_getLine(JNIEnv *env, jobject obj, jstring prompt, jint i)
{
  char buf[128];
  const jbyte *str;
  str = (*env)->GetStringUTFChars(env, prompt, NULL);
  if (str == NULL) {
    return NULL; /* OutOfMemoryError already thrown */
  }
  printf("Number:%d, %s", i, str);
  (*env)->ReleaseStringUTFChars(env, prompt, str);
    /* We assume here that the user does not type more than
     * 127 characters */
  gets(buf);
  return (*env)->NewStringUTF(env, buf);
}

A través del puntero env es posible acceder a funciones de JNI para efectuar conversiones. En esta conversión GetStringUTFChars solicita memoria para str. Una vez finalizado el uso de str, debemos retornar el espacio de memoria a través de ReleaseStringUTFChars.
La compilación y ejecución del código es similar al ejemplo previo HelloWorld.java.