On Android target platforms Storyboard provides an additional level of platform integration. In order to access the native Java service API on Android platforms Storyboard has incorporated the LuaJava module to provide a bridge from Storyboard Lua script functions to the Android Java API.

Access to the LuaJava bridge is through the luajava Lua variable. On non-Android platforms, this variable will not be defined and this can be used to provide alternate or simulated behavior.

function my_callback(mapargs)
    if(luajava == nil) then
        print("LuaJava bridge not available")
        return
    end

    -- LuaJava available for use ...
end
                    

The general mapping of standard Lua/Java types such as strings and numbers is handled transparently so that Lua strings can be used in Java constructors and methods in the same way that the Java String class would normally be used and similarly for Lua numbers and vice/versa.

When a Lua variable is created that is a reference or proxy to a Java object, then access to the methods of that object are performed using the colon (:) notation with the Lua variable, lua_variable:method_name() notation. When accessing static member variables of an object, this can be performed using the traditional dot (.) notation lua_variable.member_variable_name. This is further demonstrated in the examples shown below.

In order to access a nested Java class for instantiation or binding, the dollar sign ($) must be used as a separator. For instance, if the Java class Bar is a nested class of Foo, then binding would work as follows: luajava.bindClass("Foo$Bar"). This is further demonstrated in the examples below.

A description of the complete Android Java API is beyond the scope of this document. For a complete coverage of the Android API refer to http://developer.android.com/reference/packages.html Depending on the functionality that your application is going to access, there may be additional restrictions that must be explicitly declared in the AndroidManifest.xml file. Permissions can be added in the Advanced Options section when exporting your Android project. The android:debuggable option has been changed to false by default. To change this, you will need to use your own custom manifest file. Export your manifest file to view it by clicking the Export button under the Manifest File tab. You can make changes to this file and then select it as a custom manifest file when exporting to ensure the manifest file is setup the way you want it to be.

Within the Android environment the Storyboard Engine execution takes place outside of the main Android/Java event loop. When integrating with the Android API's developers should always consider that they are using the Android API as if they were executing in a background thread and act accordingly. This may require the creation of additional Looper message event handlers if callback event handlers are being used. For more information on Android process model and multi-threading considerations, refer to the Android documentation: http://developer.android.com/guide/components/processes-and-threads.html.