本文档面向 Java 开发者,介绍如何在 Java 代码中使用 LuaJavaNE 提供的 API 来执行 Lua 脚本、调用 Lua 函数、以及将 Java 对象暴露给 Lua 环境。
将以下 JAR 文件放入 classpath:
luajava.jar– Java 端核心库lib/jline.jar– 可选,用于 REPL 行编辑支持
同时确保本机动态库 luajava.so(Linux/Android)或 luajava.dylib(macOS)位于系统库路径或通过 -Dluajava.library.path 指定。
import com.luajava.LuaRuntime;
LuaRuntime L = new LuaRuntime();每个 LuaRuntime 实例对应一个独立的 Lua 状态机(lua_State*)。
重要:使用完毕后必须调用 L.close() 释放本机资源,或利用 try-with-resources(实现了 AutoCloseable)。
L.doString("print('Hello from Lua!')");
L.doString("x = 42");L.doFile("/path/to/script.lua");对于需要多次调用的函数,可以预编译为 LuaFunctionObj 以提高性能。注意 compile() 编译的是一个 chunk,若 chunk 本身返回函数,需要先调用一次才能拿到该函数:
LuaFunctionObj chunk = L.compile("return function(a, b) return a + b end");
LuaFunctionObj add = (LuaFunctionObj) chunk.call(); // 执行 chunk,得到内部函数
Object[] results = add.callMultiple(3, 5); // results[0] == 8
chunk.destroy();
add.destroy(); // 释放本机引用编译失败(LUA_ERRSYNTAX)会抛出 LuaSyntaxError(LuaRuntimeError 的子类),而不是返回 null。
| 方法 | 说明 |
|---|---|
void doString(String) / void doFile(String) |
执行脚本;语法错误抛 LuaSyntaxError,运行错误抛 LuaRuntimeError |
LuaFunctionObj compile(String) |
编译 chunk;返回 LuaFunctionObj |
Object callFunction(String, Object...) |
调用全局函数,返回第一个值 |
Object[] callFunctionMultiple(String, Object...) |
调用全局函数,返回全部值 |
void setGlobal(String, Object) |
写入全局变量(见第 4 章) |
String getGlobal(String) |
读取全局变量并转为字符串 |
Object getGlobalObject(String) |
读取全局变量并保留原始类型(含 LuaTable/LuaFunctionObj) |
void registerModule(Object) |
注册 @LuaModule/@LuaFunction 注解对象(见第 5 章) |
void close() |
关闭本实例(AutoCloseable) |
// Lua 中定义:function add(a, b) return a + b end
Object result = L.callFunction("add", 10, 20); // 返回 Integer 30支持参数类型自动转换:Java 的 String、Integer、Double、Boolean 会被映射为 Lua 的对应类型,其他 Java 对象会被包装为 userdata(见第 7 节)。
// Lua 中定义:function swap(a, b) return b, a end
Object[] results = L.callFunctionMultiple("swap", "hello", "world");
// results[0] = "world", results[1] = "hello"若 Lua 函数抛出错误,callFunction 会抛出 LuaRuntimeError(其父类即 RuntimeException),错误信息来自 Lua 栈。
L.setGlobal("name", "LuaJava"); // Lua: name = "LuaJava"
L.setGlobal("count", 42); // Lua: count = 42(整数)
L.setGlobal("ratio", 0.5); // Lua: ratio = 0.5(浮点)
L.setGlobal("enabled", true); // Lua: enabled = true
L.setGlobal("buf", new StringBuilder("hi"));
L.setGlobal("arr", new int[] {1, 2, 3}); // Java.Array,0 基索引
L.setGlobal("nothing", null); // Lua: nothing = nil字符串、数字、布尔按 Lua 原生类型压栈;其他对象(含数组、Map/List)按 Lua 侧 Java userdata 规则包装。
String version = L.getGlobal("_VERSION"); // "Lua 5.4.8"
Object count = L.getGlobalObject("count"); // Integer 42getGlobal 保留原行为,把值转成字符串;需要原始类型(数字、布尔、Java 对象、LuaTable/LuaFunctionObj)时使用 getGlobalObject。Lua 的 nil 在两种方法下都返回 null。Lua 整数在 32 位范围内返回 Integer,超出范围返回 Long(完整 64 位值)。
通过注解 @LuaModule 和 @LuaFunction,您可以将任意 Java 类的实例方法暴露为 Lua 全局函数。
import com.luajava.LuaModule;
import com.luajava.LuaFunction;
@LuaModule("math") // 模块前缀,可选
public class MyMath {
@LuaFunction
public int add(int a, int b) {
return a + b;
}
@LuaFunction("mul") // 自定义函数名
public int multiply(int a, int b) {
return a * b;
}
}LuaRuntime L = new LuaRuntime();
L.registerModule(new MyMath());
L.doString("print(math_add(3, 5))"); // 输出 8
L.doString("print(math_mul(6, 7))"); // 输出 42- 若未指定
@LuaModule.value(),则使用空前缀,函数名即为方法名(或@LuaFunction.value())。 - 若指定了前缀,则生成全局函数名为
前缀_函数名(例如math_add)。
支持的方法参数类型:int、long、double、float、boolean、String,以及这些类型的包装类;也支持 LuaTable、LuaFunctionObj 与任意 Java 对象/数组(按第 7 节映射)。返回值同样支持上述类型,也可以返回任意 Java 对象(会被包装为 userdata)。
LuaRuntime.compile() 返回的 LuaFunctionObj 代表一个已编译的 Lua 函数(可以是闭包)。
LuaFunctionObj fn = L.compile("return function(x) return x * 2 end");
// 调用该函数获得真正的 double 函数
LuaFunctionObj doubler = (LuaFunctionObj) fn.call();
Object result = doubler.call(21); // 42
fn.destroy();
doubler.destroy();call(Object... args)– 返回第一个返回值callMultiple(Object... args)– 返回所有返回值数组
LuaFunctionObj 通过引用计数持有所属的 lua_State:即使先调用 LuaRuntime.close(),状态也会等到最后一个 LuaFunctionObj/LuaInvocationHandler 释放后才真正关闭,因此不会出现"状态已释放仍被引用"导致的崩溃。
- 建议显式调用
destroy()释放本机注册表引用(幂等,可重复调用)。 - 未调用时,对象被 GC 回收会经
java.lang.ref.Cleaner兜底释放,但不推荐依赖 GC 时机。
| Java 类型 | Lua 类型 |
|---|---|
null |
nil |
java.lang.String |
string |
java.lang.Integer / int |
integer |
java.lang.Long / long |
integer |
java.lang.Double / double |
number |
java.lang.Float / float |
number |
java.lang.Boolean / boolean |
boolean |
| 其他对象 | userdata(Java 对象代理;Map/List 额外带 table 语义) |
| Lua 类型 | Java 返回类型 |
|---|---|
nil |
null |
boolean |
java.lang.Boolean |
integer |
java.lang.Integer |
number |
java.lang.Double |
string |
java.lang.String |
function |
com.luajava.LuaFunctionObj |
table |
com.luajava.LuaTable(惰性活引用,见 7.3) |
userdata |
保持原 Java 对象引用(如果是通过 Java 传入的) |
当 Lua 函数返回一个 Java 对象时(如通过 Java 方法返回的对象),该对象会被包装为 userdata,并在 Java 侧以原类型返回。
字符串编码:Java
String→ Lua 使用标准 UTF-8(emoji 等增补平面字符为 4 字节);Lua 字符串 → Java 同样按标准 UTF-8 解码。非法 UTF-8 序列或孤立 UTF-16 代理项会替换为U+FFFD。
table 与 function 返回的是惰性引用,不复制数据。LuaTable 的每次 get/put 都经 JNI 直接读写原表,因此 Java 侧的修改对 Lua 立即可见,反之亦然。典型来源有三处:
- Lua 调用 Java 方法时,形参声明为
LuaTable; L.getGlobalObject("t")读取一个 table 全局变量;@LuaFunction方法的返回值/参数。
// Lua: t = { name = "lua", n = 5, 10, 20, 30 }
LuaTable t = (LuaTable) L.getGlobalObject("t");
String name = (String) t.get("name"); // "lua"
int n = ((Number) t.get("n")).intValue(); // 5
int len = t.size(); // 3(# 语义,仅数组部分)
Object[] keys = t.keys(); // 全部键(各自还原为 Java 类型)
t.put("fromJava", "yes"); // 写回,Lua 侧立即可见
t.destroy(); // 用完释放注册表引用(幂等)| 方法 | 说明 |
|---|---|
Object get(Object key) |
读取键;nil/不存在返回 null,table/function 分别返回 LuaTable/LuaFunctionObj |
void put(Object key, Object value) |
写入/覆盖;Java 对象会按第 7.1 节规则压栈 |
int size() |
Lua #(rawlen),仅对数组部分精确 |
Object[] keys() |
遍历全部键 |
void destroy() |
释放引用;未调用时由 Cleaner 兜底 |
LuaTable与LuaFunctionObj一样会持有lua_State的引用计数:即使先L.close(),状态也会等最后一个引用释放后才真正关闭。销毁后再调用get/put/size/keys会抛出IllegalStateException。
Lua 函数传入 Java 时同样以 LuaFunctionObj 接收,可在 Java 侧直接回调:
public static Object applyTwice(LuaFunctionObj f, Object x) {
Object once = f.call(x);
return f.call(once);
}local r = TestBridge.applyTwice(function(v) return v * 2 end, 10) -- 40public interface Greeting {
String sayHello(String name);
}local Greeting = java.import("com.example.Greeting")
local handler = {
sayHello = function(self, name)
return "Hello, " .. name .. " from Lua!"
end
}
local proxy = java.createProxy({"com.example.Greeting"}, handler)// 将 proxy 作为 Object 传入 Java,然后强转为接口
Greeting g = (Greeting) proxy;
System.out.println(g.sayHello("Java")); // Hello, Java from Lua!java.createProxy 的 Lua 用法见 lualibjava.c,Java 侧只需接收 Object 并转型。
LuaJavaNE 提供了一套基于 RuntimeException 的结构化异常层次(包 com.luajava.exception),
既有 catch (RuntimeException) 用法完全向后兼容:
java.lang.RuntimeException
└── LuaJavaException (抽象基类)
├── LuaRuntimeError — Lua 执行期错误(doString/doFile/callFunction 的 pcall 失败)
│ └── LuaSyntaxError — Lua 编译期语法错误(compile(),对应 LUA_ERRSYNTAX)
├── JavaInvocationError — Lua 调用已注册 Java 方法失败时对 checked 异常的包装
└── TypeConversionError — Lua↔Java 参数类型转换失败
- Lua 执行错误会抛出
LuaRuntimeError(语法错误为LuaSyntaxError),错误信息包含 Lua 栈回溯。 - Java 方法通过注解暴露给 Lua 时,若抛出异常会被捕获并转换为 Lua 错误,然后在 Java 侧重新抛出:
方法的
RuntimeException/Error原样重抛,其余 checked 异常统一包装为JavaInvocationError(保留原因)。 - 以上异常均为
RuntimeException的子类,可直接catch (RuntimeException)统一处理。 - Lua 调用 Java 方法抛出的异常会先转换为 Lua 错误(信息含
java.lang.异常类: message);若该调用发生在doString/doFile/callFunction中,Java 侧会以LuaRuntimeError呈现并保留该信息。
L.close(); // 释放 lua_State 及所有关联资源若使用 try-with-resources:
try (LuaRuntime L = new LuaRuntime()) {
L.doString("...");
}fn.destroy(); // 释放本机引用(建议显式调用;未调用时 GC 会兜底)LuaJavaNE 内部使用 LuaAgent 管理后台线程池(用于异步任务)。该线程池是全局的,会在 JVM 退出时自动终止。如需主动关闭,可调用:
LuaAgent.shutdown();但通常无需手动操作。
Java 侧还可直接使用 LuaAgent 的公开入口:submitTask(AgentTask) / submitTaskFuture(...)(异步任务)、cancelTask / awaitTask(取消与等待)、registerObject / getObject / unregisterObject(对象池)、getTaskStats / getRegistryStats(统计)以及 shutdown / shutdownNow。任务与对象的详细语义见 AgentV2.md 的“Java 侧扩展”一节。
Lua 侧对应 java.load(path, {natives=true});Java 侧直接使用 com.luajava.JarLoader。它是进程级的:所有 LuaRuntime 共享同一个 URLClassLoader,重复加载同一路径会被去重。
import com.luajava.JarLoader;
int added = JarLoader.load("libs/mylib.jar"); // 1=新增,0=已加载过
Class<?> greeter = JarLoader.resolve("demo.Greeter"); // 找不到返回 null(不初始化类)
ClassLoader cl = JarLoader.loader(); // 供代理/异步等需要 loader 的场景
String[] paths = JarLoader.loadedPaths(); // 已加载路径快照带本地库(.so / .dylib / .dll)的 JAR:
JarLoader.load("libs/native-lib.jar", true); // true = 提取并绑定本地库
for (String w : JarLoader.drainWarnings()) {
System.err.println("[warn] " + w);
}| 方法 | 说明 |
|---|---|
int load(String path) / int load(String path, boolean natives) |
附加 JAR/ZIP 或 class 目录;natives=true 时按当前平台提取本地库并注册给 findLibrary;路径非法或提取失败抛 IOException |
Class<?> resolve(String binaryName) |
用运行期加载器解析类;失败返回 null(等价于 Class.forName(name, false, loader)) |
ClassLoader loader() |
运行期加载器,可传给 Proxy、ServiceLoader 等 |
String[] loadedPaths() |
已加载路径快照(诊断用) |
String[] drainWarnings() |
取出并清空告警:类被 classpath 遮蔽、跨 JAR 重复类、无匹配平台的本地库、重复库名;最多保留 10 条,其余汇总为 further warnings suppressed |
注意:父加载器优先,JAR 与 classpath 同名类时使用 classpath 版本;JVM 无法卸载类,也不支持同一类名在两个加载器中共存。
import com.luajava.LuaRuntime;
import com.luajava.LuaFunctionObj;
import com.luajava.LuaModule;
import com.luajava.LuaFunction;
@LuaModule("demo")
class Calculator {
@LuaFunction
public int add(int a, int b) { return a + b; }
}
public class Main {
public static void main(String[] args) throws Exception {
try (LuaRuntime L = new LuaRuntime()) {
// 1. 执行脚本
L.doString("function mul(a, b) return a * b end");
// 2. 调用 Lua 函数
Object product = L.callFunction("mul", 6, 7);
System.out.println("6 * 7 = " + product); // 42
// 3. 注册 Java 模块
L.registerModule(new Calculator());
L.doString("print(demo_add(10, 20))"); // 30
// 4. 编译并调用 Lua 函数
LuaFunctionObj fn = L.compile("return function(x) return x + 100 end");
LuaFunctionObj inc = (LuaFunctionObj) fn.call();
System.out.println(inc.call(50)); // 150
fn.destroy();
inc.destroy();
}
}
}Q:为什么我的 Java 方法没有被注册?
A:确保类上有 @LuaModule 注解,方法上有 @LuaFunction,且方法为 public。
Q:调用 L.doString 时抛异常怎么办?
A:捕获 LuaRuntimeError(语法错误为 LuaSyntaxError,二者均为 RuntimeException 子类)并查看错误信息,通常是 Lua 语法错误或运行时错误。
Q:LuaFunctionObj 必须调用 destroy() 吗?
A:建议调用以尽快释放本机资源。得益于引用计数,即使忘记调用或先关闭了 LuaRuntime,也不会崩溃:底层状态会在最后一个引用释放(含 GC 时的 Cleaner 兜底)后才真正关闭。
Q:如何传递数组或集合?
A:Java 数组作为 Java.Array userdata 传入/返回(0 基索引、# 取长度);java.util.Map/List 会包成带 table 语义的惰性 userdata(#、pairs/ipairs、写回)。Lua 原生 table 则以 LuaTable 活引用传入 Java(见 7.3)。
Q:如何在 Java 中拿到 Lua table 或函数?
A:用 L.getGlobalObject(name) 取回原始类型:table 得到 LuaTable,function 得到 LuaFunctionObj;也可在 @LuaFunction 方法/普通 Java 方法形参中直接声明这两种类型。
Q:Java 侧如何加载带本地库的 JAR?
A:JarLoader.load(path, true);告警通过 JarLoader.drainWarnings() 读取,详见第 11 章。
- 项目源码:
java/src/com/luajava/包含所有 Java API 类 - 示例脚本:
examples/目录下的 Lua 示例 - REPL 启动:
./luaj.sh(在项目根目录)
本文档基于 LuaJavaNE v2.5.1 及之后的未发布改动编写,如有变动请参考最新源码。