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. Postaram się dodać screeny z poszczególnych ustawień opcji, aby rozwiać wszelkie wątpliwości.

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

There are several reasons to use native functions; prominent among them are the ability to access special hardware and the ability to use pre-existing native libraries.

Before you start:

To get a class started with native code, here's the basic checklist that I use:

1. Set up your native code project or makefile: Make sure that you add the include directory from your JDK to the list of include directories, as well as include/{platform_name}. The second one is important because otherwise, jni_md.h won't be found. Unless you plan to fire up a JVM from your library, you won't need any special linker instructions, other than to specify that your library will be a shared library.
2. Set up JNI_OnLoad and JNI_OnUnload: I like to put these functions in a file of their own; many times I'll just use the default implementation file that my IDE generated for me. These don't need a header file of their own; they're already declared in jni.h [1]. You can use the templates found here.
3. Add code to the static initializer of your Java class: There are things that you'll need to do to your Java class to get it to work with native code. A call to System.loadLibrary is the most important part. Without a call to this method, any call to a native method will throw java.lang.UnsatisfiedLinkError. System.loadLibrary may also throw java.lang.UnsatisfiedLinkError if it can't find the library. Be sure to make the library accessible to your Java class. [2] It may also throw java.lang.SecurityException if the security manager doesn't like what the class is trying to do.

   The argument to System.loadLibrary doesn't need to have "lib" at the front or ".dll" at the end. The call will add all the necessary decorations for your platform to the string that you give it. Simply put:
   [sourcecode language='java']...
   static {
   System.loadLibrary("myNative");
   ...
   }
   ...[/sourcecode]

At this point, the class will load the native library and initialize it. It can't do anything though, because we haven't implemented any native methods. You might note that we don't necessarily need to call System.loadLibrary from the static initializer. But it's going to make your life quite a bit easier if you do.

You could load the native library with a singleton. If you do this, though, you'll have to prod the singleton before every call to a native function. The native library needs to be loaded and mapped before a native method call can be made. If you make the necessary calls in the static initializer, no extra effort needs to be spent. There are probably reasons to load the native library lazily, but for the most part, early initialization is fine.

Adding native methods:

At this point, we can start adding native methods. Before you add any other native methods, I suggest that you add a static native void method named init (or some other name suitable to you) that takes no arguments, and call it in the static initializer, right after the call to System.loadLibrary:

[sourcecode language='java']...
static {
System.loadLibrary("myNative");
init();
}

static native void init();
...[/sourcecode]

The init native implementation will be a good place to cache all sorts of useful information and do all sorts of useful things. I use something similar to it in all my classes that have native implementations.

If you try to run your Java code right now, it will throw java.lang.UnsatisfiedLinkError. So we need to add a native implementation. Before we do that, though, run javah on your Java class, the same way that you would invoke the class from the command line. What you'll get is a C header file in the directory where you ran javah that declares the implementation of your native method:

[sourcecode language='c']/* DO NOT EDIT THIS FILE - it is machine generated */
#include
/* Header for class testjni_TestJNI */

#ifndef _Included_testjni_TestJNI
#define _Included_testjni_TestJNI
#ifdef __cplusplus
extern "C" {
#endif
/*
* Class: testjni_TestJNI
* Method: init
* Signature: ()V
*/
JNIEXPORT void JNICALL Java_testjni_TestJNI_init
(JNIEnv *, jclass);

#ifdef __cplusplus
}
#endif
#endif[/sourcecode]

I ran javah on a class called testjni.TestJNI with the init method that I mentioned above. As you can see, a function declaration called Java_testjni_TestJNI_init is generated. If you add other functions to your Java class and repeat this process, they'll show up in the header file as well. But I don't use them, for reasons that I'll cover in the next post.

For now, just cut the declaration from the header file and paste it into a new implementation file. We don't need the header anymore:

[sourcecode language='cpp']#include

extern "C" {

/*
* Class: testjni_TestJNI
* Method: init
* Signature: ()V
*/
JNIEXPORT void JNICALL Java_testjni_TestJNI_init
(JNIEnv *, jclass)
{}

}
[/sourcecode]

Add this to your native project/makefile, build it, and test your Java class. It should run just fine.

In the next post, I'll talk about how to write your native methods.

Footnotes:

[1] In fact, I don't usually set up header files for native functions. The only entities that will be calling native method implementations are Java classes. You probably won't run into any need to call them directly; you'll probably be calling some other functions that the native methods themselves call. Therefore, there's no need to declare them in headers.
[2] There are a number of ways to do this; including setting the system property "java.library.path," and using the platform's way of locating shared libraries.

Tags: JNI, Java, DLL

Declarations

Let's first look at the declarations for JNI_OnLoad and JNI_OnUnload from jni.h:

[sourcecode language='c']...
/* Defined by native libraries. */
JNIEXPORT jint JNICALL
JNI_OnLoad(JavaVM *vm, void *reserved);

JNIEXPORT void JNICALL
JNI_OnUnload(JavaVM *vm, void *reserved);
...[/sourcecode]

You'll find this section way down at the end of the file. JNIEXPORT and JNICALL are just macros defined to be platform-specific directives that determine how you get symbols exported from a native library. They're defined for your platform in {platform name}/jni_md.h.

Arguments

You'll notice that JNI_OnLoad and JNI_OnUnload each have two arguments: vm and reserved. Forget about reserved. There's nothing super-secret or special that I know that you can do with it, and I haven't tried to find out because it's, well, reserved. There may be a use for this variable on other JVMs than the Sun JVM. If you try to do something undocumented or JVM-specific with this variable, you're asking for trouble in the future or on other platforms, respectively.

The vm argument is used to give you access to parts of the Invocation API, specifically the parts that you can use with an already-running JVM. You can attach or detach the currently-running thread, get the currently-running thread if it's already attached, or destroy the JVM (if you're running a native library attached to a Java process, it would be silly to destroy the JVM; this is meant for native processes that start a JVM).

What you should do

There are lots of things that you could do in JNI_OnLoad. You could even start your car with it (that isn't completely far-fetched; Java goes a lot of places).

But here's a few things that you should do:

1. Return the JNI version that you want support for, and set it to at least JNI_VERSION_1_4. Whether you use JNI_VERSION_1_6 is between you and your comfort level with the latest versions of Java.
2. Store the vm argument. The vm variable can be useful for a lot of things, and it will never change. You can look it up again from the context of a mapped native function, but you can't from an arbitrary function without looking up the JVM first (which requires linking to the JVM library, which can complicate things). If you have vm, why not just store it? Stick it in a singleton or static variable.
   
   
   
   For example, say that a mapped native function sets up a callback to be run from some arbitrary native thread. If the JVM is available to you, you save yourself a step.
3. Initialize anything else that you need library-wide and want to initialize early. This includes library init routines, etc. As I mentioned in Part 1, calling DllMain from statically-initialized code can be risky, so doing anything that might load a DLL should probably go in JNI_OnLoad instead (or be lazily initialized somewhere else).

Is JNI_OnLoad a good place to store method IDs and class references? Probably not. The problem in doing this is that those objects only have a lifetime as long as their associated Java class, and the native library may live longer than that (it can link to multiple classes). These objects should be refreshed when the class is loaded, so save such caching for a native method called from the static initializer of the class. More on that in a different post.

JNI_OnUnload

You've probably noticed by now that I've neglected JNI_OnUnload. This function gets called whenever the native library is released. Note that this will be when the class loader that stores it is garbage-collected, so it isn't a good idea to assume that it will be called after any one particular class is collected. In fact, it isn't a good idea to assume that it will be called at all. If a native library is loaded by the default class loader, that class loader may never get finalized.

In my opinion, the best that you can do in this function is to reset your previously-stored vm variable, to ensure that nothing else tries to use it (since the JVM has now officially divested itself of the library). You should, of course, protect the variable against concurrent access. Leave necessary library cleanup to a different function.

One thing to note here is that this illustrates a running theme in JNI programming. It's easy to get something created, but it can be tedious to ensure its proper destruction. It's one place where Java is very different from native code, and it comes out on JNI boundaries.

Putting it together

To sum up, here's a skeleton for JNI_OnLoad and JNI_OnUnload in C++:
[sourcecode language='c++']// onload.cpp
#include <jni.h>

#include <vmutil.h>
#include <otherlibrary.h>

JNIEXPORT jint JNICALL
JNI_OnLoad(JavaVM *vm, void *reserved)
{
// Store the JVM
VM::getInstance().init(vm);

// Do initialization here
OtherLibraryInit("Native", OTHER_LIBRARY_NO_ZUCCHINI);

// Return the JNI version
return JNI_VERSION_1_4;
}

JNIEXPORT void JNICALL
JNI_OnUnload(JavaVM *vm, void *reserved)
{
// Reset the JVM pointer
VM::getInstance().cleanup(vm);
}
[/sourcecode]

That concludes this post, and I'll talk about how to set up the Java class and native methods in a post to come soon.

Tags: JNI, Java, DLL

[Edited to use the source code widget; that makes things a lot easier!]

JNI_OnLoad is there for two reasons: to specify the minimum JNI version needed by the library and to perform library initialization. If it's not present in your library, the JVM will assume that it's only compliant with the minimum JNI version, 1.1.

It may seem unnecessary to export JNI_OnLoad from your library if you don't have anything to initialize. However, the minimum version of 1.1 isn't the best. You should at least support 1.2. Several good features were added in that version of the API. If you want support for java.nio.ByteBuffer, you're going to need 1.4. You probably won't need 1.6, unless you're really interested in the kind of reference you're looking at. I have had no personal need for that level of introspection. I'd recommend 1.4, unless you really need the features supplied in 1.6.

If you do have something that you want to do on library initialization, JNI_OnLoad is the best place to get it done. If you're programming a DLL on Windows, then you may be tempted to do the initialization in DllMain instead. I'd recommend against that for the following reasons:

• It's possible, though tedious, to perform lookups of information from the JVM within DllMain. JNI_OnLoad gives you direct access to the JVM API functions.
• JNI_OnLoad isn't called from the context of DllMain. That means that it's safe to load other DLLs from it, and also to look up Java classes. A Java class may end up loading a native library of its own, which means that your program will deadlock if you try to do this lookup from DllMain.
  
  Oh yeah, if you didn't know, DllMain isn't reentrant, so you'll deadlock if you try to load a DLL in the context of DllMain. That seems to be a fact that is overlooked in many forum posts on JNI, and it's one that will have you pulling out your hair if you don't know it or remember it.
  
  Static initialization also falls under that category, so be careful what you statically initialize in a native library DLL. It's probably best to use a pointer for static data, and initialize the data in JNI_OnLoad.
• Debugging in DllMain can get a bit wacky. At least in Visual Studio, it can be difficult to set a breakpoint in DllMain and have it stop where you want it to. With JNI_OnLoad, it's never a problem.

I'll describe how to best utilize JNI_OnLoad in the second part of this post.

Tags: JNI, Java, DLL

What is JNI?

JNI stands for Java Native Interface. It's simply a way for the JVM to interface with machine-native code. JNI functions consist of implementations of Java methods that are declared native. The code is provided in a shared library or DLL, and loaded by the Java program when a class needs it.

Why would you use JNI?

Despite breathless claims to the contrary, Java bytecode can't perform any faster than native code on any particular platform. It may be the case that a particular implementation can run as fast or better on modern JVM's than a similar implementation in C or C++, but this isn't true generally (also, this comparison is prone to the apples-to-oranges problem). There are good reasons to go all-Java, so I'm not trying to start the age-old Internet debate all over again. Suffice it to say that there may be performance gains in using a native library.

Additionally, bytecode can't interact directly with hardware. For example, if your program is written to take advantage of a GPU, it's likely that a native library will be involved somewhere in the picture. JNI allows you to write code that takes advantage of these features available on your platform.

Another reason to use JNI is if you already have a working library that you want to take advantage of in Java code. Say that you have some ancient library that works like a charm, and hasn't been altered in years, but no one wants to rewrite it in Java code, because it would be too much work. This is a perfect application for JNI. All that is necessary is to write a couple wrapper functions and make the calls to the legacy library. (In theory, anyway; it usually gets a little more complex than that.)

Books & Links:

If you're anything like me, you like a good text on the topic that you're interested in. There are two books specifically for JNI in print:

1. Java(TM) Native Interface: Programmer's Guide and Specification (The Java Series) by Sheng Liang, Prentice Hall PTR (June 20, 1999)
2. Essential Jni: Java Native Interface (Essential Java) by Rob Gordon, Prentice Hall PTR (March 1998)

The Liang book is considered to be the essential source on JNI programming. In fact, it's free. Don't pay for it. It's available from Sun. I can't say anything about the Gordon book, because I haven't read it. You'll notice that these books are almost nine years old and over ten years old, respectively. That's because the JNI API has changed very little in that time. A couple of API functions have been added, but for the most part, it's the same as it was in 1999, which can be kind of comforting.

I printed out a copy of the Liang book a while ago, and it served me well as a good starting point. If you're in the need for JNI, and you want to get a good overview on how to use it, it's a good text. When you start getting more complicated with it, though, that's when you need a little more info, and for the most part, it's not out there, except in scattered forum posts and Java bug descriptions.

An absolute must-bookmark link is this one: the JNI Spec. If you do any JNI programming, you'll be referencing this page a lot.

How do I use the JNI?

One stumbling block for me and my colleagues was getting used to writing the JNI code. I eventually came up with some rules of thumb for creating the JNI interface that sped up development time:

1. Implement JNI_OnLoad and JNI_OnUnload for your native implementations; don't use DllMain on Windows
2. Don't run javah, use RegisterNatives() in your code
3. Use care in how you access arrays
4. Use peer objects, but make them loosely-coupled

These are the points where I depart from Liang's book. Most of what's in the book is sound advice, in my opinion. Like it says, these are rules of thumb, not laws set in stone. These are practices that worked well for me and my colleagues. I will be getting to these each in separate posts.

How do I debug JNI code?

Another big difficulty lies in debugging native code that's called by Java code, or Java code that you're trying to use with native code, or both. Getting everything to line up is tricky. And it deserves a whole post.

Stay tuned for more on this topic, and I hope that you find it useful.

What I think that I can claim is some expertise in a few niche fields. Note that I say "some expertise" instead of "that I am an expert." Therefore, I'll usually try to state the source of my expertise if it isn't wholly my own.

The areas of expertise that I can claim here, and will most likely post on, are:

1. JNI Programming: JNI stands for Java Native Interface, and is the standard way of extending Java with native code. Much of the Java 2 API uses it (java.lang.Object has native methods), and its hooks have to be implemented by any compliant JVM. The thing about JNI is that it *can* be incredibly tedious to use. This subject deserves a post of its own, though, so I'll stop here.
2. Generic Programming: This is a method of programming in the same way that Object-Oriented Programming is a way of programming. Generic programming goes off the idea that a function or class can be used with a wide variety of types, not just those that fit a certain interface.
   Generic programming can be taken further, and it can be used to build skeletons for basic design patterns that you can "fill in" with the classes of your choice. There's a library provided by Adobe called the Generic Image Library that's built on this idea. GP libraries use "concepts" instead of interface definitions to specify what a class should look like to be used with its generic constructs.
   I would say that I have an intermediate-level understanding of GP, so I feel that I could probably help those people trying to get started on it.
3. Template Metaprogramming: Much like GP, this technique uses C++ templates, but it does so in a different way. TMP uses templates to generate code, and can be used to "unroll" loops, control the selection of functions for overload, create functions, provide information on other constructs, plus many more uses (such as making GP work better).
   Again, I would say that I have an intermediate knowledge of this topic.
4. The STL: I'm a big fan of the STL, and you should be too, if you use C++! I'm definitely not an expert on the STL; I'd say intermediate here again, but it's really easy to gain a basic understanding of it, and a basic understanding will help out a ton, so I think that I can help out there.
5. Parallel Programming: This is a big one, and there are heavier hitters out there, but I have a decent amount of experience with this topic, and it can be pretty important to get right. I'll see if I can help.

That about sums it up for stuff that I'm comfortable with; I do also know a fair amount about handling raw image data, but that's not quite as useful as the higher-level knowledge of manipulating images with transforms, so I'll probably leave that subject out.

As for other topics that I have an interest in, but am not well-versed in, I'll list those here briefly:

• GPU Programming
• Functional languages (like OCaml or Haskell; no experience at all, in fact, but I want to teach myself, so I'll blog about that while it happens)
• Image processing (like convolutions and transforms)

I'll stop there. Again, welcome, and I hope that you find this blog useful.

[Edit: trying to fix a couple formatting quirks]

Rentrons dans le vif du sujet: qu'est-ce que ça donne du coté de mon application C#:
[code language='csharp']
// on démarre la JVM avec mes bons arguments
MathiasJniCpp.JVMWrapper.InitJvm(new String[] { "-Djava.class.path=Mathias.Jni.Java.jar" });

// on créer un objet .Net qui wrappe l'objet Java
// en C++/CLI, le destructeur des classes CLI sert de méthode "Dispose"
using (MathiasJniCpp.MyJavaWrapper javaObject = new MathiasJniCpp.MyJavaWrapper())
{
// faire mumuse avec...
javaObject.People = "Mathias";
Console.WriteLine(javaObject.SayHello());
}

// on libère la JVM
JVMWrapper.ReleaseJvm();
[/code]

MathiasJniCpp c'est le namespace de mon assembly c++/cli, j'en reparlerai plus tard.
On voit que je manipule une classe JVMWrapper qui me permet de charger une JVM (et de la libérer). J'utilise aussi une classe .Net codé en C++/CLI. En fait, je l'utilise comme un classe C#, ou VB.net etc. C'est une classe "classique" .Net avec des méthodes et des propriétés.

Point intéressant à souligner: pourquoi utiliser using?
Pour rappelle, il y a des mots-clefs en C# très lié au Framework (comme foreach) et using en fait partie. Il prend les objets qui implémente IDisposable et fait appelle à la méthode Dispose() à la fin du bloque. Comme ça, je suis sûr de libérer la classe du coté JVM quand j'en ai plus besoin.

Je ne vais pas montrer tout le code, car trop long et disponible ici.
Mais voici un aperçu de la classe C++:
[code language='cpp']
#include "jni.h"
public ref class MyJavaWrapper
{
private:
static jmethodID initMethodId;
static jclass clazz;
jobject obj;
public:
/* initialisation des métadata Java/JNI, à voir plus tard */
static void initJavaMetadata()
{ ... }

/* une méthode de notre classe Java que l'on wrappe, expliqué aussi plus tard */
String^ SayHello(String^ people)
{ ... }

/* constructeur */
MyJavaWrapper(void)
{
// histoire de récupérer toutes les métadatas nécessaires du coté Java
MyJavaWrapper::initJavaMetadata();

// construction d'une instance avec le constructeur par défaut
this->obj = JVMWrapper::env->NewObject(MyJavaWrapper::clazz, MyJavaWrapper::initMethodId);
}

/* "destructeur" */
virtual ~MyJavaWrapper(void)
{
JVMWrapper::env->DeleteLocalRef(this->obj);
}
};
[/code]
ref class veut dire "c'est une classe .Net". Mais... ma classe n'implémente pas IDisposable!! Et c'est quoi ce destructeur??
Et oui: le destructeur C++ pour un objet .Net est transformé en la méthode Dispose() et la classe devient alors forcement IDisposable. Pour gérer le finalize allez voir ici.

Je manipule le membre this->obj qui est tout simplement un "pointeur" sur notre objet java. En fait, c'est un jobject qui est un type définie dans "jni.h".
J'utilise la classe JVMWrapper qui me permet de communiquer avec la JVM, et je lui demande de créer un nouvel objet d'une certaine classe jclass avec un certain constructeur jmethodID et j'obtiens ainsi mon jobject.
Étant donnée que la classe et la méthode ne change pas, j'ai rendu ces données static.

Voyons maintenant ce que fait MyJavaWrapper::initJavaMetadata();:
[code language='cpp']
/* initialise les metadata du coté Java */
static void initJavaMetadata()
{
// si les métadata ne sont pas déjà récupérées...
if(MyJavaWrapper::clazz == NULL)
{
MyJavaWrapper::clazz = JVMWrapper::env->FindClass("mathias/jni/java/MyJavaClass");
MyJavaWrapper::initMethodId = JVMWrapper::env->GetMethodID(MyJavaWrapper::clazz, "", "()V");
}
}
[/code]

C'est la dedans que j'obtiens une fois pour toute la représentation de la classe Java mathias.jni.java.MyJavaClass et la représentation de la méthode <init> avec en paramètre ()V.
Pour comprend le lien avec la classe, il n'y a pas trop de problème: c'est le fully qualified name avec des '/' au lieu des '.'.
Mais en ce qui concerne la recherche d'une méthode, ça devient du charabia!!
En fait, <init> est une méthode un peu spéciale: c'est un constructeur.
Ensuite, on spécifie les arguments du constructeur que l'on cherche, et la on tombe sur une syntaxe barbare. Dans notre cas, on cherche le constructeur par défaut c'est à dire qui ne prend pas d'argument.
Mais pour mieux comprendre la syntaxe barbare, voyons d'autres exemples de méthodes:
[code language='cpp']
JVMWrapper::env->GetMethodID(MyJavaWrapper::clazz, "setPeople", "(Ljava/lang/String;)V");
[/code]
Traduction: je cherche la méthode setPeople qui prend un argument de type java.lang.String et qui retourne void.
Un autre exemple:
[code language='cpp']
JVMWrapper::env->GetMethodID(MyJavaWrapper::clazz, "sayHello", "([Ljava/lang/String;Z;)I");
[/code]
Traduction: je cherche la méthode sayHello qui prend un argument de type java.lang.String[] et un autre de type boolean et qui retourne un type int.

On retrouve cette syntaxe à beaucoup d'endroits, comme sous Eclipse par exemple. Pour plus d'explication voir la documentation officielle.

Si l'on veut maintenant appeler une méthode Java, on récupère sa représentation tout comme on le fait avec le constructeur, puis on l'invoque sur notre instance:
[code language='csharp']
public ref class MyJavaWrapper
{
private:
static jmethodID initMethodId;
static jclass clazz;

// notre représentation JNI de la méthode "sayHello"
static jmethodID sayHelloMethodId;

jobject obj;
public:
/* initialisation des métadata Java/JNI */
static void initJavaMetadata()
{
/* initialisation de la classe et du constructeur, comme vu précédemment
[...] */

// on récupère la représentation de "sayHello"
JVMWrapper::env->GetMethodID(MyJavaWrapper::clazz, "sayHello", "(Ljava/lang/String;)Ljava/lang/String");
}

/* sur l'appelle de cette méthode .Net, on fait appelle à la méthode Java */
String^ SayHello(String^ people)
{
// j'utilise une classe spéciale pour convertir ma String^ .net en natif ou Java
StringConverter peopleStringConverter(people);
jstring jPeople = peopleStringConvert.toJava();

// appelle de la méthode Java, j'ai le droit de caster en jstring car c'est un sous-type de jobject
jstring jResult = (jstring)JVMWrapper::env->CallObjectMethod(this->obj, sayHelloMethodId, jPeople);

// conversion du type Java en .Net
StringConverter resultStringConvert(jResult);
return resultStringConvert.toDotnet();
}
};
[/code]

Voila, maintenant vous savez:

• obtenir la représentation d'une classe Java
• obtenir la représentation d'une méthode d'une classe
• créer une instance d'une classe Java
• invoker des méthodes sur une instance

En conclusion:
l'API JNI c'est un peux comme utiliser la réflection. Ça a donc des conséquences en termes de performance. Pour information, créer 10000 objet en java prend 625ms, en pure .net ça donne 46ms et en .Net->JNI->Java ça donne 2.687s.
L'API JNI peut sembler barbare au début, mais on s'y fait :) et puis il y a la doc, alors RTFM ;).

C++/CLI c'est de la bombe en termes d'interop. C'est le pont parfait entre le monde .Net et le natif.
L'inconvénient c'est que la syntaxe C++ est lourde. Et elle l'est d'autant plus en C++/CLI car il faut y ajouter les spécificités .Net, et il faut aussi distinguer une instance managée et non-managée, et tout ça passe par de nouveau symboles/mots-clefs.
Les conversions de types entre les deux mondes ne sont pas faites implicitement, et il faut souvent jongler pour avoir le bon type. J'ai par exemple eu des problèmes lors des conversions de String avec JNI: il faut convertir la String^ .net en char* natif pour enfin construire une jstring. Les conversions ont été le plus pénible dans l'histoire.

Enfin, voici le projet complet: Mathias.Jni.CSharp.zip
Un petit rappel des liens utiles:

• http://dotnet.developpez.com/faq/cppcli/
• http://java.sun.com/j2se/1.4.2/docs/guide/jni/spec/jniTOC.html

When Google App Engine was released, there were immediately demands raised for support of other programming languages than Python. Developers wanted everything from Java and C# to Ruby and Scala.

Android is less than 6 months old, and just two weeks ago the great Android Developer Challenge was closed with more than 1700 submissions. Google achieved enormous interest in Android within the Java community. Not surprisingly, people started thinking about using other languages to develop apps on Android.

C/C++

Linux development in general is of course based on C and C++. Everything from kernel and its modules to windowed environments like GNOME and KDE to office applications is in most cases written in C/C++. The mobile world has also chosen C++ since it can provide best performance and memory usage what is so crucial in embedded environments. And since Android is in fact another Linux distro, an attempt of running native apps seems quite natural.

Aaron P. D’Souza described how to compile and run a tiny console program within emulator. Aaron used GNU/ARM Linux toolchain that can be downloaded here. Also Benno came up with similar solution.

Unfortunately, such native apps can't access all the cool features that make Android so special, since they are accessible only through Java framework. If you want mix C++ and Java but still send SMS messages, capture video or use location based services, you may however try to use JNI. Davanum Srinivas presents how to achieve this step by step. This way one can make part of his app partially native to gain performance, for instance in case he uses some unique audio/video coding algorithms or advanced math, and call it from Java through JNI.

There is however a lot of doubt about these attempts. Even a discussion arose on Google Groups. One of main concerns is such native code has to be compiled for every device out there that is going to run Android to make it fully supported. And Android was created to eliminate the need to recompile stuff. Hatem Ben Yacoub of Open Handset Magazine has addressed the issue here.

Python, Jython

There are some python scripts like activityCreator.py included within Android SDK. Moreover, we all know Python, along with Java, to be one of the most used languages by Google engineers. So, is it possible to write Python apps for Android?

First attempts of installing and running python snippets took Marcelo Barros de Almeida but he couldn't get it running. There is of course a problem that, just like native apps, such scripts couldn't use all the features without creating special bindings to Android API first.

Jython might be of help here, allowing to run Python scripts within JVM (or rather Dalvik VM) and transparently access API. hdante tried to use Jython on Android but it also appeared difficult.

Google used Apache Harmony project that reimplements all Java standard APIs. Unfortunately, Harmony hasn't complete implementation of Java reflection and there are java.beans.IntrospectionException thrown.

Ruby, JRuby and Groovy

The very same problem appears in repect to Ruby and JRuby. Also James Williams tried to bring Groovy to Android with no success. Here is some discussion.

Scala

It seems the only team to get a "foreign" language run on Android are the Scala guys. They even made a dedicated Android Target for their technology. There is a short description on how to get a Scala snippet running in the emulator.

Other BIG players

Sun must be quite worried Google thrown away their J2ME and made their own solution (Dalvik). Just as Sun tries a lot to get J2ME running on iPhone, we could wonder if they are going to try introducing JavaFX Mobile to Android in the future. Is Adobe going to make sure Flash runs in Android?

.NET and Mono communities are considering workarounds to allow running their code on Google's OS. Here are some ideas by now.

Google Gears and JavaScript

Google Gears brings the opportunity to develop desktop-like applications in JavaScript. Combined with GWT and run within Android's WebKit browser, it could grow in time to become another app platform. And since all modern handheld devices are equipped with AJAX-capable browsers, Gears+GWT tandem could let us create applications that run on more than Android: including iPhone, Windows Mobile and Symbian-based phones. There are successful attempts in bringing GWT to Android. Gears in mobile world is currently ported to Windows Mobile only but we can be pretty sure we shall see it in WebKit based browsers too. There are rumors that porting Gears to Safari has been already started.

Gears open up possibilities to use Dojo, JQuery, YUI, GWT and many more. It would also allow us to reuse code of our existing AJAX-enabled web apps straight into mobile version, thus reducing significantly its implementation time.

What about J2ME?

A frequent question that appears on various forums is how to run J2ME applications on Android. Since Android itself does not support Java ME, there are attempts to fill the gap. ME4SE is a project that aims to supplement SE with ME so J2ME software could be run in J2SE environment. Poliplus created ME4android that allows to port your J2ME application to Android.

Conclusion

Android uses Dalvik VM instead of JVM. Dalvik bytecode is incompatible with Java bytecode. It makes impossible to implement dynamic Class Loaders known in web development. For instance iJetty (Jetty port to Android) cannot load .war-packaged web apps on the fly. Apache Harmony isn't complete yet and since Android uses it, there are some significant problems so far. This all makes quite hard to port other languages and technologies to Android, though it is widely described to be noting but Linux and Java. This issues are said to be fixed soon but by that time any attempts to use other languages on Android may be impossible to succeed. It seems we are bound to Java for some time, we can give Scala a try or even start thinking about Gears. Gears could be in future the real "write-once-run-everywhere" solution, assuming of course that this "dream" is possible after all.

Some of the links I posted here are months old, so things might have changed by now. If anyone succeeded in porting other languages to Android, please let us know in comments.

Oke, sebelum mulai, pastikan sesajen berikut ini sudah terinstall di linux anda:
1. JDK, untuk compile kode java anda
2. gcc, beserta libc6 untuk compile kode C anda
3. Eclipse (optional), sebagai editor
Yak, cukup itu sajen yang diperlukan dalam ritual ini. Sebagain informasi saja, sajen yang terakhir sifatnya sunah. Anda boleh menggunakan editor lainnya.

Untuk mulai mencoba JNI, buat dulu source java anda sebagai berikut (file: NevNat.java):

package com.uki.coba;

public class NevNat {
static {
System.loadLibrary("nevnative");
}
public native void display() ;

public static void main(String[] args) {
NevNat nat = new NevNat();
nat.display();
}

}

Setelah jadi, simpan dan compile source java tersebut.

gue@linux:~$ javac com/uki/coba/NevNat.java

Hasil komipilasi file tersebut menghasilkan file NevNat.class. Abis itu, dari file NevNat.class dibikin file C headernya, caranya:

gue@linux:~$ javah com.uki.coba.NevNat

Hasilnya adalah file com_uki_coba_NevNat.h. Isinya:

/* DO NOT EDIT THIS FILE - it is machine generated */
#include <jni.h>
/* Header for class com_uki_coba_NevNat */

#ifndef _Included_com_uki_coba_NevNat
#define _Included_com_uki_coba_NevNat
#ifdef __cplusplus
extern "C" {
#endif
/*
* Class: com_uki_coba_NevNat
* Method: display
* Signature: ()V
*/
JNIEXPORT void JNICALL Java_com_uki_coba_NevNat_display
(JNIEnv *, jobject);

#ifdef __cplusplus
}
#endif
#endif

Nah, langkah selanjutnya adalah membuat source C yang mengimplementasi header tersebut.
Isinya sebagai berikut:
#include <jni.h>
#include "com_uki_coba_NevNat.h"
#include <stdio.h>

JNIEXPORT void JNICALL Java_com_uki_coba_NevNat_display
(JNIEnv *env, jobject obj) {
printf("Hello dab!\n");
return;
}

Kalo udah dibuat, tinggal compile

gcc -shared -I $JAVA_HOME/include/ -I $JAVA_HOME/include/linux/ NevNatImpl.c -o libnevnative.so


Trus, kalo udah kelas java tadi dijalankan aja

export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:.
gue@linux:~$ java com/uki/coba/NevNat


Hasilnya:
Hello dab!


http://www.devarticles.com/c/a/Java/Interacting-With-C-From-Java-With-JNI-Part-1/1/

I came across two open source projects Java Native Access( will be referred to as JNA) and JNative. I initially started with JNA and also came across a useful tutorial for the same. Unfortunately I tried developing access to other Windows API and came across issues such as procedure not found. I was unable to find a suitable way for mapping the native data types like LPTSTR or LPDWORD.

After spending some frustrating hours I gave up and started with JNative. Using JNative is a breeze especially since
the project provides sample implementations for standard Windows DLLs like kernel32, GDI32, User32, Advapi32 etc.
These implemenation classes act as references for custom implementations. All in all I am for JNative project for abstracting Java Native access.

Como todos os frameworks JNI também tem as suas implicações, o uso do JNI coloca em risco dois benefícios da plataforma Java. Primeiro as aplicações Java que utilizam JNI ficam dependentes do ambiente de execução, contrário de Java puro que pode ser executado em múltiplos ambientes com JNI a parte nativa tem de ser recompilada em cada um dos ambientes de execução, perdendo a portabilidade do Java. Segundo a linguagem de programação Java é uma linguagem type-safe e segura, ao contrario das linguagens nativas como C ou C++ que não são seguras.

Por estas razões o uso de JNI deve ser feito de forma cuidada e apenas caso não seja possível implementar apenas com a linguagem Java.
Depois desta breve introdução vamos passar então à prática, vamos ver quais os passos necessários para a criação de um programa em Java com JNI.

Depois de vermos o percurso a percorrer vamos começar com a implementação da classe HelloWorld.java

1 public class HelloWorld{
2
3	private native void print();
4
5	public static void main(String args[]){
6      		new HelloWorld().print();
7	}
8
9	static{
10     		System.loadLibrary("HelloWorld");
11 	}
12 }

Na linha 3 foi declarado o método nativo print e nas linhas 9 e 10 é dito ao Java para carregar o biblioteca “HelloWorld”, que vamos criar depois de realizar mais alguns passos. Em seguida vamos compilar a classe criada : javac HelloWorld.java.
Depois de obtermos o ficheiro HelloWorld.class vamos usar a ferramenta javah do Java para criar o ficheiros header (HelloWorld.h), com o comando javah -jni HelloWorld vamos obter o ficheiro HelloWorld.h com o seguinte conteúdo.

1 /* DO NOT EDIT THIS FILE - it is machine generated */
2	#include <jni.h>
3	/* Header for class HelloWorld */
4
5	#ifndef _Included_HelloWorld
6	#define _Included_HelloWorld
7	#ifdef __cplusplus
8	extern "C" {
9	#endif
10	/*
11	* Class:     HelloWorld
12 	* Method:    print
13 	* Signature: ()V
14 	*/
15	JNIEXPORT void JNICALL Java_HelloWorld_print (JNIEnv *, jobject);
16
17	#ifdef __cplusplus
18	}
19	#endif
20	#endif

Como podemos ver na linha 15 é declarado o header para o método nativo que iremos implementar, vamos usar essa header para criar o ficheiro de código nativo (HelloWorld.c), como podemos ver em seguida.

Na linha 3 foi declarado o método nativo print e nas linhas 9 e 10 é dito ao Java para carregar o biblioteca “HelloWorld”, que vamos criar depois de realizar mais alguns passos. Em seguida vamos compilar a classe criada : javac HelloWorld.java.
Depois de obtermos o ficheiro HelloWorld.class vamos usar a ferramenta javah do Java para criar o ficheiros header (HelloWorld.h), com o comando javah -jni HelloWorld vamos obter o ficheiro HelloWorld.h com o seguinte conteúdo.

1 /* DO NOT EDIT THIS FILE - it is machine generated */
2	#include <jni.h>
3	/* Header for class HelloWorld */
4
5	#ifndef _Included_HelloWorld
6	#define _Included_HelloWorld
7	#ifdef __cplusplus
8	extern "C" {
9	#endif
10	/*
11	* Class:     HelloWorld
12 	* Method:    print
13 	* Signature: ()V
14 	*/
15	JNIEXPORT void JNICALL Java_HelloWorld_print (JNIEnv *, jobject);
16
17	#ifdef __cplusplus
18	}
19	#endif
20	#endif

Como podemos ver na linha 15 é declarado o header para o método nativo que iremos implementar, vamos usar essa header para criar o ficheiro de código nativo (HelloWorld.c), como podemos ver em seguida.

1 include <jni.h>
2	#include <stdio.h>
3	#include "HelloWorld.h"
4
5	JNIEXPORT void JNICALL Java_HelloWorld_print(JNIEnv *env, jobject obj){
6        		printf("Hello World!\n");
7        		return;
8	}

Se observar-mos vamos ver que a linha 15 do ficheiro HelloWorld.h é praticamente igual ao código na linha 5 do ficheiro HelloWorld.c.
Agora que já dispomos de todos os ficheiros necessários “HelloWorld.java”, “HelloWorld.class”, “HelloWorld.h” e “HelloWorld.c” vamos criar a nossa biblioteca nativa. Vamos ver como o fazer em diferentes sistemas operativos.

Linux com GCC

gcc -fPIC -I jdk/include -I jdk/include/linux -shared -o libHelloNative.so HelloNative.c

Solaris com Sun Compiler

cc -G -I jdk/include -I jdk/include/solaris -o libHelloNative.so HelloNative.c

Windows com MS C++ Compiler

cl -I jdk\include -I jdk\include\win32 -LD HelloNative.c -FeHelloNative.dll

Onde jdk é o caminho para a pasta de instalação do Java.

Vamos agora ver como realizar a passagem de dados entre Java e C através do JNI. Para isso criamos um pequeno programa em que vamos imprimir uma pergunta, usar a função scanf do C para recolher o input e retorná-lo para o Java como um Objecto String. Para isso vamos começar claro pela criação do ficheiro Prompt.java.

1 public class Prompt{
2	private native String getLine(String prompt);
3
4	public static void main(String args[]){
5		Prompt p = new Prompt();
6		String input = p.getLine("Qual o seu nome ? ");
7		System.out.println("Escreveu : "+input);
8	}
9
10	static{
11		System.loadLibrary("Prompt");
12	}
13 }

Em seguida vamos gerar o ficheiro Prompt.h que irá conter algo semelhante a este:

1 /* DO NOT EDIT THIS FILE - it is machine generated */
2	#include <jni.h>
3	/* Header for class Prompt */
4
5	#ifndef _Included_Prompt
6	#define _Included_Prompt
7	#ifdef __cplusplus
8	extern "C" {
9	#endif
10	/*
11	* Class:     Prompt
12	* Method:    getLine
13	* Signature: (Ljava/lang/String;)Ljava/lang/String;
14	*/
15	JNIEXPORT jstring JNICALL Java_Prompt_getLine(JNIEnv *, jobject, jstring);
16
17	#ifdef __cplusplus
18	}
19	#endif
20	#endif

Até aqui não há nada de novo relativamente ao HelloWorld implementado anteriormente, as novidades então agora na implementação do ficheiro Prompt.c que vai conter algumas novidade ao nível de JNI e no tratamento de Strings em JNI-C. Vamos então implementar o seguinte código.

1 #include <stdio.h>
2 #include <jni.h>
3 #include "Prompt.h"
4
5 JNIEXPORT jstring JNICALL Java_Prompt_getLine(JNIEnv *env, jobject obj, jstring prompt){
6
7	char buf[128];
8	const jbyte *str;
9
10	str = (*env)->GetStringUTFChars(env,prompt,NULL);
11
12	if(str == NULL){
13		return NULL;
14	}
15
16	printf("%s",str);
17	(*env)->ReleaseStringUTFChars(env,prompt,str);
18	scanf("%s",buf);
19	return (*env)->NewStringUTF(env,buf);
20 }

Como podemos ver na linha 5 nos argumentos do método para além das variáveis de ambiente que por defeito são colocadas, neste caso foi adicionada mais uma a variável prompt do tipo jstring que corresponde à String dada como argumento da classe Java. Como o C não tem o Objecto String como o Java vamos ter de passar a String para outra forma trabalhável em JNI-C, para isso é criada uma variável apontador do tipo jbyte, que de uma forma básica é o byte do JNI da mesma forma que o jstring é a String do JNI. O passo final para fazer a conversão é usar a função do JNI GetStringUTFChar que retorna uma cópia da String dada no segundo argumento (linha 10) e assim a variável str vai ficar com o valor da String dado como argumento ao método getLine.
Depois deste procedimento basta utilizar a função printf do C para imprimir a String e para terminar o processamento da String vamos usar a função ReleaseStringUTFChars (linha 17) que vai libertar a memória usada para guardar a String, atenção que este método apenas deve ser utilizado depois de terem terminado todas as operações na String.
Vamos agora para finalizar o nosso programa capturar o input do utilizador através da função scanf (linha 18) e guardar o input sob a forma de String no array de char definido na linha 7, em seguida basta converter o array de char para um Objecto String e retorná-lo para o Java, para isso vamos usar a função NewStringUTF como podemos ver na linha 19. Ao executar este exemplo o que vai acontecer será um intercâmbio de dados bastante simples, o Java envia uma String que é impressa pelo C, em seguida a função scanf vai capturar o input do utilizador e irá retornar esse input para o Java que o irá imprimir com o método println().

Passamos agora ao tratamento de arrays de Java para C, para isso vamos implementar o seguinte código.

1 public class IntArray{
2
3	private native int sumArray(int [] arr);
4
5	public static void main(String args []){
6		IntArray p = new IntArray();
7		int arr[] = new int[10];
8		for(int i = 0; i < 10; i++){
9			arr[i] = i;
10		}
11		int sum = p.sumArray(arr);
12		System.out.println("sum = "+ sum);
13	}
14
15	static{
16		System.loadLibrary("IntArray");
17	}
18 }

Como podemos ver o código implementado vai criar um array com 10 posições e vai preenche las com os números de 0 a 9, em seguida vai executar o método nativo sumArray que vai somar todos os valores presentes no array e vai retornar o total da soma. Vamos agora passar à implementação do método nativo e para isso vamos começar como sempre por gerar o ficheiro IntArray.h.

1 /* DO NOT EDIT THIS FILE - it is machine generated */
2	#include <jni.h>
3	/* Header for class IntArray */
4
5	#ifndef _Included_IntArray
6	#define _Included_IntArray
7	#ifdef __cplusplus
8	extern "C" {
9	#endif
10	/*
11	* Class:     IntArray
12 	* Method:    sumArray
13 	* Signature: ([I)I
14 	*/
15	JNIEXPORT jint JNICALL Java_IntArray_sumArray(JNIEnv *, jobject, jintArray);
16
17	#ifdef __cplusplus
18	}
19	#endif
20	#endif

Ao vermos os argumentos do método podemos verificar que está agora presente um jintArray que corresponde ao array de inteiros do Java que é dado como argumento na chamada do método. Agora o código nativo do nosso método.

1 #include <jni.h>
2 #include <stdio.h>
3 #include "IntArray.h"
4
5 JNIEXPORT jint JNICALL Java_IntArray_sumArray(JNIEnv *env, jobject obj, jintArray arr){
6
7	jint *carr;
8	jint i = 0;
9	jint sum = 0;
10     carr = (*env)->GetIntArrayElements(</