Sous-programmes en C pour programmes Java

On utilise JNI : Java Native Interface (voir les liens).

1. Appel d'un sous-programme C dans une méthode Java

A. Le programme Java

La première étape consiste à créer le programme en Java, par exemple avec le nom de fichier : MaClasse.java
Déclarations (hors de toute méthode) :
native public static void procedure();
native indique que cette procédure ne sera pas écrite en java, mais proviendra d'une bibliothèque externe.
static { System.loadLibrary( "biblio" ); }
La procédure loadLibrary va essayer de charger le fichier libbiblio.so qui est une bibliothèque linux (voir ci-dessous comment la construire).
La syntaxe static { ... } permet d'exécuter ce bloc d'instructions dès le chargement de la classe MaClasse sans attendre l'exécution d'une quelconque méthode.
L'appel en java s'écrit comme si la procédure était écrite en Java : procedure();
La compilation se fait comme pour n'importe quelle classe Java :

javac MaClasse.java

qui génère le fichier MaClasse.class.

B. L'entête en C

La deuxième étape consiste à générer un fichier .h qui pourra être ensuite inclus dans le fichier .c qu'on veut développer pour assurer une communication entre les mondes Java et C.

La commande

javah MaClasse

génère automatiquement le fichier MaClasse.h suivant (les #if ... ont été retirés) :

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

/*
 * Class:     MaClasse
 * Method:    procedure
 * Signature: ()V
 */
JNIEXPORT void JNICALL Java_MaClasse_procedure
  (JNIEnv *, jclass);

Remarques sur ce fichier .h :
- javah MaClasse ne fonctionne que si MaClasse.class existe.
- Le nom de la procédure a quelque peu changé : il a été préfixé par Java puis par le nom de la classe.
- On retrouve le type de retour void entre JNIEXPORT et JNICALL qui sont deux mots définis par l'environnement JNI pour faire communiquer Java et C.
- 2 paramètres ont été ajoutés : l'environnement de communication Java/C et la classe.
- Pour chaque sous-programme déclaré native en Java, on trouvera un tel prototype dans le fichier .h .

C. Sous-programme en C

La troisième étape consiste à créer le module en C par exemple dans un nouveau fichier "biblio.c"
Y inclure "MaClasse.h"
Y recopier les prototypes de MaClasse.h
Donner des noms aux paramètres : env, cla, etc...
Remplacer le ; final par un corps : { instructions }
Compiler (sans édition de liens) ce programme en remplaçant dans la commande de compilation habituelle -ansi par -std=c99 et en ajoutant :

-Irép-Irép/linux

où rép est le répertoire d'installation par le JDK des includes JNI (voir INCDIR dans le makefile typique ci-dessous).

D. Création de la bibliothèque

La quatrième étape consiste à générer la bibliothèque "partagée" qui sera chargée par le programme Java. Le nom de fichier doit être de la forme "lib*.so"
Ne pas construire un exécutable, mais une bibliothèque de sous-programmes (chargeable dynamiquement) ; l'édition de liens est donc différente :

gcc -Wall -shared -o libbiblio.so biblio.o
Le fichier libbiblio.so ainsi généré correspond au nom "biblio" indiqué en Java dans l'appel à loadLibrary() .
Sous Windows, il se serait appelé BIBLIO.DLL .

E. Exécution

La dernière étape consiste à exécuter ce programme multi-langage.
Avant la première exécution, il faut taper la commande :

setenv LD_LIBRARY_PATH .

pour dire à la machine virtuelle Java d'aller chercher la bibliothèque dans le répertoire courant.
Ensuite, l'exécution se lance comme habituellement :

java MaClasse
Les seuls fichiers nécessaires à l'exécution sont : MaClasse.class et libbiblio.so .
(les seuls fichiers à conserver pour pouvoir tout reconstruire sont : MaClasse.java et biblio.c).

F. Exemple complet

MaClasse.java biblio.c

`MaClasse.java`	`biblio.c`
// MaClasse.java public class MaClasse { static { System.loadLibrary( "biblio" ); } native public static void cProcedure(); public static void main( String [] args ) { System.out.println( "affichage java" ); cProcedure(); } // main() } // Java2C	/* biblio.c / #include <stdio.h> #include "MaClasse.h" JNIEXPORT void JNICALL Java_MaClasse_cProcedure ( JNIEnv env, jclass cla ) { printf( "affichage c\n" ); } /* ..._cProcedure() */

// MaClasse.java
public class MaClasse
{
    static { System.loadLibrary( "biblio" ); } 

    native public static void cProcedure(); 

    public static void main( String [] args )
    {
        System.out.println( "affichage java" );
        cProcedure();
    } // main()
} // Java2C

/* biblio.c */
#include <stdio.h>
#include "MaClasse.h"

JNIEXPORT void JNICALL Java_MaClasse_cProcedure
  ( JNIEnv * env, jclass cla )
{
    printf( "affichage c\n" );
} /* ..._cProcedure() */

2. `makefile` typique de communication Java/C : à télécharger (pas de copier/coller !)

CLASSE = MaClasse
PROGC  = biblio
#
# adapter la ligne ci-dessous en fonction du PC
INCDIR = /usr/lib/jdk1.5.0v9/include
#INCDIR = /usr/java/j2sdk1.4.2/include
#
CFLAGS = -std=c99 -pedantic -W -Wall
IFLAGS = -I$(INCDIR) -I$(INCDIR)/linux
LFLAGS = -shared

all : $(CLASSE).class lib$(PROGC).so 

%.class : %.java
        javac $<
        javah $(basename $<)

%.c : %.h
        touch $@

%.o : %.c
        gcc $(CFLAGS) $(IFLAGS) -o $@ -c $<

lib%.so : %.o
        gcc $(LFLAGS) -o $@  $<
        @echo ____________________ Tapez la ligne suivante avant la premiere execution :
        @echo ____________________ setenv LD_LIBRARY_PATH .

#.SECONDARY : $(PROGC).o

TOCLEAN = $(CLASSE).h $(PROGC).o *~
clean :
        rm -f $(TOCLEAN)
cleanall :
        rm -f lib$(PROGC).so $(CLASSE).class $(TOCLEAN)

Les lignes commençant par # sont des commentaires.
Il suffit de taper make pour reconstruire le programme.
Il est possible de taper make clean pour supprimer les fichiers inutiles, ou make cleanall pour ne conserver que les sources.
La seule chose à modifier est le nom de la classe et le nom du programme C au début du fichier, et éventuellement la valeur de INCDIR en fonction du PC sur lequel on travaille.

3. Échange de données entre Java et C

A. Récupérer les paramètres Java dans une procédure en C

1^er paramètre : env
donne l'accès à l'environnement java et à plusieurs fonctions d'interface entre Java et C.
Ces fonctions sont appelées par une instruction du type : (*env)->NomFonction( env, autres paramètres de la fonction );
2^ème paramètre : cla
- Pour accéder à un attribut statique de la classe Java qui appelle la procédure C :
  jfieldID fid = (*env)->GetStaticFieldID( env, cla, "nomAttribut", "code du type de l'attribut" );
  jint i = (*env)->GetStaticIntField( env, cla, fid ); (si le code était "I")
  jfieldID est un type défini pour contenir un numéro d'identification de chaque attribut d'une classe (ou d'un objet), et jint est le type C correspondant au type int en Java (voir type primitif : ci-dessous).
  Voir le tableau des codes des différents types Java (chercher "Java VM Type Signatures") et ce tutoriel de Sun.
- Pour accéder à une méthode statique de la classe Java qui appelle la procédure C :
  jmethodID mid = (*env)->GetStaticMethodID( env, cla, "nomMethode", "signature codée de la méthode" );
  (*env)->CallStaticVoidMethod( env, cla, mid, paramètres de la procédure );
  Voir le tableau des codes des différents types Java (chercher "Forming the Method Name and Method Signature") et ce tutoriel de Sun.
3^ème paramètre (et suivants), 4 possibilités :
- type primitif : si type en Java, alors jtype en C
  Voir le tableau de correspondance entre Java et C pour les types primitifs.
- type objet : jobject (Soit jo le nom de ce paramètre.)
  - Pour accéder à la classe de jo :
  jclass cls = (*env)->GetObjectClass( env, jo );
  - Pour accéder à un attribut de jo :
  jfieldID fid = (*env)->GetFieldID( env, cls, "nomAttribut", "code du type de l'attribut" );
  jint i = (*env)->GetIntField( env, jo, fid ); (si le code était "I")
  jstring js = (*env)->GetObjectField( env, jo, fid ); (si l'attribut était de type String ; voir type String : ci-dessous)
  - Pour accéder à une méthode de l'objet jo :
  jmethodID mid = (*env)->GetMethodID( env, cls, "nomMethode", "signature codée de la méthode" );
  int i = (*env)->CallIntMethod( env, jo, mid, paramètres de la fonction entière );
  ou (*env)->CallVoidMethod( env, jo, mid, paramètres de la procédure );
- type String : jstring en C
  Le code du type est : Ljava.lang.String;
  Problème de conversion entre les caractères Unicode sur 16 bits en Java et les caractères ASCII sur 8 bits en C :
  const char *cs = (*env)->GetStringUTFChars( env, js, NULL );
  pour convertir une String Java en chaîne de caractères C.
  (*env)->ReleaseStringUTFChars( env, js, cs );
  pour dire au Garbage Collector de Java qu'il peut récupérer la mémoire allouée pour cs.
  Voir également ce tutoriel de Sun.
- type tableau :
  Le code du type commence alors par [ et se termine par le code du type des éléments du tableau.
  Exemples : [I pour un tableau d'entiers et [Ljava.lang.String; pour un tableau de String
  Voir les fonctions spécifiques aux tableaux dans ce tutoriel de Sun.

B. Valeur de retour d'une fonction C, pour la récupérer en Java

type primitif : return variable ;
variable doit être d'un type jtypeJava
type String : return (*env)->NewStringUTF( env, cs );
cs est une chaîne de caractères C et cette fonction retourne une jstring

A COMPLETER

4. Pour en savoir plus :

Tutoriel JNI de Sun
Livre JNI de Sun
Spécification des fonctions JNI
Autres ressources de Sun
Cours JNI en français
Cours JNI de Jean-Michel DOUIN (CNAM Paris)