After an upgrade to SP5 from 5.3 SP3 we started getting regular crashes of Weblogic, which was hosting the WDK apps. After looking at various crashes we were still struggling to find something common among the crash instances. Finally, we discovered that every crash that left a dump file showed a stack trace of expression evaluation for conditional value assistance. It didn't indicate the expression it was evaluating but it did show that it was going outside the JVM via JNI and crashing there.

Fast forwarding to the EMC response. They had encountered something similar in another case and the recommendation was to migrate docbasic expressions to Java implementation! Huh?

Well, Appendix B of DQL Reference describes this process in a reasonable detail. Apparently, for evaluating the conditions in value assistance (among other things) DFC uses a DLL which is a Docbasic runtime. However, it is possible to provide a Java implementation for expressions so that the need for JNI calls can be obviated. The methods available for this purpose are called dmc_MigrateDbExprsToJava and dmc_MigrateDbExprsToJavaForType.

If you follow this documentation in conjunction with the object reference it will all begin to make sense. The only additional worthwhile thing to know, and probably the biggest value addition offered by this post, is the following.

Once you have created the Java implementations for Docbasic expressions, you can disable and enable the use of these Java implementations. However, when we tried to disable the use of these expressions using dmc_SetJavaExprEnabled, the command failed. When we got to the logs, we found various errors but one caught our eye. It complained about missing a parameter named "enabled". However, the reference names the parameter as "enable" (which turns out to be incorrect). Once we corrected the parameter name to be "enabled" in the command line, it started to work as expected.

In order to troubleshoot this issue, we wrote a small DFC client that iterated through docbase objects and exercised all the conditions present in value assistance. We embedded this client in a JSP so that we could reproduce it in the environment that was encountering the problem. Using this tool, we were able to reproduce the problem consistently. The tests following the change have been encouraging since we haven't seen any more crashes.

Introducción 

Este documento muestra como construir un Hello World usando JNI.

JNI es la sigla de "Java Native Interface" y como su nombre lo indica, es una interfaz que permite llamar a funciones compiladas en el código nativo de la máquina en que se está ejecutando el programa.

Para esto, primero debemos escribir la función en algún lenguaje y compilarla como una librería del entorno en el que vamos a llamarla. (Por ejemplo en Windows, podemos compilar una DLL en Visual C++ con las funciones que queremos llamar desde Java).

Hello JNI World

Antes que nada, si queremos usar JNI tenemos que poder compilar un ejemplo simple y verificar como funciona:

Mundo Java

Se empieza por crear la clase Java definiendo la interfaz de comunicación con la futura DLL.

import java.util.*;

class HelloWorld {

//Native method declaration

  native void sayHello(String name);

//Load the library

  static {

    System.loadLibrary("helloworld");

  }

  public static void main(String args[]) {

//Create class instance

    HelloWorld hello =new HelloWorld();

//Call native method

    hello.sayHello("Nerdy");

  }

}

Compilar la clase con el comando "javac HelloWorld.java"

Luego ejecutar el comando "javah HelloWorld". Se generará un header HelloWorld.h que contiene la descripción de los métodos que debería implementar la libería dll:

/* DO NOT EDIT THIS FILE - it is machine generated */

#include <jni.h>

/* Header for class HelloWorld */

#ifndef _Included_HelloWorld

#define _Included_HelloWorld

#ifdef __cplusplus

extern "C" {

#endif

/*

 * Class:     HelloWorld

 * Method:    sayHello

 * Signature: (Ljava/lang/String;)V

 */

JNIEXPORT void JNICALL Java_HelloWorld_sayHello

  (JNIEnv *, jobject, jstring);

#ifdef __cplusplus

}

#endif

#endif

Mundo C

Cómo paso siguiente vamos a implementar la función en C++ (en realidad en C, porque no vamos a crear ninguna clase) para Visual C++ de esta manera:

#include <jni.h>

#include "HelloWorld.h"

#include <stdio.h>

JNIEXPORT void JNICALL 

Java_HelloWorld_sayHello(JNIEnv *env, jobject obj, jstring name)

{

  jboolean iscopy;

  const char *charsname = (*env)->GetStringUTFChars(

                env, name, &iscopy);

  printf("Hello ");

  printf(charsname);

  printf(", this is your first JNI library\n");

  return;

}

Algunas observaciones:

 * #include <jni.h>: Esta línea es necesaria para poder usar las funciones de JNI dentro de la DLL. JNI implementa "métodos" y constantes para comunicarse con Java, por ejemplo para convertir tipos de datos. 

 * JNIEXPORT void JNICALL: Esta línea es un ejemplo del uso de definiciones JNI para código C, indica como se exporta la función en la dll y el método de llamada a la misma. Lo único que nos importa es que tiene que ir así.

 * JNIEnv *env: Este es un puntero al objeto environment de JNI. Con los métodos de este objeto hacemos por ejemplo transformaciones de formato de los parámetros. Además es un handler al thread actual de la máquina virtual de java.

 * jobject obj : Esta es la referencia al método de Java que llama a la función. Supongo que sirve para hacer recursión. Si el método que hace la llamada es estático viene un jclass.

 * jstring: La clase String de Java no existe en C++, hay que hacer una conversión para poder usar los datos. Esto se hace en la línea const char *charsname = (*env)->GetStringUTFChars(env, name, &iscopy); donde *charsname es un puntero a un char que en realidad apunta a una cadena de caracteres (ver pointers en C) y el operador -> es como el punto "." en Java pero para objetos referenciados por puntero (el tipo env de era JNIEnv* y por eso hay que usarlo).

Por último, una vez está escrito el código hay que compilar. La forma más fácil de hacer esto (si la DLL está compuesta de un único archivo .c) es compilarla directamente desde linea de comandos. Para eso hay que abrir "Simbolo de Sistema de Visual Studio". Esto despliega una nostálgica ventana de DOS donde se puede ejecutar el comando para generar la librería. No lo hacemos con la línea de comandos común y corriente (ejecutando cmd) porque haría falta setear muchas variables de entorno de Visual Studio.

Lo mejor para compilar es meter el comando dentro de un archivo .bat para poder usar la variable de entorno %JAVA_HOME% que apunta al directorio del JDK. Dentro de este la carpeta include contiene el archivo "jni.h" al que se hace referencia desde el código de la DLL. Luego desde la consola de Visual Studio llamamos a nuestro script (por ejemplo makeDLL.bat).

El comando dentro del archivo makeDLL.bat es:

cl -I%JAVA_HOME%/include -I%JAVA_HOME%/include/win32 -LD HelloWorld.c -Fehelloworld.dll

La opción -I incluye al directorio para buscar los includes, -LD indica el archivo fuente con el que creará una DLL y por último -Fe indica el nombre del archivo de salida.

Esto generará el archivo HelloWorld.dll y sus correspondientes HelloWorld.obj y HelloWorld.lib que no nos sirven para nada y se pueden borrar.

Finalmente, para probar el programa ejecutamos "java HelloWorld" y obtenemos la siguiente salida:

Hello Nerdy, this is your first JNI library

Conclusión

A esta altura creo que se habrán dado cuenta de que JNI no es fácil. No es algo trivial (sobre todo si piensan en objetos complejos y threads). 

Este fue uno de los HelloWorld más complicados que ví en mi vida. Por suerte hay bastante buena documentación en Internet:

 * Introductoria: http://java.sun.com/developer/onlineTraining/Programming/JDCBook/jni.html de acá saqué en parte las cosas para hacer el HelloWorld

 * Más completo: Java Native Interface: Programmer's Guide and Specification. Se puede bajar el libro en html o pdf o verlo en línea.

 * Especificación completa: http://java.sun.com/javase/6/docs/technotes/guides/jni/index.html.

Septiembre:

sabado 6:

Culto compañerismo
lugar: en la iglesia
hora: 6.30 p.m.
organizado por: Katy
objetivo: integracion de grupos de amistad juvenil

sabado 13:

Paseo a la alberca
lugar: pendiente
hora: 10 am. a 2 pm.

domingo 14:

Celebracion de noche mexicana
lugar: en la iglesia
objetivo: trabajo en GAJ

lunes 15 y martes 16:

Congreso de adolescentes interzonas valles y frailesca
lugar: villas el Buen Pastor
costo: 150 pesos por persona

sabado 20:

Retiro espiritual
lugar: el Eden
hora: 9.00 am.
nota: ir en ayuno

sabado 27:

Culto normal
lugar: iglesia
hor: 6.30 p.m.

Tests Vocacionales Online: Entrada en un blog de Blogger con links a varios tests vocacionales online. Algunos links rotos, otros apuntan a tests muy buenos. Ya estoy grande para estas cosas pero tenía que pasárselos a un conocido...

XOM XML Parser: Parser y modelo de objetos de XML. Lo pienso utilizar para levantar documentos KML de Google Earth en el contexto de un trabajo de investigación sobre Sistemas de Información Geográfica(GIS).

The Java Native Inteface Guide and Specification: Sitio oficial de sun con la guía de desarrollo JNI. Muy completo. Lo voy a utilizar en un proyecto para crear una interfaz entre dispositivos USB y Java desde Windows.

MPUSBAPI Library: Especificación (no oficial) del api (DLL en windows) para comunicar con dispositivos USB de Microchip.

Na początek wypadałoby stworzyć kod w Javie, który będzie startował cały skrypt w Javie - może to być jakaś ogólna klasa typy Game, która tworzy resztę managerów i logikę gry.
"Wołanie" metod statycznych z Javy jest bardzo proste z tego powodu, że nie musimy mieć instancji(obiektu) danej klasy. I na tym się właśnie zatrzymamy w tej części tutoriala.
Załóżmy więc, że mamy taki kod:

import java.awt.event.WindowAdapter;
import java.awt.event.WindowEvent;

import javax.swing.JFrame;
import javax.swing.UIManager;

public class Game {

public static void main(String[] args) {
//rusza nasza logika..

	try {
		UIManager.setLookAndFeel("com.sun.java.swing.plaf.windows.WindowsLookAndFeel");

		JFrame jFrame = new JFrame();
		jFrame.addWindowListener(
		new WindowAdapter()
		{
			public void windowClosing(WindowEvent e)
			{
			System.exit(0);
			}
		}
		);

		jFrame.setSize(400, 300);
		jFrame.setVisible(true);

	} catch (Exception e) {
		e.printStackTrace();
	} catch (Throwable t) {
		t.printStackTrace();
	}
}

public static int GetInt(int n){
	return n*n;
}

public static int GetVersion(){
	return 1;
}

}

Zauważmy, że wszystkie metody są statyczne oraz dobrane tak, żeby pokazać kluczowe różnice w ich wywoływaniu z poziomu cpp.
Teraz przejdźmy do naszego projektu w cpp - tworzymy nowy, pusty projekt c++ wg poprzednio podanych schematów. Tym razem musimy zrobić następujące czynności:

• na zakładce C/C++ Bulid przechodzimy do Settings/Tool Settings,
• przechodzimy do GCC C++ Compiler i dalej do Directories,
• klikając przycisk dodajemy katalogi \include i \include\win32 - (w moim przypadku są to D:\Program Files\Java\jdk1.6.0_06\include oraz D:\Program Files\Java\jdk1.6.0_06\include\win32)
• zatwierdzamy wprowadzone zmiany,
• następnie odnajdujemy zakładkę MinGW C++ Linker, która jest na poziomie C/C++ Bulid,
• wybieramy pole Libraries i uzupełniamy obie rubryki: w górej wpisujemy nazwę biblioteki statycznej którą musimy dołączyć do projektu ze względu na JVM - wpisujemy jvm (bez rozszerzenia), natomiast w dolnej musimy wskazać katalog zawierający tą bibliotekę (\lib w katalogu zainstalowanego JDK - u mnie D:\Program Files\Java\jdk1.6.0_06\lib),
• zatwierdzamy wprowadzone zmiany i powracamy do ekranu głównego.

Dodajemy do projektu pliki implementacji - w naszym przypadku wystarczy jeden, który wystartuje JVM - np. main.cpp. Jego treść jest u mnie następująca:

#include <jni.h>
#include <conio.h>
#include <memory.h>

int main()
{
JavaVMOption options[1];
JNIEnv *env;
JavaVM *jvm;
JavaVMInitArgs vm_args;
long status;
jclass cls;
jmethodID mid;
jint square;

options[0].optionString = "-Djava.class.path=.";
memset(&vm_args, 0, sizeof(vm_args));
vm_args.version = JNI_VERSION_1_4;
vm_args.nOptions = 1;
vm_args.options = options;
status = JNI_CreateJavaVM(&jvm, (void**)&env, &vm_args);

if (status != JNI_ERR)
{
printf("jvm ok\n");

cls = env->FindClass("Game");
if(cls !=0)
{
printf("class Game ok\n");

mid = env->GetStaticMethodID( cls, "GetInt", "(I)I");
if(mid !=0)
{
square = env->CallStaticIntMethod(cls, mid, 5);
printf("GetInt: %d\n", square);
}

mid = env->GetStaticMethodID( cls, "GetVersion", "()I");
if(mid !=0)
{
square = env->CallStaticIntMethod(cls, mid);
printf("GetVersion: %d\n", square);
}

mid = env->GetStaticMethodID( cls, "main","([Ljava/lang/String;)V");

if(mid !=0)
{
printf("method main ok\n");

jclass string = env->FindClass("java/lang/String");
jobjectArray args = env->NewObjectArray(0,string, NULL);

env->CallStaticIntMethod(cls, mid, args);
}
}

jvm->DestroyJavaVM();
return 0;
}
else{
printf("jvm problem");
return -1;
}

}

Teraz będę opowiadał o tym co się w nim dzieje.
Na starcie występuje deklaracja zmiennych, które za chwilę będą użyte do tworzenia JVM. Przejdźmy więc od razu do linii ustawiającej opcje JVM:

options[0].optionString = "-Djava.class.path=.";

Definiuje ona ścieżkę, gdzie JVM będzie szukać naszej klasy - u mnie widnieje . (kropka) a więc będzie szukać w katalogu projektu (cpp). Możemy tu oczywiście dodać parę ścieżek, rozdzielonych średnikiem (windows) lub dwukropkiem (linux,mac). Ponieważ jest to tablica opcji (o zadeklarowanym wymiarze 1) to nasza opcja ma indeks 0. Gdybyśmy chcieli zwiększyć ilość opcji to musimy to uwzględnić w miejscu deklaracji zmiennej options oraz parę linii niżej, gdzie podajemy ich liczbę raz jeszcze, już bezpośrednio (vm_args.nOptions = 1;).

Przejdźmy teraz do linii zawierającej następujący wpis:
vm_args.version = JNI_VERSION_1_4;
Jest to dość kłopotliwa stała, ponieważ jeśli ją źle podamy to nie nastąpi stworzenie JVM. Jeśli będziemy kompilować nasz kod z wykorzystaniem JDK6, wartość ta powinna być ustawiona na JNI_VERSION_1_6, ja natomiast kompilowałem z użyciem JDK1.4 i JDK6 (co można zmienić w opcjach projektu Javy lub globalnie w opcjach Eclipse) i działa z JNI_VERSION_1_4.
Do momentu szukania pierwszej metody wszystko powinno być jasne. Zobaczmy więc pierwszy przykład:

mid = env->GetStaticMethodID( cls, "GetInt", "(I)I");

Mówi on tak: znajdź mi "wzór" metody statycznej z określonej wcześniej klasy o nazwie "GetInt", która pobiera parametr typu int i zwraca wynik typu int.
Jeśli znaleziono, mamy kolejną linię:

square = env->CallStaticIntMethod(cls, mid, 5);

której tłumaczenie jest następujące: wywołaj metodę statyczną zwracającą int z określonej wcześniej klasy i "wzorca" metody i przekaż jej parametr 5 (int).Wynik zapisz do zmiennej square.
To teraz w skrócie dwa kolejne przykłady:

mid = env->GetStaticMethodID( cls, "GetVersion", "()I");
square = env->CallStaticIntMethod(cls, mid);

co tłumaczymy jako: znajdź "wzór" metody statycznej o nazwie "GetVersion" nie pobierającej żadnego parametru (pusty nawias zamiast V jak void!) i zwracającą wynik typu int. Wywołaj metodę z tego "wzorca" i zapisz wynik do zmiennej square.
Na zakończenie metoda main z Javy:

mid = env->GetStaticMethodID( cls, "main","([Ljava/lang/String;)V");
jclass string = env->FindClass("java/lang/String");
jobjectArray args = env->NewObjectArray(0,string, NULL);
env->CallStaticIntMethod(cls, mid, args);

Zaczynamy od poszukiwania "wzorca", podając że chodzi nam o metodę statyczną o nazwie "main", przyjmującą parametr typu String i nic nie zwracającej (V od void). Następnie musimy znaleźć "wzorzec" klasy String, który zostanie użyty do utworzenia pustej tablicy obiektów typu String, a następnie przekazanej do wywołania metody.

Tak jak w temacie, pokażę jak napisać prosty pomost między Javą a cpp przy wykorzystaniu IDE Eclipse z biblioteką CDT5.0 oraz wykorzystując toolchain'a MinGW. O sposobie konfiguracji takiego środowiska wspomniałem już wcześniej, a więc zaczynamy.

Naszym zadaniem będzie napisanie kodu w Javie, który będzie wykorzystywał dll'ke, którą przygotujemy wykorzystując język cpp i toolchain'a MinGW - będziemy przesyłać i odbierać dane z dll'a.

Lista wymagań jest następująca:

1. Eclipse + CDT + MinGW,
2. Java JDK (nie musi być koniecznie nowe), JRE nie wystarczy.

Ze wspomnianego JDK wykorzystamy następujące rzeczy:

• bin\javah.exe - pozwoli automatycznie wygenerować nagłówek języka cpp(.h) dla danej klasy Javy,
• include\jni.h - dostarcza "funkcje" do konwersji typów Java <-> cpp oraz wiele innych,
• include\$platform$ - $platform$ w moim przypadku to win32.

Kolejne kroki które będziemy wykonywać przedstawiają się następująco:

1. napisanie kodu klas(y) w Javie z użyciem słowa kluczowego native,
2. kompilacja klas(y) - otrzymujemy pliki .class,
3. wygenerowanie nagłówka dla języka cpp (.h) za pomocą narzędzia javah.exe,
4. implementacja wygenerowanego pliku nagłówkowego w projekcie w języku cpp,
5. skompilowanie kodu do postaci pliku biblioteki dynamicznej (dll/so),
6. uruchomienie aplikacji Javy.

Zaczynamy - punkt 1 i napisanie kodu klasy w Javie.
Jak już wspomniałem, użyjemy słowa kluczowego native do oznaczenia metod, które chcielibyśmy zaimplementować w języku cpp.

Niech za przykład takiego kodu w Javie posłuży nam następująca klasa:

public class SomeData {

native String GetVersion();
native void SetVersion(String sNewVersion);
native void DoSomething();

static{

System.loadLibrary("libjni_test");

}

public String GetSomeDataFromJava(){

return "dane z javy";

}

public static void main(String[] args) {

SomeData cData = new SomeData();
System.out.println("Version: "+cData.GetVersion());

}

}

Parę słów komentarza: na początku mamy metody natywne, które będziemy implementować w cpp - podajemy więc ich definicję i na tym kończymy. Następnie widoczny jest blok static{} w którym podajemy informację do JVM, z jakiej dokładnie biblioteki dll/so będziemy korzystać.
Ważne są dwie rzeczy:

1. nie podajemy tam rozszerzenia pliku (bez dll/so) ponieważ w zależności od systemu JVM zrobi to za nas,
2. nie musimy ładowania biblioteki zewnętrznej umieszczać w bloku static{} - równie dobrze można to zrobić zaraz na początku metody main(String[] args).

Ostatecznie w metodzie main(String[] args) wywołujemy naszą natywną metodę w celu sprawdzenia efektu.

Czas na punkt 2 z listy czyli kompilację - tak naprawdę dzieje się ona z automatu jeśli mamy w Eclipse ustawioną opcję automatycznego kompilowania przy zapisywaniu pliku. Jeśli więc utworzyliśmy prosty projekt Javy, to plik źródłowy (.java) znajduje się w katalogu /src/ a skompilowana klasa w katalogu /bin/.

W punkcie następnym użyjemy generatora nagłowka (.h) - narzędzia javah.exe. Jeśli jest on w naszej zmiennej środowiskowej PATH to wydanie polecania:

javah -jni $nasza_klasa$

w katalogu \src\ powinno zakończyć się sukcesem i wygenerowanym nagłówkiem, lecz może być jeszcze konieczne przekopiowanie pliku skompilowanego (.class) z katalogu \bin\ do \src\.
Natomiast jeśli wydanie powyższego polecania zgłasza błąd nieznanego polecenia, należy edytować zmienną PATH (np. z poziomu właściwości mój komputer, na zakładce Zaawansowane, przycisk zmienne środowiskowe, dodając dodatkowy wpis do zmiennej PATH, który będzie zawierał ścieżkę do pliku wykonywalnego java, javac, javah, itp. - np. D:\Program Files\Java\jdk1.6.0_06\bin\ - należy uważać żeby nie nadpisać jej całkowicie a tylko dopisać dodając średnik jeśli to konieczne do oddzielenia ścieżek).

W tym momencie mamy już wygenerowany plik nagłówkowy więc możemy w Eclipse opcjonalnie przełączyć perspektywę na C/C++ i utworzyć projekt C++ (New C++ Project) - również pisałem już o tym wcześniej, najważniejsze żeby dostępny był toolchain MinGW oraz rodzaj projektu wybrać Empty Project (.exe) ewentualnie docelowy Shared Library.

Po utworzeniu pustego projektu, należy dokonać na starcie paru ustawień - przechodzimy do jego właściwości:

• na zakładce C/C++ Bulid przechodzimy do Settings/Tool Settings,
• przechodzimy do GCC C++ Compiler i dalej do Directories,
• klikając przycisk dodajemy katalogi \include i \include\win32 - (w moim przypadku są to D:\Program Files\Java\jdk1.6.0_06\include oraz D:\Program Files\Java\jdk1.6.0_06\include\win32)
• zatwierdzamy wprowadzone zmiany,
• następnie odnajdujemy zakładkę MinGW C++ Linker, która jest na poziomie C/C++ Bulid,
• przechodzimy do zakładki Miscellaneous i w Linker Flags wpisujemy:
  -Wl,--add-stdcall-alias
  Bardzo istotna opcja, ponieważ dzięki niej nie dojdzie do "udziwnienie" metod w wynikowym pliku biblioteki dynamicznej. Gdybyśmy o tej opcji zapomnieli, to pomimo że nasza biblioteka byłaby widoczna, to JVM nie odnalazłaby w niej określonych nazw, właśnie przez te "udziwnienia", tworzone przez linker z toolchain'a MinGW.
• sprawdzamy jeszcze, czy na zakładce poniżej Miscellaneous-Shared Library Settings zaznaczona jest pierwsza opcja od góry Shared (jeśli tworzony był Empty Project trzeba ją zaznaczyć),
• opcjonalnie, jeśli korzystaliśmy z Empty Project musimy zmienić ustawienia generowania pliku wykonywalnego na generowania dll/so - uczynimy to zmieniając zakładkę Tool Settings na Build Artifact i ustawiając pole Artifact Type na Shared Library. Resztę opcji możemy tak pozostawić chyba że pragniemy dla przykładu nadać jakąś specyficzną nazwę dla biblioteki dynamicznej.
• zatwierdzamy wprowadzone zmiany i powracamy do ekranu głównego.

Teraz możemy zaimportować wygenerowany przez javah plik nagłówkowy (import/File System/podajemy scieżkę do wygenerowanego pliku nagłówkowego). Gdy spróbujemy ten plik podejrzeć,  include jni.h nie powinien zgłaszać błędów (w p.p sprawdź include directory), lecz syntax error'y pojawią się przy wszystkich liniach rozpoczynających się np. tak JNIEXPORT jstring JNICALL, czyli wszystkich eksportowanych metodach z/do Javy - nie musimy się tym w ogóle przejmować.

Teraz należy utworzyć plik implementacji zaimportowanego pliku nagłówkowego czyli wkraczamy w punkt 4 - dodajemy w nim include'y dla pliku nagłówkowego i jni.h oraz kopiujemy definicje metod z pliku nagłówkowego i uzupełniamy je o nazwy zmiennych w metodach(są tylko typy) oraz ciało metod.

Dla przykładu podam ciało metody zwracającej z dll'ki napis typu String:



JNIEXPORT jstring JNICALL Java_SomeData_GetVersion(JNIEnv * env, jobject o){
const char *str = "1.1 MinGW compiled";
return env->NewStringUTF(str);
}

Jak widać w powyższym, nie ma bezpośredniej konwersji typów między Javą i cpp, dlatego musimy się posługiwać metodami konwersji, które dostępne są przez odwołanie do JNIEnv, która jest tablicą metod pomocniczych.

Kompilujemy kod (Bulid Project) i jeśli wszystko dobrze wcześniej ustawiliśmy, otrzymamy w wyniku plik biblioteki dynamicznej o nazwie projektu z przedrostkiem lib lub podaną przy ustawieniach Arifact name, co kończy punkt 5.

Przed wykonaniem ostatniego punktu, czyli odpalenia aplikacji Javy, musimy w odpowiednim miejscu umieścić nasz plik wynikowy biblioteki dynamicznej. Możemy go umieścić w scieżkę wskazywanej przez java.library.path lub umieścić w wybranym miejscu i w ustawieniach projektu Javy - Java Build Path, rozwinąć zakładkę Source i edytować ostatnią pozycję o nazwie Native Library Location, wskazując folder gdzie znajduje się skompilowany dll/so.

Czas na wykonanie ostatniego kroku i uruchomienie (najszybciej w Eclipse z opcji Run As/Java application) kodu. W wyniku nie powinniśmy otrzymać błędu java.lang.UnsatisfiedLinkError, a jeśli się to zdarzy, to należy uważnie przejrzeć opisane wcześniej czynności.

W ten sposób kończę ten najdłuższy do tej pory wpis na blogu.
Z takimi podstawami można już szybko ruszyć w dalszą drogę i poznawać możliwości JNI.

The JNI is used to write native methods to handle situations when an application cannot be written entirely in the Java programming language such as when the standard Java class library does not support the platform-specific features or program library. It is also used to modify an existing application, written in another programming language, to be accessible to Java applications. Many of the standard library classes depend on the JNI to provide functionality to the developer and the user, e.g. I/O file reading and sound capabilities. Including performance- and platform-sensitive API implementations in the standard library allows all Java applications to access this functionality in a safe and platform-independent manner.

The JNI is not trivial and requires a considerable effort to learn, and some people recommend that only advanced programmers should use the JNI. However, the capability for Java to communicate with C++ and assembly removes any limitations on what function Java programs can perform. Programmers considering using the JNI should be aware that

1. JNI is not an easy API to learn;
2. Subtle errors in the use of JNI can destabilize the entire JVM in ways that are very difficult to reproduce and debug;
3. Only applications and signed applets can invoke the JNI;
4. An application that relies on JNI loses the platform portability Java offers (a workaround is to write a separate implementation of the JNI code for each platform and have Java detect the Operating System and load the correct one at runtime);
5. There is no garbage collection for the JNI side (JNI code must do explicit deallocation);
6. Error checking is a MUST or it has the potential to crash the JNI side and the JVM.

Enough of boring stuff. Now lets see some codes.

Here we will try to call the MFC function AfxMessageBox() from Java. Our function in C++ will take no arguments and will not return any value.

Following a simple Java program that calls the method showMessageBox() defined in a DLL, which we will create later.

public class JNISample
{
    static
    {
        System.loadLibrary("TestDll");
    }
    public static void main(String[] arg)
    {
        System.out.println("Hello world from Java");
        JNISample t =new JNISample();
        t.showMessageBox();
    }
    public native void showMessageBox();
}

As we can see, we have loaded a DLL, which we will soon create in Visual C++. This DLL consists of a method showMessageBox() which is defined in C++. This a basic procedure of using JNI. We write our application in Java first and declare the methods that will be required to call. We rarely write the native code first.

An alternative way to load a DLL will be to use System.load(...) method. With this load() method, you can supply any path to the DLL. While, the one used above i.e. loadLibrary(...) requires the DLL to be in the <WinDIR>\system32 folder.

Now the next step will be to generate a header file corresponding to this class. We use javah.exe utility which is included with JDK.

javah -jni JNISample

This will generate a header file. We will need this header file during the next step.

Now we are need to write a DLL which will contain the implementation of our native function. Easiest way is to use MFC AppWizard (DLL). Lets name the project TestDll. We should also include the header file we generate previously in TestDll.h.

Then, lets copy following line from JNISample.h and paste it at the end of TestDll.h.

JNIEXPORT void JNICALL Java_JNISample_showMessageBox(JNIEnv *, jobject);

and add following definition in the implementation file:

JNIEXPORT void JNICALL Java_JNISample_showMessageBox(JNIEnv *env, jobject obj)
{
    AfxMessageBox("MFC Hello via. a DLL");
}

Before we compile this application, we should include the path of jni.h header file. So following two directories should included through the IDE settings.
<JDK DIR>\include
<JDK DIR>\include\win32

Now lets compile and generate our DLL, put newly created DLL in system32 directory and then run our class file to see the output.

Credit: Initial description of JNI was taken from Wikipedia.

Almost all native libraries have some kind of nugget of data that represents state. It's often the return value from some factory function and the first argument of every other function in the API, and it's almost always a pointer. You'll find this model in many stable libraries because it scales incredibly well.

We'll get to the state itself later on. For now, assume that we have it, and that it's held by a pointer. [1]

KISS

In case you've been living under a rock, this annoying acronym stands for "Keep It Simple, Stupid." Whether you decide to take it as a personal insult is your choice, but it's a good principle to adhere to when you design a native interface. What this means is that you should keep complexity in your native interface to a minimum.

If you're just wrapping a stable native library, wrap the API functions that you need and no more. Don't try to get fancy with the API anywhere between the native method and the actual API functions. Wrap it as minimally as you can. If it's a good library, the authors will have designed it well. Don't mess with it. If you want to get fancy, you can do that on the other side of the class that has the native methods.

If you're delegating some part of your class to a native library, the same principle applies. Keep the interface minimal. Trust me when I say that you won't be served well by an ill-planned, overly-complicated interface. Leave the complexity to the implementation of the library.

One last thing to consider is performance. I'm not talking about premature optimization. I'm talking about preventing premature "pessimization." Be judicious in the design of your interface. For example, if you've got an operation that does the same thing to a bunch of pixels, don't design a native method that operates on one pixel. You wouldn't design your Java class or native API that way, so don't do it across the boundary, either. There are structures in JNI that help with passing large volumes of data around. Use them.

Representing your native data nugget

I already asked you to assume that you're using a pointer to represent your state. There are a number of complicated ways to encapsulate this idea on the Java side. You could create a "mirror" object, or you could encapsulate the idea of a pointer in a "Pointer" class. Both those methods add a needless layer of complexity. Use them, but don't pass them across the native/Java boundary. Remember: simple.

So what's the simplest way to represent a pointer in Java? A pointer is essentially just a number. [2] Easy enough. Just return a jlong and pass that around. You should do that. But there's a problem.

It's intrinsic to the effort. Native code (usually) requires explicit resource management, via a dispose() or free() API function. Java uses GC. So you have to treat native state like you would a network connection. You need to release the resource when you don't need it. That means that you always need a cleanup native method, and you need to be disciplined about resource usage. The try/finally way of handling this is often a good methodology.

The reasoning here is that sometimes native state can represent a significant expenditure of heap memory or other resources. In fact, the native state may hang on to network connections, keeping them open until the disposal function is called. You just don't know. It's a good idea to work within the native resource model, and release the resource as soon as you're finished with it. In fact, I don't like depending on a finalizer at all, and avoid implementing them, at least to manage resources. [3]

Declare native methods as static

It's natural, if you've been steeped in OOP, to think that for any native method that passes state, you should declare it as a member of the class. I claim that it's more useful to declare each native method as static. Let's compare. Here's the two ways to declare essentially the same thing:

[sourcecode language='java']...
private native boolean doSomething
(long ptr, double x, double y);
private static native boolean doSomething
(NativeClass obj, long ptr, double x, double y);
...[/sourcecode]

And here's what you end up with on the native side:

[sourcecode language='cpp']...
jboolean doSomething_member
(JNIEnv *env, jobject obj, jlong ptr,
jdouble x, jdouble y)
{
...
}

jboolean doSomething_static
(JNIEnv *env, jclass cls, jobject obj, jlong ptr,
jdouble x, jdouble y)
{
...
}
...[/sourcecode]

It's slightly longer, because you have to pass this as the first parameter, and then the native pointer, but it has a hidden parameter that's useful: the class. If you declared the method as non-static, then you'd have to look up this information inside the native implementation. Declaring as static prevents the need for the lookup.

Declare native methods as private

Additionally, you'll notice that I declared the native methods as private. I need to pass the pointer parameter every time I call a method, but I don't need that implementation detail exposed to the world. So I just create a wrapper function that calls the native method with the state pointer, and make the state pointer private as well. If I do this, though, it doesn't matter if I declare the native method as static or not. If it's all wrapped up anyway, just make it static and no one has to care that this has to be passed as a parameter.

Taking it from here

And that's my advice for creating a native library. At this point, it's pretty much all implementation. I hope you find it useful. Be sure to check out parts 1-3. I also plan to do a walk-through of wrapping a native library, to give an idea of how it all goes together.

Footnotes:

[1] So why don't we address working with Java state the same way? The reason is that native-to-Java calls can be slower than Java-to-native calls by a nontrivial amount. In my testing, Java-to-native calls have negligible cost. My guess is that these calls are optimized because they're the important part of native libraries. Whether you're taking advantage of an existing native library or trying to gain performance in Java code, you're delegating work to the native side.

[2] C++ mavens might chime in at this point and explain that a pointer isn't always a number. But you can always get a unique numeric representation of a pointer, which is the important part.

[3] You may be thinking that a "Pointer" class is a good idea at this point. It's not necessarily a bad idea, but you should still provide an explicit "dispose" method that does the job of releasing the resources, and not just depend on the finalizer to take care of it.

Tags: JNI, Java, DLL

At compile time, JNI defines how Java data types correspond to C data types. C programs get this information from JNI header files that come with the Java SDK. Javah, a tool that comes with the SDK, creates application-specific header files that help eliminate programming errors in communication between Java and C routines. At run time, JNI lets Java objects be passed to C code, and lets C code access Java properties and methods. Thus, C code can set properties of Java classes, making it possible to call Java methods from C.

Six steps to call C/C++ from Java code

The process of calling C or C ++ from Java programs consists of six steps. We'll go over each step in depth in the sections that follow, but let's start with a quick look at each one.

1. Write the Java code. We'll start by writing Java classes to perform three tasks: declare the native method we'll be calling; load the shared library containing the native code; and call the native method.
2. Compile the Java code. We must successfully compile the Java class or classes to bytecode before we can use them.
3. Create the C/C++ header file. The C/C++ header file will declare the native function signature that we want to call. This header will then be used with the C/C++ function implementation (see Step 4) to create the shared library (see Step 5).
4. Write the C/C++ code. This step consists of implementing the function in a C or C++ source code file. The C/C++ source file must include the header file we created in Step 3.
5. Create the shared library file. We'll create a shared library file from the C source code file we created in Step 4.
6. Run the Java program. We'll run the code and see if it works. We'll also go over some tips for dealing with the more commonly occurring errors.

Let me reiterate what I see as the pros and cons of javah:

Pros:

1. Simple; you only have to run a command and the declarations are done
2. Great for whipping up a wrapper interface for a stable native library

Cons:

1. Changes in the Java interface can have unexpected results
2. Signature encoding for overloaded functions is odd and different from the encoding for the rest of the API
3. It exposes the native interface to the world

There's another way to get the job done, and it essentially inverts these arguments. That is, this method takes a little more effort to get started, and it's not ideal for throwing together a quick wrapper. However, if you invert the cons above, they become pros for this method. What method is this? RegisterNatives.

With RegisterNatives, you essentially take a class, and a map (a mapping is the name of a method and the Java signature of the method, and a function pointer to a native implementation) and you tell the JVM to use that map for the class.

• The encoding is the same as the rest of the API:

  The bad news here is that you can't generate the map automatically. [1] The good news is that Java method signatures are easily found by using javap (they're also listed in the comments in the header that javah creates). The javap program is used just like java and javah, except that it gives you a diagnostic output of what your class looks like (you'll need "-private" to get all of the methods, not just the public ones).

  If you give javap the "-s" option, it will also spit out the signature of each method, the one that you need for RegisterNatives. It also happens to be the signature that you'll need to look up the method ID for calling a Java method from native code. That makes it a little more valuable to learn, and after a while, you won't need javap. I can write signatures just by looking at the Java method declaration (it gets a little trickier with generics, though).

• Adding a Java method won't have unexpected results:

  Because the mapping is explicit, and you wrote it, using RegisterNatives to map Java to native methods won't have any weird results when you add a new Java method. The mapping remains valid.

• None of the native interface is exposed, except perhaps for a static "init" function:

  If you're concerned about the security of the native interface, the javah way of doing things will leave your native implementations exposed to the elements. If you call RegisterNatives from your "init" static method, however, all the mapping can be done at runtime. If this sounds like "security through obscurity," it is. However, that's pretty much the best you get with Java (and native code, but often the obfuscation is easier).

  One of the problems with javah that I forgot to mention (aside from exposing your entire interface, yielding confusing function names, and sometimes giving you unexpected results) is that the exported functions are fixed at runtime. This may seem like an obvious requirement, but it isn't necessarily so if you use RegisterNatives.

Enough jabbering on about RegisterNatives. How do you use it?

Like I said, it's pretty straightforward. In your static native "init" function (I'm assuming that you set one of these up so that it's called in a static initializer), set up the map; let's use NativeClass from the last post, and signatures from javap:

[sourcecode language='cpp']JNIEXPORT void JNICALL Java_my_NativeClass_init
(JNIEnv *env, jclass cls)
{
JNINativeMethod methods[] = {
// name, signature, function pointer
{ "doStuff", "(Ljava/lang/String;II)V", &doStuff_string },
{ "doStuff", "(F)V", &doStuff_float },
{ "performAdmirably", "([ZLjava/lang/Runnable;DD)J", &performAdmirably_array },
{ "performAdmirably", "(F)J", &performAdmirably_float }
};
...[/sourcecode]

Notice that I keep the javah style for init. That means that the JVM can find it right away when it loads the library. Now call RegisterNatives:

[sourcecode language='cpp']...
env->RegisterNatives(cls, methods, 4);
}[/sourcecode]

Pretty simple. What to the implementations of the functions look like? They're actually pretty close to what we saw from javah:

[sourcecode language='cpp']...
/*
* Class: my_NativeClass
* Method: doStuff
* Signature: (Ljava/lang/String;II)V
*/
void JNICALL doStuff_string
(JNIEnv *, jobject, jstring, jint, jint)
{}

/*
* Class: my_NativeClass
* Method: doStuff
* Signature: (F)V
*/
void JNICALL doStuff_float
(JNIEnv *, jobject, jfloat)
{}

/*
* Class: my_NativeClass
* Method: performAdmirably
* Signature: ([ZLjava/lang/Runnable;DD)J
*/
jlong JNICALL performAdmirably_array
(JNIEnv *, jobject, jbooleanArray, jobject, jdouble, jdouble)
{
return 0;
}

/*
* Class: my_NativeClass
* Method: performAdmirably
* Signature: (F)J
*/
jlong JNICALL performAdmirably_float
(JNIEnv *, jobject, jfloat)
{
return 0;
}
...[/sourcecode]

They have to have the same arguments, or else the JVM would crash calling them. The nice thing is that you can give them names that make sense. Also, it's not difficult to figure out what arguments should be there. I recommend using javah for a while until you get used to seeing what should go into the declarations.

Notice that I drop JNIEXPORT, but retain JNICALL. There's a reason for that; it's very important (at least on Windows; not so much on other platforms) to make sure that the calling convention matches what the JVM expects. JNICALL is the way to do that.

Compile the native library, and run your class. Assuming that you've called init from your static initializer after you call System.loadLibrary, you should be able to use all of your methods.

In the next post, I'll talk about some suggestions for how to declare your native methods.

Footnotes:

[1] Well, you could, but you'd need to code one up yourself; maybe that's a project I'll take on for learning OCaml.

Tags: JNI, Java, DLL

Overview

First, I think that it would probably be helpful to go over what a native method implementation looks like. Say that we define a class called my.NativeClass, and we add the init static method to it like we did in the last post, and we add two methods, doStuff and performAdmirably:

[sourcecode language='java']public class NativeClass
{
static {
System.loadLibrary("JNITest");
init();
}

static native void init();

public native void doStuff(String str, int x, int y);

public native long performAdmirably
(boolean[] marks, Runnable r, double u, double v);

public static void main(String[] args)
{
System.out.println("Entered main");
}
}
[/sourcecode]

We'll need to know what to put in the native file; Java code won't do. I'm not going to worry right now about fleshing out these implementations. As you can see, these are toy interfaces, and a tutorial about how to write a real native library deserves a more serious example. Let's run javah. A file named my_NativeClass.h is generated, with the following declarations:

[sourcecode language='C']...
JNIEXPORT void JNICALL Java_my_NativeClass_init
(JNIEnv *, jclass);
...
JNIEXPORT void JNICALL Java_my_NativeClass_doStuff
(JNIEnv *, jobject, jstring, jint, jint);
...
JNIEXPORT jlong JNICALL Java_my_NativeClass_performAdmirably
(JNIEnv *, jobject, jbooleanArray, jobject, jdouble, jdouble);
...[/sourcecode]

You'll notice that unlike init, doStuff and performAdmirably take as their second argument a variable of type jobject. This reflects the fact that they are not static methods; they're instance methods. The jobject parameter represents the instance that the method is being called on, and can be used to access fields and methods of the instance. Likewise for static methods, the jclass parameter represents the class, and can be used in that capacity.

You've probably also noticed that the third parameter to the native doStuff is of type jstring. Because Strings are so often used in native code, and there are so many API functions in the JNI for them, it has its own type. You'll notice the same thing about the third argument of performAdmirably; its type is jbooleanArray (all of the primitive array types have an equivalent native array type).

The Runnable argument has no equivalent. It's just a jobject. All the primitive types have equivalents, and they actually carry the value of their respective variable; the other types represent Java references. There are a couple more special types, but I'll get to them in a different post.

Copy the declarations to an implementation file, and leave the bodies blank (just return 0 from performAdmirably), and your Java class should run, assuming that you've done all the steps in the last post.

Complicating things

Ok, let's throw a wrench into things. Create overloads for each of the functions we defined before. Let's just give them each one float parameter:

[sourcecode language='java']public class NativeClass
{
static {
System.loadLibrary("JNITest");
init();
}

static native void init();

public native void doStuff(String str, int x, int y);
public native void doStuff(float f);

public native long performAdmirably
(boolean[] marks, Runnable r, double u, double v);
public native long performAdmirably(float f);

public static void main(String[] args)
{
System.out.println("Entered main");
}
}
[/sourcecode]

If you re-run your Java class, things will probably still work. If you try to call both versions of either function, however, you'll get an exception thrown. This is because you don't have implementations for both overloads in your native library. You probably expected this.

Here's the kicker, though: run javah again, recompile your native library, and try to run the java code again. If you call both overloads, neither will work. Open the header file, and you'll see why:

[sourcecode language='c']...
JNIEXPORT void JNICALL Java_my_NativeClass_init
(JNIEnv *, jclass);
...
JNIEXPORT void JNICALL Java_my_NativeClass_doStuff__Ljava_lang_String_2II
(JNIEnv *, jobject, jstring, jint, jint);
...
JNIEXPORT void JNICALL Java_my_NativeClass_doStuff__F
(JNIEnv *, jobject, jfloat);
...
JNIEXPORT jlong JNICALL Java_my_NativeClass_performAdmirably___3ZLjava_lang_Runnable_2DD
(JNIEnv *, jobject, jbooleanArray, jobject, jdouble, jdouble);
...
JNIEXPORT jlong JNICALL Java_my_NativeClass_performAdmirably__F
(JNIEnv *, jobject, jfloat);
...[/sourcecode]

The original declarations are gone, and have been replaced with declarations that are much more arcane. This is the biggest problem that I have with javah. Even if you add it to your build configuration so that it's run automatically, it may still cause unexpected linking issues at runtime if you change the Java interface.

In the end, though, this won't cripple your development. If all that you're trying to do is stick a wrapper around a stable library, chances are high that you won't be maintaining the native interface very often. If you're maintaining and updating your native library regularly, though, it can be inconvenient to keep examining the declarations generated by javah to make sure that you haven't missed anything.

Summary

To sum up, here's the pros and cons (as I see them) for javah:

Pros:

1. Simple; you only have to run a command and the declarations are done
2. Great for whipping up a wrapper interface for a stable native library

Cons:

1. Not necessarily robust; changes in the Java interface can have unexpected results
2. Signature encoding for overloaded functions is odd and different from the encoding for the rest of the API (I'll explain this later, I promise)
3. It exposes the native interface to the world; I didn't mention this before, but if you're concerned about this kind of thing (especially if you're obfuscating your code), you may want to be careful about what native methods you expose, because they'll all show up in the library interface.

Using javah is the de rigeur way of starting a native library. In the next post, I'll talk about a different method, which works just as well, and is actually used by parts of the Java 2 API.

Tags: JNI, Java, DLL