Building a native extension for iOS and Android – Part 4: Building the Android library

In Part 2 and Part 3 of this series, you created the main and default libraries in ActionScript and the iOS library for a volume native extension for Adobe AIR. If you are going to use the native extension on Android devices, you must also create an Android library.

For me, building the Android library was an interesting experience. It was easier for me to write Java than Objective-C as it is more similar to ActionScript. Some amount of debugging (log statements) is actually possible with no work on the developer’s part, which is a great help. Also, using the AIR runtime extensions in Java is a much simpler process.  However, the Android operating system leaves a great deal of work up to the developers. You’ll find that some functionality that is built into the iOS framework will need to be built from scratch for Android.

Creating the Android library is fairly straightforward. If you haven't done so already, download the Android SDK and install the ADT Eclipse plugin into a standard version of Eclipse (not Flash Builder). Then follow these steps to create the library:

1. Open Eclipse and create a new Android project. Name it whatever you want and choose the minimum SDK version you wish to support. Chances are you'll want to pick 2.2, which is the first version of Android that AIR supports.

Next, you'll need to add the AIR runtime extensions to the project.

2. Right-click the project and select Properties.
3. Click Java Build Path and select the Libraries tab.
4. Click Add External JARs, navigate to air_sdk_dir\lib\android, select the FlashRuntimeExtensions.jar file, and click OK.
5. Create a class that implements the FREExtension interface. The package and name for this class should match the initializer node for the Android-ARM platform in the extension.xml file. This class should have the methods createContext() , dispose() , and initialize() .

The createContext() method accepts a string parameter that is the type of context to create. This is the second parameter passed to the ExtensionContext.createExtensionContext() method. The return value for createContext() should be a class that extends FREContext.

The dispose() method will be called when the native extension is no longer needed by the application. Here you should do any clean up required.

The initialize() method is called when the native extension is ready to be used.

6. Create a class that extends FREContext. This class should have the methods dispose() and getFunctions() .

The dispose() method serves the same purpose as the dispose method of the FREExtension .

The getFunctions() method returns a collection of FREFunction objects. There should be one FREFunction for each method that is called from the main ActionScript library. Each FREFunction is mapped to a string value, which is the name of the function.

7. Create one class that implements FREFunction for each method invoked from the main ActionScript library.

These classes will each have a call() method. This method is invoked when the function is called from the main ActionScript library. This is where the heavy lifting happens in the native extension and where you'll add the native code to implement whatever capabilities that your native extension offers.

The call() method is passed a FREContext instance and an array of FREObject instances. The FREContext is the extension context used to invoke the method. The array of FREObject instances is a collection of the parameters passed to the method, one FREObject for each parameter.

FREObject is a Java representation of an ActionScript object. It is a wrapper class, so to get to the underlying value you must invoke methods of FREObject. For example, in the setVolume() method you would pull out the Number value that is the new volume.

In the code above, the line that reads volume = args[0].getAsDouble(); is where the value passed from ActionScript is extracted from the FREObject collection.

Now you're ready to create the JAR file.

8. Right-click the Android project and select Export > Java > JAR File.
9. Ensure the project you're exporting is checked in Select Resources To Export.
10. Choose where to save the JAR file and click Finish.

Debugging native extensions isn't easy, but Android native extensions aren't quite as difficult to debug as iOS native extensions. You won't be able to hit breakpoints but you can see log statements from the native code. When using one of the Log.d(TAG,"Context disposed."); statements, the output will show up in the LogCat window in ADT when the native extension is running on the device. The LogCat window shows all of the logging that is happening on the device, so you'll likely want to filter (click the green plus sign) by tag to see only your native extension's specific logging.

The Android library is now complete. You have also completed the main and default libraries in ActionScript, as well as the iOS library if you are using your native extension on iOS devices. You're now ready for the final tutorial in this series—Developing a native extension for iOS and Android — Part 5: Building the ANE file.