Acesso ao c�digo nativo usando JNA (Java Native Access)

Introduç�o

O ecossistema Java prov� centenas de frameworks e API�s para as mais diversas finalidades, sendo essa uma das caracter�sticas que torna Java uma das linguagens mais utilizadas do mundo. Por�m, existem certas situaç�es que podem exigir que os desenvolvedores acessem c�digo nativo para realizar determinadas tarefas. Os principais motivos s�o:

Reescrever c�digo legado (de outra linguagem) leva tempo, e talvez fosse mais interessante acess�-lo diretamente;
Quest�es de desempenho;
Acesso a drivers e API�s fornecidos atrav�s de DLL�s e Shared Libraries;
N�o h� biblioteca similar em Java.

Para isso, a Oracle disponibiliza a API JNI, que permite acessar c�digo nativo a partir de aplicaç�es Java. O problema do JNI � que ele � extremamente complexo, exige do programador certo conhecimento de C/C++, al�m de ser algo realmente enfadonho de se programar.

Felizmente, existe uma alternativa a altura, o framework JNA (Java Native Access), que abstrai as quest�es mais complexas do JNI e torna a integraç�o entre c�digo nativo e Java muito mais leve e produtiva.

Configurando o JNA

Os c�digos desse artigo podem rodar tanto no Netbeans como no Eclipse. A vers�o do JNA a ser utilizada � a 3.3.0.

Links: http://java.net/projects/jna/downloads/directory/3.3.0.

Jars: jna.jar e plataform.jar.

O jna.jar prov� toda a infraestrutura necess�ria para acesso a c�digo nativo, enquanto o plataform.jar prov� diversas facilidades, como mapeadores para funcionalidades amplamente usados em v�rias plataformas, como funç�es Win32, X11, etc.

Nesse artigo trabalharemos com o Linux, mas os conceitos abordados servem para o sistema Windows tamb�m.

Acessando funç�es nativas em Linux

No Linux (ser� utilizado o Ubuntu 12.04 � 32 bits), faremos uso do compilador gcc para compilar um programa que faz uso das funç�es printf e atoi. (se o gcc n�o estiver instalado, � s� fazer uso do bom e velho apt-get).

Listagem 1: Hello World em C usando printf e atoi


#include <stdio.h>

int main() {

  int ano = atoi("2012");
  printf("Hello [%s] [%d] \n", "World", ano);
  return 0;
}

Listagem 2: Para compilar e executar o programa


 - Compilando e gerando o execut�vel helloWorld:
 gcc -o helloWorld HelloWorld.c
 
 - Executando:
 ./helloWorld

 Sa�da: 
  Hello [World] [2012]

Nota: printf - utilizado para formatar e imprimir diversos tipos de dado
atoi � utilizado para converter string (terminadas com NULL) em n�mero inteiro

Veremos agora como utilizar as funç�es printf e atoi diretamente no c�digo Java.

Nota: Os exemplos abaixo n�o rodaram corretamente utilizando o OpenJDK. Foi necess�rio instalar a vers�o 1.6.0_37 do jdk da Oracle (32-bits).

Listagem 3: Interface CLibrary


package br.com.devmedia.jna;

import com.sun.jna.Library;

public interface CLibrary extends Library {
    void printf(String format, Object... args);
    int atoi(String value);
}

Toda funç�o nativa que desejamos usar, no nosso caso printf e atoi, deve ser declarada numa interface que estende com.sun.jna.Library do JNA. Isso � pre-requisito para que o JNA consiga descobrir e carregar essas funç�es internamente.

Observe como s�o declarados os prot�tipos das funç�es em C e os m�todos correspondentes em Java:

Listagem 4: M�todos em Java


    void printf(String format, Object... args);
    int atoi(String value);

Listagem 5: M�todos em C


    int printf (__const char *__restrict __format, ...); - arquivo /usr/include/stdio.h
    int atoi (__const char *__nptr); - arquivo /usr/include/stdio.h

Podemos fazer as seguintes associaç�es:

Java	C
String	const char*
Object...	...
int	int

Nota: apesar de retornar int, podemos ignorar o valor de retorno de printf. Por isso foi usado o void na declaraç�o do m�todo em Java.

Na documentaç�o do JNA, encontra-se a tabela de mapeamento de tipos entre Java e C:

Listagem 6: Classe CLibraryFunctions


package br.com.devmedia.jna;

import com.sun.jna.Native;

public final class CLibraryFunctions {
    
    private CLibrary cLibraryInstance;
    
    public CLibraryFunctions() {
        cLibraryInstance = (CLibrary)Native.loadLibrary("c", CLibrary.class);
    }

    public void printf(String format, Object... args) {
        cLibraryInstance.printf(format, args);
    }    
    
    public int atoi(String data) {
        return cLibraryInstance.atoi(data);
    }    
}

Depois de declarar as funç�es nativas a serem utilizadas, devemos informar ao JNA qual biblioteca din�mica possue as funç�es. Para isso utilizamos a classe Native.

A classe Native possue o m�todo loadLibrary, que recebe como argumentos o nome da lib (Shared Library) que queremos usar e a interface com os m�todos que queremos acessar dentro da Shared Library (definidas na classe CLibrary). O retorno dela � um Object, o que obriga a convers�o de tipo para a interface CLibrary.

A lib utilizada foi a libc.so (especificamente no meu caso: /lib/i386-linux-gnu/libc.so.6). O m�todo loadLibrary utiliza uma convenç�o. Ao passarmos qualquer nome de Shared Library no primeiro argumento, ela ir� adicionar o prefixo "lib" e o sufixo ".so" no nome, portanto ao passar "c" como argumento, temos: "libc.so".

A t�tulo de curiosidade, podemos verificar se a libc possue os m�todos prinft e atoi. Para isso, basta executar o seguinte comando:

nm -D /lib/i386-linux-gnu/libc.so.6 | egrep -ie " printf|atoi"

Cuja sa�da �:

00031620 T atoi
0004ced0 T printf
0004c6f0 T printf_size
0004ce70 T printf_size_info

Uma vez recuperado o objeto (que implementa a interface passada como argumento), podemos utiliz�-lo para chamar as funç�es nativas.

Listagem 7: Classe JNAHelloWorld


package br.com.devmedia.jna;

public class JNAHelloWorld {

    public static void main(String[] args) {
        CLibraryFunctions cLib = new CLibraryFunctions();
        int ano = cLib.atoi("2012");
        cLib.printf("Hello [%s] [%d]", "World", ano);
    }
}

Listagem 8: Sa�da da classe JNAHelloWorld


Hello [World] [2012]

Temos ent�o a sa�da da execuç�o do programa, o que demonstra que realmente acessamos as funç�es printf e atoi da libc.so.

Trabalhando com funç�es que usam Callback

V�rias funç�es em C recebem como par�metro um ponteiro de funç�o, que atua muitas vezes como uma funç�o de callback (similiar aos eventos do Java). Veremos como declarar funç�es callback no JNA.

Listagem 9: Capturando o CTRL+Z


#include <stdio.h>
#include <stdlib.h>
#include <signal.h>

void handler_SIGTSTP(int sig)
{
   printf("\nCTRL+Z pressionado\n");
   exit(1);
}
 
int main(void)
{   
   signal(SIGTSTP, handler_SIGTSTP);
   
   for( ; ; ) {
     // Loop infinito
   }
}

Compilando: gcc -o signal signal.c

Executando: ./signal

A funç�o signal do C permite que sinais do Linux (CTRL+Z, CTRL+C, sinais enviados pelo comando kill, etc) sejam capturados e manipulados pelo programa. Para isso basta passar como argumento o sinal que vai ser interceptado e a funç�o de callback que ser� executada quando o sinal vier (A constante SIGTSTP t�m valor 20, e indica que queremos capturar o sinal de CTRL+Z).

O programa ficar� executando o laço at� que o comando CTRL+Z seja pressionado. Quando isso acontece, a funç�o handler_ SIGTSTP � chamada, � feito um print na tela e depois o programa � finalizado.

Agora veremos como utilizar a funç�o signal em Java.

Listagem 10: Classe ClibraryFunctions com signal


package br.com.devmedia.jna;

import com.sun.jna.Callback;
import com.sun.jna.Library;

public interface CLibrary extends Library {

    void printf(String format, Object... args);
    int atoi(String value);
    
    public interface SignalFunction extends Callback {
        void invoke(int signal);
    }
    SignalFunction signal(int signal, SignalFunction func);    
}

Listagem 11: Classe CLibraryFunctionss


package br.com.devmedia.jna;

import com.sun.jna.Native;

public final class CLibraryFunctions {
   
    private CLibrary cLibraryInstance;
    
    public static int SIGTSTP = 20;
    
    public CLibraryFunctions() {
        cLibraryInstance = (CLibrary)Native.loadLibrary("c", CLibrary.class);
    }

    public void printf(String format, Object... args) {
        cLibraryInstance.printf(format, args);
    }    
    
    public int atoi(String data) {
        return cLibraryInstance.atoi(data);
    }    
    
    public void signal(int signal, CLibrary.SignalFunction sf) {
        cLibraryInstance.signal(signal, sf);
    }        
}

Listagem 12: Classe de teste


package br.com.devmedia.jna;

public class JNAHelloWorld {
    
    public static void main(String[] args) {
        final CLibraryFunctions cLib = new CLibraryFunctions();
        int ano = cLib.atoi("2012");
        cLib.printf("Hello [%s] [%d]\n", "World", ano);
        
        // Registrando "listener" para o CTRL+Z
        cLib.signal(CLibraryFunctions.SIGTSTP, new CLibrary.SignalFunction() {
            @Override
            public void invoke(int signal) {
                cLib.printf("CTRL+Z pressionado");
                System.exit(1);
            }
        });
        
        // Loop infinito
        while (true) {}
    }
}

A novidade no c�digo � essa:

Listagem 13: Novidade no c�digo


    public interface SignalFunction extends Callback {
        void invoke(int signal);
    }
    SignalFunction signal(int signal, SignalFunction func);

A funç�o signal em C tem essa declaraç�o:

Listagem 14: Declaraç�o da funç�o em C


void (*signal(int sig, void (*func)(int)))(int);

Ou seja, ela aceita no segundo argumento, um ponteiro de funç�o que n�o retorna nada(void), e cujo argumento deve ser um valor inteiro. A funç�o signal tamb�m retorna um ponteiro de funç�o (retorno void e com um argumento int).

Por isso declaramos tanto o tipo de retorno, quanto o segundo argumento, como sendo do tipo SignalFunction, que estende a interface Callback e representa o ponteiro de funç�o utilizado pelo signal.

Al�m de estender Callback, devemos sempre declarar um m�todo p�blico com a quantidade (e tipo) de par�metros da funç�o em C.

O m�todo pode ter qualquer nome (n�o necessariamente invoke), o tipo de retorno pode ser diferente de void, a �nica restriç�o � que aja apenas um �nico m�todo p�blico declarado. Se houver mais de um m�todo p�blico, ser� lançada uma exceç�o em tempo de execuç�o.

Ao rodar a aplicaç�o dentro do Netbeans/Eclipse, talvez n�o seja poss�vel utilizar o CTRL+Z. Uma forma equivalente � enviar um sinal 20 (SIGTSTP) atrav�s do comando kill.

kill -20 <pid_do_processo_java>

Nota: Cuidado para n�o enviar o kill ao PID do processo do Netbeans/Eclipse.

Isso � o mesmo que efetuar CTRL+Z no seu programa. Com isso a mensagem "CTRL+Z pressionado" ser� impressa e o programa finalizado.

Trabalhando com Estruturas

Existem duas formas de se trabalhar com estruturas em C: por valor e por refer�ncia. Em Java, passagens por valor podem ser representadas por m�todos que recebem valores primitivos:

Listagem 15: Passagem por valor em Java


   int soma(int x, int y) {
      x = 2;
      y = 3;
      return x + y;
   }

   int x = 1;
   int y = 1;
   System.out.println("x + y = " + soma(x,y)); // imprime 5
   System.out.println("x = " + x);  // Imprime 1
   System.out.println("y = " + y);  // Imprime 1

Os valores impressos de x e y ser�o 1, mesmo eles tendo sido modificados dentro do m�todo. Isso porque eles foram passados por valor.

Listagem 16: Passagem por refer�ncia


   class Valores {
      public int x;
      public int y;
   }

   int soma(final Valores v) {
      v.x = 2;
      v.y = 3;
      return v.x + v.y;
   }
   
   Valores val = new Valores();
   val.x = 1;
   val.y = 1;
   System.out.println("x + y = " + soma(val)); // Imprime 5 
   System.out.println("val .x = " + val.x); // Imprime 2
   System.out.println("val .y = " + val.y); // Imprime 3

Nesse caso, � poss�vel alterar os valores x e y do objeto val. Isso � conhecido como passagem por refer�ncia. �lias, refer�ncias em Java s�o semelhantes a ponteiros em C.

Para passarmos objetos por refer�ncia em JNA estendemos a classe abstrata Structure. Para passar objetos por valor devemos trabalhar com Structure.ByValue.

Passando um Objeto por Valor

Criaremos uma shared library em C no Linux para demonstrar a passagem por valor.

Listagem 17: Shared Library (passagem por valor)


#include <stdio.h>
#include <stdlib.h>

typedef struct Retangulo {
  int base;
  int altura;  
} Retangulo;

int calculaBase(Retangulo ret) { // Passagem por valor
  return ret.base * ret.altura;
}

Nesse exemplo ser� criado uma shared libray (biblioteca din�mica) que cont�m a funç�o calculaBase, que recebe uma estrutura Retangulo por valor. Para compilar e gerar a lib, execute os seguintes comandos:

Compilando: gcc -fPIC -c Retangulo.c
Gerando shared library: gcc -shared -o libRetangulo.so Retangulo.o
Verificando se a funç�o calculaBase est� na lib: nm libRetangulo.so

Uma vez criada o libRetangulo.so (shared object), �remos criar o c�digo em Java para utilizar essa funç�o (calculaBase), passando uma classe Retangulo com os atributos base e altura, por valor.

Listagem 18: Interface IRetangulo (passagem por valor)


package br.com.devmedia.jna;

import com.sun.jna.Library;

public interface IRetangulo extends Library {

    // declaracao da funcao a ser utilizada dentro da lib
    int calculaBase(Retangulo.ByValue r);  // Estamos dizendo que a passagem sera por valor
}

Listagem 19:Classe Retangulo (passagem por valor)


package br.com.devmedia.jna;

import com.sun.jna.Structure;

// Seja por Valor ou Referencia, deve estender Structure
public class Retangulo extends Structure {
    
    public int base;
    public int altura;    

    // Inclui suporte a passagem por valor (ByValue)
    public static class ByValue extends Retangulo implements Structure.ByValue {}
}

Listagem 20: Classe de Teste (passagem por valor)


package br.com.devmedia.jna;

import com.sun.jna.Native;

public class TesteClasse {
     public static void main(String[] args) {  
         IRetangulo service = (IRetangulo) Native.loadLibrary("<path>/libRetangulo.so", IRetangulo.class);  
         Retangulo.ByValue r = new Retangulo.ByValue();  
         r.base = 30;  
         r.altura = 30;  
         System.out.println("Base = " + service.calculaBase(r));  // Sera 900
     } 
}

Para indicar que estamos passando a classe Retangulo por valor, ao inv�s de criar diretamente uma inst�ncia de Retangulo, criamos o objeto do tipo Retangulo.ByValue. Somente isso � necess�rio.

Se Retangulo.ByValue indica objetos que ser�o passados por valor, o leitor deve estar imaginando: se eu passar um objeto que � inst�ncia de Retangulo, a passagem ser� por refer�ncia? A resposta � sim.

Passando um Objeto por Refer�ncia

Modificaremos a biblioteca libRetangulo.so, para incluir uma outra funç�o que recebe um ponteiro da struct Retangulo.

Listagem 21: Shared Library (passagem por refer�ncia)


#include <stdio.h>
#include <stdlib.h>

typedef struct Retangulo {
  int base;
  int altura;  
} Retangulo;

// Por valor
int calculaBase(Retangulo ret) {
  return ret.base * ret.altura;
}  

// Por referencia
int transformaEmQuadrado(Retangulo* ret) {
  ret->base = ret->altura;
  return ret->base * ret->altura;
}

Regere a lib novamente conforme indicado anteriormente. A funç�o transformaEmQuadrado recebe um ponteiro de Retangulo (passagem por refer�ncia), e dentro dela copia o valor da altura para a base e calcula a �rea.

Veremos agora como passar o objeto Retangulo por refer�ncia em Java.

Listagem 22: Interface IRetangulo (passagem por refer�ncia)


package br.com.devmedia.jna;

import com.sun.jna.Library;

public interface IRetangulo extends Library {

    // declaracao das funcoes a serem utilizadas dentro da lib
    int calculaBase(Retangulo.ByValue r);  // Estamos dizendo que a passagem sera por valor
    int transformaEmQuadrado(Retangulo r); // Passagem por refer�ncia
}

Listagem 23: Classe de Teste (passagem por refer�ncia)


package br.com.devmedia.jna;

import com.sun.jna.Native;

public class TesteClasse {
      public static void main(String[] args) {  
         IRetangulo service = (IRetangulo) Native.loadLibrary("<path>/libRetangulo.so", IRetangulo.class);  
         Retangulo.ByValue r = new Retangulo.ByValue();  
         r.altura = 10;  
         r.base = 30;  
         // Passagem por valor
         System.out.println("Base = " + service.calculaBase(r));  // Imprime 300
         System.out.println("r.base = " + r.base);  // Imprime  30
         System.out.println("r.altura = " + r.altura);  // Imprime 10
         
         Retangulo r2 = new Retangulo();  
         r2.altura = 10;  
         r2.base = 30;           
         // Passagem por referencia
         System.out.println("Base = " + service.transformaEmQuadrado(r2));  //Imprime 100
         System.out.println("r2.base = " + r2.base);  //Imprime 10
         System.out.println("r2.altura = " + r2.altura);  //Imprime 10
     } 
}

Conclus�o

A API JNA prov� uma s�rie de recursos para lidar com alocaç�o de mem�ria (atrav�s das classes Memory/Pointer), callbacks (Callback), structs (Struture), arrays, etc de uma forma bem mais simples do que o JNI. Utilizar JNA no Windows tamb�m � t�o simples quanto o que foi exposto nos exemplos acima. Com isso fechamos a an�lise dessa excelente biblioteca, que facilita a integraç�o entre c�digo nativo e a plataforma Java.

Obrigado pessoal e at� a pr�xima!