LuaJavaBridge - Lua 与 Java 互操做的简单解决方案

http://dualface.github.io/blog/2013/01/01/call-java-from-lua/

最近在游戏里要集成中国移动的 SDK，而这些 SDK 都是用 Java 编写的。因为咱们整个游戏都是使用 Lua 开发的，因此就面对 Lua 与 Java 互操做的问题。

传统作法是先用 C/C++ 借助 JNI（Java Native Interface）编写调用 Java 的接口函数，而后再将这些函数经过 tolua++ 导出给 Lua 使用。这种作法最大的问题就是太繁琐，并且稍微有一点点修改，就要从新编译，严重下降了开发效率。

我尝试写了几个接口函数后，发现 JNI 提供了完善的接口来操做 Java，好比查找特定的 Class、Method 等等。既然有这些东西，我想彻底能够实现一个很薄的转接层。这个层会提供一些函数，让 Lua 代码能够直接调用到 Java 的方法。

通过一番努力，LuaJavaBridge（简称 luaj）诞生了。

luaj 主要特征

• 能够从 Lua 调用 Java Class Static Method
• 调用 Java 方法时，支持 int/float/boolean/String/Lua function 五种参数类型
• 能够将 Lua function 做为参数传递给 Java，并让 Java 保存 Lua function 的引用
• 能够从 Java 调用 Lua 的全局函数，或者调用引用指向的 Lua function

luaj 的功能很简单，但对于集成各类 SDK 来讲已经彻底知足需求了。

luaj 用法示例

下面的代码是咱们游戏中实际使用的中国移动支付 SDK 调用代码，luaj 好很差用一目了然：

Lua 代码:

--[[ 购买 1000 金币  Java 方法原型: public static void GameInterface_doBilling(final String billingIndex,  final boolean useSms,  final boolean isRepeated,  final int luaFunctionId) ]]  -- 用于处理支付结果的函数 local function callback(result)  if result == "success" then  game.state:increaseCoins(1000)  game.state:save()  end end  -- 调用 Java 方法须要的参数 local args = {  "001", -- billingIndex  true, -- useSms  true, -- isRepeated  callback -- luaFunctionId } -- Java 类的名称 local className = "com/qeeplay/frameworks/ChinaMobile_SDK" -- 调用 Java 方法 luaj.callStaticMethod(className, "GameInterface_doBilling", args)

luaj 实现原理

luaj 的核心目标有两个：从 Lua 调用 Java, 从 Java 调用 Lua。整理出来就是以下几点：

• 查找并调用指定的 Java 方法
• 检查调用结果，并从 Java 方法获取返回值
• 将 Lua function 做为参数传递给 Java 方法
• 在 Java 方法中调用 Lua function

查找并调用指定的 Java 方法

JNI 提供了 FindClass() 方法用于查找指定的 Class，因此 luaj.callStaticMethod() 的第一个参数就是要调用的 Java Class 的完整类名称（类名称中的“.”要替换为“/”）。

找到指定 Class 后，利用 JNI 的 GetStaticMethodID() 方法就能够找到这个类的指定静态方法，前提是要提供静态方法的名称和签名。

所谓签名，就是指 Java 方法的参数类型和返回类型定义。例如前面示例代码中 GameInterface_doBilling() 方法的签名是 (Ljava/lang/String;ZZI)V 。关于 Java 方法签名的具体定义，能够参考：JNI Type Signatures。

因为签名写起来有点啰嗦，因此 luaj 能够根据调用参数自动猜想方法签名。示例代码中，luaj.callStaticMethod() 的第二个参数指定了要查找的方法名称，但并无提供方法的签名，这就是利用了 luaj 的自动猜想签名功能。

示例代码一共指定了 4 个参数，分别是：字符串、布尔值、布尔值、Lua function。

-- 调用 Java 方法须要的参数 local args = {  "001", -- billingIndex  true, -- useSms  true, -- isRepeated  callback -- luaFunctionId }

luaj 根据这 4 个参数，会构造出正确的 GameInterface_doBilling() 方法签名。注意 Lua function 是以整数的形式传入 Java 方法，因此 Java 方法的第四个参数是 int 类型）。

不幸的是 Lua 里没有办法准确判断一个数值是整数仍是浮点数，因此 luaj 在猜想方法签名时，假定全部的数值都是浮点数。所以下面的代码第二个调用就会失败：

为此，luaj 容许开发者指定完整的方法签名。并且除了整数和浮点数的状况，在须要从 Java 方法得到返回值时，也须要开发者指定完整的方法签名。示例代码以下：local args = {1} -- 生成的方法签名是 (F)V  --[[ Java 方法原型: public static void TestMethod1(final float integerValue) ]] -- 调用成功 luaj.callStaticMethod(className, "TestMethod1", args)  --[[ Java 方法原型: public static void TestMethod2(final int integerValue) ]] -- 调用失败，正确的方法签名应该是 (I)V luaj.callStaticMethod(className, "TestMethod2", args)

local args ={"StringValue", 1, 3.14}  --[[ Java 方法原型: public static int TestMethod3(final String stringValue,  final int integerValue,  final float floatValue) ]]  -- 定义签名 -- 参数: [S]tring, [I]nteger, [F]loat -- 返回值: [I]nt local sig = "(Ljava/lang/String;IF)I"  -- 调用方法并得到返回值 local ok, ret = luaj.callStaticMethod(className, "TestMethod3", args, sig)

检查调用结果，并从 Java 方法获取返回值

luaj 调用 Java 方法时，可能会出现各类错误，所以 luaj 提供了一种机制让 Lua 调用代码能够肯定 Java 方法是否成功调用。

luaj.callStaticMethod() 会返回两个值：

• 当成功时，第一个值为 true，第二个值是 Java 方法的返回值（若是有）。
• 当失败时，第一个值为 false，第二个值是错误代码。

下面的代码展现了如何检查返回结果和得到返回值：

Java 代码

Lua 代码public static int AddTwoNumbers(final int number1,  final int number2) {  return number1 + number2; }

local args = {2, 3} local sig = "(II)I" local ok, ret = luaj.callStaticMethod(className, "AddTwoNumbers", args, sig)  if not ok then  print("luaj error:", ret) else  print("ret:", ret) -- 输出 ret: 5 end

将 Lua function 做为参数传递给 Java 方法

不少时候，咱们须要一种方法让 Java 代码能够向 Lua 代码传递一些消息。例如在大部分游戏平台的 SDK 中，涉及支付的部分都是异步操做的。在支付操做结束后，Java 代码须要通知 Lua 支付成功与否。

Lua 虚拟机中，Lua function 以值的形式保存。但这个值没法直接给 Java 用，因此 luaj 作了一个 Lua function 引用表。当一个 Lua function 传递给 Java 时，这个 function 对应的值会被存在引用表中，并得到一个惟一的引用 ID （整数）。Java 代码拿到这个引用 ID 后，就能够很方便的调用该 Lua function 了。

回顾最开始的示例代码，GameInterface_doBilling() 函数用于接收 Lua function 的参数就是 int 类型。由于实际传入 Java 函数的值是 Lua function 的引用 Id。

~

在 Java 方法中调用 Lua function

在 Java 代码中拿到 Lua function 的引用 ID 后，就能够很方便的调用该 Lua function 了：

LuaJavaBridge.callLuaFunctionWithString(luaFunctionId, "hello");

这里出现的 LuaJavaBridge 是 luaj 的 Java 部分定义的工具 class。 callLuaFunctionWithString() 方法能够将一个字符串参数传递给指定的 Lua function。

LuaJavaBridge 还提供了 callLuaGlobalFunctionWithString() 方法，能够直接调用 Lua 中指定名字的全局函数。这样能够在没有 Lua function 引用 ID 的状况下和 Lua 代码交互。

因为本身的项目暂时没更多需求，因此目前 luaj 只支持向 Lua function 传递单个字符串参数。

GL 线程和 UI 线程的协调

cocos2d-x for Android 运行在多线程环境下，因此在 Lua 和 Java 交互时须要注意选择适当的线程。

~

cocos2d-x 在 Android 上以两个线程来运行，分别是负责图像渲染的 GL 线程和负责 Android 系统用户界面的 UI 线程。

• 在 cocos2d-x 启动后，Lua 代码将由 GL 线程调用，所以从 Lua 中调用的 Java 方法若是涉及到系统用户界面的显示、更新操做，那么就必须让这部分代码切换到 UI 线程上去运行。
• 反之亦然，从 Java 调用 Lua 代码时，须要让这个调用在 GL 线程上执行，不然 Lua 代码虽然执行了，但会没法更新 cocos2d-x 内部状态。

下面是 GameInterface_doBilling() 方法的主要代码：

public static void GameInterface_doBilling(final String billingIndex,  final boolean useSms,  final boolean isRepeated,  final int luaFunctionId) {  context.runOnUiThread(new Runnable() {  @Override  public void run() {  GameInterface.doBilling(useSms, isRepeated, billingIndex, new BillingCallback() {   ...   @Override  public void onBillingSuccess() {  context.runOnGLThread(new Runnable() {  @Override  public void run() {  LuaJavaBridge.callLuaFunctionWithString(luaFunctionId, "success");  LuaJavaBridge.releaseLuaFunction(luaFunctionId);  }  });  }   ...   });  }  }); }

~

方法中，构造了一个 Runnable 对象，用来包装须要执行的 Java 代码。这个 Runnable 对象被指定运行在 UI 线程上。这样当调用 GameInterface.doBilling() 方法时就能够正确显示出支付界面。

当用户支付成功后，GameInterface.doBilling() 会调用 BillingCallback.onBillingSuccess() 方法。这个方法里构造了另外一个 Runnable 对象，包装了调用 Lua function 的代码。

看上去代码很多，实际上就是在两个线程间互相切换。确保 Lua function 跑在 GL 线程，Java 代码跑在 UI 线程。

~

Lua function 的引用计数器

Lua 虚拟机具备自动垃圾回收机制。Lua function 既然是值，那么在没有被使用时天然会被回收掉。因此 luaj 提供了 retainLuaFunction() 和 releaseLuaFunction() 两个函数用于增减 Lua function 的引用计数。

将一个 Lua function 以引用 ID 的形式传入 Java 时，luaj 会自动增长引用 ID 的计数器，因此在 Java 方法里能够放心的异步调用 Lua function。但在不须要使用该 Lua function 后，必定要调用 releaseLuaFunction() 减小该引用 ID 的计数器。当计数器为 0 时，会自动释放该 Lua function。

若是了解 cocos2d-x 中 CCObject 的 autorelease 机制，那么对引用计数应该很熟悉，二者是彻底相同的实现机制。

~

链接第三方 SDK 和 cocos2d-x 的中间层

虽然 luaj 可让开发者从 Lua 中直接调用 Java 代码。但大部分第三方 SDK 在初始化时都须要指定当前应用程序的 Activity 对象，而且还要切换不一样线程，因此对于大多数第三方 SDK，咱们仍然要写一个中间层用于 Lua 和 Java 的交互。

与使用 JNI 作中间层相比，配合 luja 的中间层是使用 Java 来编写的，不但更简单明了，并且处理线程切换也很是简单。

~

要实现一个中间层，只有两个步骤：

• 实现供 luaj 调用的 Java 接口
• 修改游戏的 Java 入口文件，将应用程序的 Activity 对象传入 SDK

第一步请参考：“中国移动游戏基地和短信支付 SDK”中间层源代码

第二步也至关简单，只须要在游戏的 onCreate() 中调用 中间层 class 的 setContext() 方法：

public class mygame extends Cocos2dxActivity {   protected void onCreate(Bundle savedInstanceState) {  ChinaMobile_SDK.setContext(this); // init sdk  super.onCreate(savedInstanceState);  }   ...  }

~

作好一切准备工做后，在游戏的 Lua 代码里访问 SDK 功能就很简单了：

local luaj = require("luaj")  local className = "com/qeeplay/frameworks/ChinaMobile_SDK"  -- 初始化 SDK local args = {  CHINA_MOBILE_SP_APP_NAME,  CHINA_MOBILE_SP_CP_NAME,  CHINA_MOBILE_SP_TEL } luaj.callStaticMethod(className, "GameInterface_initializeApp", args)  -- 支付 local function callback(result)  if result == "success" then  -- 支付成功  end end  local args = {  billingIndex,  true,  true,  callback } luaj.callStaticMethod(className, "GameInterface_doBilling", args)  -- 显示游戏基地界面 luaj.callStaticMethod(className, "GameCommunity_launchGameCommunity")  -- 提交玩家的游戏成绩 local args = {  "0", -- 排行榜Id  newBestScores, -- 新的最佳成绩 } local sig = "(Ljava/lang/String;I)V" luaj.callStaticMethod(className, "GameCommunity_commitScoreWithRank", args, sig)