Java调用本地库的JNA快速入门教程

简介：JNA是一个开源库，它简化了Java代码调用操作系统API的过程，无需编写JNI代码。本文通过一个示例项目展示了如何使用JNA与C/C++编写的DLL交互，包括定义原生接口、数据类型映射、指针和引用的处理、结构体的使用以及异常处理等。项目包含DLL文件、JNA接口定义和主程序，帮助读者理解和实践JNA的使用。

1. JNA简介和优点

Java Native Access（JNA）是一个开源的Java库，它提供了直接在Java代码中调用本地（非Java）库功能的能力，而不必编写本地代码。它的主要优点在于大大简化了跨平台访问原生代码的复杂性，允许开发者专注于Java层的开发，同时复用已有的本地代码库。

1.1 JNA的应用场景

JNA广泛应用于需要与原生API交互的Java应用程序中，例如，当开发者需要访问操作系统级别的API或者调用一些老旧的本地库时，JNA提供了一个无缝接口。

import com.sun.jna.Native;
import com.sun.jna.Library;
import com.sun.jna.platform.win32.User32;
public class JNAExample {
    public interface CLibrary extends Library {
        CLibrary INSTANCE = Native.load("c", CLibrary.class);
        int MessageBox(int hWnd, String text, String caption, int type);
    }
    public static void main(String[] args) {
        CLibrary.INSTANCE.MessageBox(0, "Hello, world!", "JNA Example", 0);
    }
}

通过上述代码，我们在Java程序中直接调用了Windows平台的MessageBox函数。

1.2 JNA的优势

使用JNA的优势在于它提供了一种简洁的方式来调用原生库，无需借助JNI（Java Native Interface）编写复杂的本地代码。此外，JNA自带跨平台支持，无需为不同的操作系统编写不同的本地代码。这也意味着，作为Java开发者，可以更轻松地处理不同平台间差异带来的问题。

2. 定义Native Interface

2.1 接口基础

2.1.1 接口定义与Java类的关联

在Java Native Access (JNA) 中，定义Native Interface 是让Java程序能够调用本地代码的第一步。接口定义是通过Java中的接口（Interface）来完成的，这种接口与普通Java接口不同，它主要负责声明本地方法。与本地代码的关联通过注解 @Structure.FieldOrder 来实现，它指定了在结构体中字段的顺序，以确保Java能够按照正确的顺序将数据映射到本地代码中。

以下是一个简单的例子：

public interface MyNativeInterface extends Library {
    void myNativeFunction(int arg);
}

在这个例子中， MyNativeInterface 接口扩展了 Library 接口，允许它继承 load 方法，用于加载动态链接库。声明的 myNativeFunction 方法代表了将要在本地库中被调用的函数。为了使这个接口能够与本地库中的函数相对应，JNA 需要知道具体要调用的函数名称。这可以通过在接口中使用 @Function 注解来指定函数名称来实现。

2.1.2 接口方法映射到本地函数

在定义了接口之后，我们需要确保接口中的每个方法都映射到了正确的本地函数。这通常是通过JNA的注解来完成的，如 @Function 注解用于指定本地函数的名称。

public interface MyNativeInterface extends Library {
    void myNativeFunction(int arg);
    @Function(value="myNativeFunction")
    void theRealFunction(int arg);
}

在这个例子中， myNativeFunction 是Java接口中的方法名，而通过 @Function(value="myNativeFunction") 注解，我们告诉JNA这个Java方法对应于本地库中的函数 myNativeFunction 。

2.2 动态链接库的加载

2.2.1 库的加载过程

加载动态链接库（DLLs或.so文件）是使用JNA非常关键的一步。JNA通过 Library 接口中的 load 方法来加载动态链接库。 load 方法是一个静态方法，需要提供库名作为参数。例如，在Windows上，你可以通过 MyNativeInterface.INSTANCE.load("mylib") 来加载名为 mylib.dll 的库；在Linux上则是加载名为 libmylib.so 的共享库。

MyNativeInterface instance = Native.load("mylib", MyNativeInterface.class);

在这段代码中， instance 对象将代表加载的动态链接库，并且可以用来调用映射到Java接口的方法。

2.2.2 动态链接库的卸载

在JNA中，卸载动态链接库不像加载那样直接。通常，动态链接库在Java虚拟机（JVM）停止运行时会自动被卸载。但是，如果你需要在程序运行期间手动控制资源，可以通过平台相关的代码来实现库的显式卸载。

以Windows为例，可以通过调用 FreeLibrary 函数来卸载动态链接库，这需要使用 Kernel32 库。在JNA中，你可以这样做：

Kernel32 kernel32 = Native.load("kernel32", Kernel32.class);
boolean result = kernel32.FreeLibrary(MyNativeInterface.INSTANCE.getPointer());

在这段代码中， MyNativeInterface.INSTANCE.getPointer() 获取了动态链接库的句柄，并传递给 FreeLibrary 方法。需要注意的是，手动卸载库可能会导致不稳定的程序行为，特别是如果库中的某些资源还没有被释放或者正在被使用时。

以上内容介绍了定义Native Interface时需要进行的操作和注意事项。接下来的章节将讨论如何处理数据类型映射，以便能够在Java和本地代码之间安全有效地传递数据。

3. 数据类型映射规则

3.1 基本数据类型映射

3.1.1 原生Java类型与本地类型的对应关系

JNA（Java Native Access）框架的主要优势之一是在Java世界和本地世界之间提供了一种无缝的数据类型映射机制。原生Java类型映射到本地类型是JNA核心功能的基础，它保证了数据在Java和本地代码之间正确无误地传输。

在JNA中，Java的基本数据类型，例如 int 、 long 、 short 等，会自动映射到相应大小和精度的本地类型。对于浮点数， float 类型映射到本地的 float 类型，而 double 类型映射到本地的 double 类型。对于布尔类型，JNA使用 byte 类型（在C语言中为 bool 类型）来表示。

这种映射不是简单的一对一映射，它还考虑到了平台差异，比如在某些平台上 int 和 long 的大小可能不同。JNA的内部机制能够处理这些差异，确保无论在什么平台上，Java代码的编译和本地代码的编译都能正常进行。

public interface NativeLib {
    int add(int a, int b);  // Java int maps to native int
    long getLong();         // Java long maps to native long
    float getFloat();       // Java float maps to native float
    double getDouble();     // Java double maps to native double
}

3.1.2 字符串与字符数组的映射处理

在Java和C语言中处理字符串的方式有所不同。Java中字符串是对象，而在C语言中是字符数组。在JNA中，字符串映射通常使用 String 类型来处理。JNA提供了多种字符串处理选项，如使用 String 、 char[] 或者 WString （用于宽字符字符串，即 wchar_t[] ）等。

JNA处理字符串的方式取决于定义的Java方法签名以及目标本地库的字符串处理约定。比如，如果本地库期望一个以null结尾的UTF-8编码的字符串，那么相应的Java方法签名可能如下：

public interface NativeLib {
    String sayHello(String name); // Java String maps to null-terminated UTF-8 string in C
}

JNA会自动处理字符串到本地的转换，包括编码转换和添加空字符（null-termination）。

3.2 复杂数据类型映射

3.2.1 结构体的映射

JNA提供了复杂数据类型的映射能力，最典型的如结构体（struct）的映射。在Java中，结构体可以通过创建一个简单的接口来映射，JNA框架会处理好从Java对象到本地结构体的转换。

public interface MyStruct extends Structure {
    public static class ByValue extends MyStruct implements Structure.ByValue {}
    public static class ByReference extends MyStruct implements Structure.ByReference {}
    public int field1;
    public String field2;  // JNA will convert this to native string type
    @Override
    protected List<String> getFieldOrder() {
        return Arrays.asList("field1", "field2");
    }
}

在上面的代码示例中， MyStruct 是一个映射到本地结构体的接口， ByValue 和 ByReference 类型用于区分是通过值传递还是通过引用传递。JNA支持直接的结构体映射，结构体内的字段顺序需要通过 getFieldOrder 方法来显式指定，确保与本地结构体的布局一致。

3.2.2 数组和字符串的映射

数组的映射在JNA中比较直接。如果本地库需要接收一个数组参数，可以直接在Java接口中定义一个数组类型的参数。

public interface NativeLib {
    void processArray(int[] array);  // Java int[] maps to native int*
}

这里的 int[] 会被JNA自动映射到对应的本地指针类型 int* 。

字符串数组的映射稍微复杂一些，因为需要考虑字符串的编码以及数组结束的标识。JNA提供了 PointerByReference 或者 Structure 的数组来映射字符串数组，同时提供了 String[] 、 Pointer[] 和 byte[] 等不同的映射方式，以适应不同情况下对字符串数组的处理需求。

JNA通过灵活的映射机制和强大的类型转换能力，使得Java调用本地库的复杂数据类型变得简单直接，极大地降低了Java应用和本地代码交互的难度。

4. 指针和引用的处理方法

4.1 指针的使用

4.1.1 Java中的指针概念

在Java语言中，通常不直接使用指针这一概念，而是通过对象引用来操作对象。然而，在使用Java Native Access (JNA) 进行本地方法调用时，指针成为了不可回避的话题。在本地代码中，指针是访问内存的基础，而JNA提供了一种机制将这些指针映射回Java世界，使得Java程序能够与本地代码中的指针进行交互。

指针在JNA中的使用主要涉及Java中的 Pointer 类，这个类代表了一个指向原始数据的指针。JNA允许通过 Pointer 类的实例访问本地内存，可以将其看作是对原生指针的抽象封装。

4.1.2 指针类型的声明和操作

在JNA中，指针类型的声明非常直观，你可以直接使用 Pointer 类的实例作为参数传递给本地方法。操作指针主要包括获取和设置指针指向的内存数据，例如：

Pointer pointer = new Pointer(内存地址);
int value = pointer.getInt(0); // 获取指针指向的内存中偏移0位置的整数值
pointer.setInt(0, newValue); // 设置指针指向的内存中偏移0位置的整数值为newValue

此外， Pointer 类还提供了许多有用的方法来处理内存，比如 getString 和 setString 用于处理字符串， size 用于获取指针指向内存的大小等。

String str = pointer.getString(0); // 获取指针指向的内存中偏移0位置的字符串
pointer.setString(0, "newString"); // 设置指针指向的内存中偏移0位置的字符串为"newString"

指针的使用往往涉及到内存操作，所以在使用时需要格外小心，确保不会出现内存泄漏或者越界访问等问题。

4.2 引用的传递

4.2.1 引用类型数据的映射

在JNA中，引用通常表示为指针。传递引用可以允许本地方法修改Java对象的值，或者实现回调函数等高级特性。当需要传递引用时，我们通常使用 Pointer 类的实例来传递Java对象的引用。

public class MyObject {
    public int value;
}
public class NativeLib {
    public native void modifyByReference(Pointer reference);
}
NativeLib lib = NativeLoader.load(NativeLib.class);
MyObject obj = new MyObject();
Pointer ref = new Pointer(ByReference.Util.objectToHandle(obj));
lib.modifyByReference(ref);
// 之后可以通过obj.value获取修改后的值

在上面的例子中， ByReference.Util.objectToHandle 方法用于获取Java对象对应的本地引用，这样就可以在本地方法中对它进行操作。

4.2.2 引用在本地方法中的应用实例

引用的传递在本地方法调用中非常有用，尤其是在需要修改传递给本地方法的Java对象状态时。举个例子，假设有一个本地方法可以修改传入参数的值：

void incrementByPointer(int *value) {
    (*value)++;
}

在Java中，我们可以这样调用：

public class IncrementExample {
    static {
        Native.register("yourLibraryName");
    }
    public static void main(String[] args) {
        Pointer ptr = new Pointer(0); // 初始值为0
        incrementByPointer(ptr);
        System.out.println("Incremented value: " + ptr.getInt(0)); // 输出1
    }
    private static native void incrementByPointer(Pointer value);
}

在这个例子中， incrementByPointer 方法通过指针引用修改了指针指向的值。在Java代码中，我们使用 Pointer 类来传递引用，并在本地方法调用后通过 getInt 方法检索更新后的值。

引用的传递机制是JNA中非常重要的特性，它允许Java程序与本地代码之间有着更深层次的交互和数据共享。

5. 结构体的定义和使用

5.1 结构体的定义

5.1.1 Java中定义结构体的方式

在Java中，通常没有直接对应C语言中的结构体（struct）的概念。然而，Java Native Access（JNA）库提供了一种方式来模拟结构体的行为，这使得Java程序能够与本地代码进行交互。在JNA中，结构体是通过定义一个Java类来实现的，该类继承自 Structure 类，而且必须被声明为 public 和 abstract 。每个字段都必须在结构体类中声明，并使用 @Field 注解来标记其在内存中的位置。

以下是一个简单的结构体定义示例：

import com.sun.jna.Structure;
import com.sun.jna.ByReference;
public abstract class MyStruct extends Structure {
    @Field(0)
    public int field1;
    @Field(1)
    public double field2;
    @Override
    protected List<String> getFieldOrder() {
        return Arrays.asList("field1", "field2");
    }
    public MyStruct() {
        super();
    }
    public MyStruct(int size) {
        super(ByReference.class, size);
    }
}

在这个例子中，我们创建了一个名为 MyStruct 的类，它有 field1 和 field2 两个字段。 getFieldOrder 方法返回一个包含字段名称的列表，这些字段名称对应于结构体中字段的顺序，这是因为在结构体中字段的顺序至关重要。

5.1.2 结构体字段的映射规则

在JNA中，结构体字段映射到本地代码时需要遵循一些规则。首先，每个字段都必须使用 @Field 注解来标明它的内存位置。如果没有提供位置信息，JNA将为每个字段分配连续的内存地址，但有时候这样的映射方式并不符合本地代码的预期布局。因此，显式地指定字段位置是非常重要的，特别是在与现有的本地库进行交互时。

JNA支持多种字段类型，包括原生Java类型（如 int 、 double 等）、数组、指针、Java对象以及自定义的结构体。每种类型都有相应的映射规则，这允许结构体能够以一种透明的方式与本地库进行交互。例如，一个原生类型的字段将会映射为本地结构体中相同类型的字段，而一个数组字段将会映射为一个指针，指向该数组的数据。

5.2 结构体的应用

5.2.1 结构体的创建和初始化

一旦定义了结构体，接下来就是创建和初始化它们的实例。创建结构体实例时，可以使用无参构造函数，这将创建一个空的结构体实例，但是它不会分配任何内存。为了分配内存，可以使用带有特定大小参数的构造函数，这样可以创建一个引用类型的结构体，该结构体可以指向分配的本地内存。

MyStruct myStruct = new MyStruct();
myStruct.field1 = 10;
myStruct.field2 = 3.14;
// 创建一个引用类型的结构体，分配了16字节的内存
MyStruct myStructRef = new MyStruct(16);

在使用结构体时，如果要将其作为参数传递给本地函数，应确保使用引用类型（由 ByReference 标记的类型）。

5.2.2 结构体与本地函数的数据交互

在本地代码中定义了相应的结构体后，就能够在Java和本地代码之间传递复杂的数据结构。例如，考虑一个本地函数 doSomethingWithStruct ，它接受一个结构体参数并对其进行操作。

// 本地代码示例
typedef struct {
    int field1;
    double field2;
} MyStruct;
void doSomethingWithStruct(MyStruct *s) {
    s->field1 *= 2;
    s->field2 += 1.0;
}

在Java中，你可以这样使用这个本地函数：

Pointer pointer = new Memory(16); // 为结构体分配本地内存
MyStruct struct = new MyStruct(pointer);
struct.field1 = 1;
struct.field2 = 5.5;
// 获取本地函数的引用
Function doSomethingFunc = Native.loadLibrary("library", Library.class).getFunction("doSomethingWithStruct");
doSomethingFunc.invoke(struct);
System.out.println("Field1: " + struct.field1); // 输出 2
System.out.println("Field2: " + struct.field2); // 输出 6.5

在上面的Java代码中，我们首先创建了一个指向本地内存的 Pointer 对象，并用它来初始化我们的 MyStruct 实例。然后，我们加载了包含 doSomethingWithStruct 函数的本地库，并调用该函数。最后，我们通过 struct 实例输出了被修改过的值，以验证函数的调用结果。

结构体的这些操作提供了Java和本地代码之间复杂数据交互的基础，为涉及复杂数据结构的应用程序提供了强大的支持。通过这种方式，开发者可以利用JNA的优势，以最小的努力来调用本地库，而无需担心底层的复杂性。

6. 回调函数在JNA中的实现

回调函数是编程中一个非常重要的概念，它允许Java程序在执行某些操作时，能够调用预先定义好的本地函数。这种机制在处理异步任务、事件通知或者实现复杂交互时尤为有用。

6.1 回调函数基础

6.1.1 回调函数的概念和作用

回调函数本质上是一个被引用的对象，它指向一个方法。在JNA中，我们可以通过定义接口来实现回调功能。当某个本地操作需要执行一些操作时，它会调用这个接口中预定义的方法。这允许Java代码在本地代码执行期间有机会执行自己的代码。

6.1.2 在Java中声明回调函数的方法

在Java中声明回调函数通常涉及以下步骤：

1. 定义一个接口，其中包含预期被回调的方法。
2. 使用 Callback 接口标记接口。
3. 在Java类中实现这个接口。

interface MyCallbackInterface extends Callback {
    void callbackFunction(int arg);
}

6.2 回调函数高级应用

6.2.1 利用回调函数实现异步通信

异步通信允许程序在等待一个长时间操作（如磁盘I/O或网络通信）完成时继续执行其他任务。在JNA中，我们可以使用回调函数来接收操作完成的通知。

例如，我们定义一个本地函数 doLongOperation ，它接受一个回调函数参数。当操作完成时，通过调用回调函数来通知Java程序。

public interface NativeLib extends Library {
    void doLongOperation(MyCallbackInterface callback);
}

然后我们可以在Java中实现接口，并将其传递给本地函数：

public class CallbackDemo {
    public static void main(String[] args) {
        NativeLib lib = (NativeLib) Native.loadLibrary("theLibrary", NativeLib.class);
        MyCallbackInterface callback = new MyCallbackInterface() {
            public void callbackFunction(int arg) {
                System.out.println("Operation completed with result: " + arg);
            }
        };
        lib.doLongOperation(callback);
        // 程序可以继续执行其他任务，而不是在此等待
    }
}

6.2.2 回调函数中的数据管理和回调策略

在回调函数中处理数据时，需要特别注意线程安全和资源管理。例如，如果回调函数是在其他线程中执行的，我们需要确保数据访问是线程安全的，避免竞态条件。

此外，处理回调的策略也可以多种多样，例如：

• 阻塞回调 ：等待回调函数执行完毕后继续执行。
• 非阻塞回调 ：将回调任务提交到一个线程池，然后继续执行当前线程。

使用JNA时，通常需要根据应用程序的上下文和性能要求来选择合适的回调策略。

通过本章节的介绍，我们了解了JNA中回调函数的基础和高级应用。

到此这篇关于Java调用本地库的JNA快速入门的文章就介绍到这了,更多相关java调用jna内容请搜索脚本之家以前的文章或继续浏览下面的相关文章希望大家以后多多支持脚本之家！