Next week I’ll be presenting in Seattle at my first Force.com Developer Meetup! It starts at 6pm on Wednesday, June 22. My session will be on Flex Mobile Development. Other sessions include Force.com Platform Basics, Native iOS Development using JavaScript, and a Force.com Hands-On Lab. It’s going to be a fun evening, so if you are in the Seattle area, then I hope to see you there!

Get more details and register!

In 2004 I started getting into Macromedia Flex. I was amazed at how easy it was to retrieve and nicely render data from a Java back-end. In 2005 I began evangelizing Flex + Java. Following the acquisition of Macromedia by Adobe, Flex has really flourished. Adobe Flex is now the dominant RIA technology and it has been so fun to be a part of that!

Over the past seven years I’ve had so many great adventures on the client-side, but when a new opportunity on the server-side came my way I couldn’t pass it up. Starting June 6th I’ll be stepping back into the Java world to evangelize the Cloud for Salesforce.com. I’m excited to dive into some of the emerging Java/JVM technologies like Scala, Play Framework, and Clojure!

This change is certainly bittersweet for me. Flex continues to make app development easier. With things like Android support in Flex 4.5 and iOS support coming soon, the future of Flex is bright. I’ve been very privileged to be a part of the Flex community for the past seven years. This group of passionate and creative developers have taught me so many new things. Learning how to do runtime bytecode modification and co-creating Mixing Loom has certainly been one of the highlights!

As I begin this new adventure on the Cloud I’m excited about what lies ahead for Flex and for the Cloud. Both continue to help us developers build better software. I’ve hopefully helped you learn how to build great UIs with Flex. Now I will help you learn how to build solid and scalable back-ends on the Cloud!

Adobe AIR provides a consistent platform for desktop and mobile apps. While consistency is very important there are times when developers need to extend beyond the common APIs. This article will walk you through how to integrate AIR for Android applications with other native APIs and functionality in the Android SDK. It covers three common use cases for native extensibility: System Notifications, Widgets, and Application Licensing.

If you’d like to follow along you will need the following prerequisites:

• Adobe Flash Builder 4.5(which includes the Flex 4.5 SDK and AIR 2.6 SDK)
• Android SDK
• Android Eclipse Plugin

Before getting started, a little background will help. Android applications are distributed as APK files. An APK file contains the Dalvik executable (dex), which will run on an Android device inside the Dalvik VM. The Android SDK compiles a Java-like language to dex.

AIR for Android applications are also distributed as APK files. Inside of these APK files is a small bit of dex that bootstraps the AIR for Android runtime, which then loads and runs the SWF file that is also inside of the APK. The actual dex class that bootstraps the AIR application is dynamically generated by the adt tool in the AIR SDK. The class is named AppEntry and its package name depends on the AIR application ID, but it always begins with “air”. The AppEntry class checks for the existence of the AIR runtime and then launches the AIR application. The Android descriptor file in an AIR APK specifies that the main application class is the AppEntry class.

To extend AIR for Android applications to include native APIs and Android SDK functionality, you start by creating a SWF file using Flex and then copy that SWF file, the dex classes for AIR for Android, and the required resources into a standard Android project. By using the original AppEntry class you can still bootstrap the AIR application in the Android project but you can extend that class to gain a startup hook.

1. To get started, download a package with the required dependencies for extending AIR for Android:
   http://www.jamesward.com/downloads/extending_air_for_android-flex_4_5-air_2_6-v_1.zip
2. Next, create a regular Android project in Eclipse (do not create an Activity yet):
   
3. Copy all of the files from the zip file you downloaded into the root directory of the newly created Android project. You will need to overwrite the existing files and update the launch configuration (if Eclipse asks you to).
4. Delete the “res/layout” directory.
5. Add the airbootstrap.jar file to the project’s build path. You can do that by right-clicking on the file, then select Build Path and then Add to Build Path.
6. Verify that the project runs. You should see “hello, world” on your Android device. If so, then the AIR application is properly being bootstrapped and the Flex application in assets/app.swf is correctly being run.

   At this point if you do not need any custom startup hooks then you can simply replace the assets/app.swf file with your own SWF file (but it must be named app.swf). If you do need a custom startup hook then simply create a new Java class named “MainApp” that extends the air.app.AppEntry class.
   

7. Override the onCreate() method and add your own startup logic before super.onCreate() is called (which loads the AIR app). Here is an example:

   package com.jamesward;
    
   import air.app.AppEntry;
   import android.os.Bundle;
    
   public class MainApp extends AppEntry {
    
   	@Override
   	public void onCreate(Bundle arg0) {
   		System.out.println("test test");
   		super.onCreate(arg0);
   	}
   }

8. Open the AndroidManifest.xml descriptor file and tell it to use the new MainApp class instead of the original AppEntry class. First change the package to be the same as your MainApp’s package:

   <manifest package="com.jamesward" android:versionCode="1000000" android:versionName="1.0.0"
     xmlns:android="http://schemas.android.com/apk/res/android">

   Also update the activity to use the MainApp class (make sure you have the period before the class name):

   <activity android:name=".MainApp"

   You can also add any other permissions or settings you might need in the AndroidManifest.xml file.

9. Save the changes and, when Eclipse prompts you, update the launch configuration.
10. Run the application and you should again see “hello, world”. This time, however, in LogCat (command line tool or Eclipse view) you should see the “test test” output. Now that you have a startup hook, you can do some fun stuff!

System Notifications and Services

AIR for Android applications don’t yet have an API to do Android system notifications. But you can add system notifications to your AIR for Android application through a startup hook. In order for the AIR application to communicate with the native Android APIs you must provide a bridge for the communication. The simplest way to create that bridge is using a network socket. The Android application can listen for data on the socket and then read that data and determine if it needs to display a system notification. Then the AIR application can connect to the socket and send the necessary data. This is a pretty straightforward example but some security (for instance a key exchange) should be implemented to insure that malicious apps don’t discover and abuse the socket. Also some logic to determine which socket should be used would likely be necessary.

1. Inside the application section add a new Android Service:

<service android:enabled="true" android:name="TestService" />

2. Since this example uses a Socket you will also need to add the INTERNET permission:

<uses-permission android:name="android.permission.INTERNET"/>

3. You might also want to enable the phone to vibrate when there is a new notification. If so add that permission as well:

   <uses-permission android:name="android.permission.VIBRATE"/>

4. Save your changes to AndroidManifest.xml.
5. Next, create the background Java Service class, called TestService. This service will listen on a socket and when necessary, display an Android Notification:

   package com.jamesward;
    
   import java.io.BufferedInputStream;
   import java.io.DataInputStream;
   import java.io.IOException;
   import java.net.ServerSocket;
   import java.net.Socket;
    
   import android.app.Notification;
   import android.app.NotificationManager;
   import android.app.PendingIntent;
   import android.app.Service;
   import android.content.Context;
   import android.content.Intent;
   import android.os.IBinder;
   import android.os.Looper;
   import android.util.Log;
    
   public class TestService extends Service
   {
     private boolean stopped=false;
     private Thread serverThread;
     private ServerSocket ss;
    
     @Override
     public IBinder onBind(Intent intent)
     {
       return null;
     }
    
     @Override
     public void onCreate()
     {
       super.onCreate();
    
       Log.d(getClass().getSimpleName(), "onCreate");
    
         serverThread = new Thread(new Runnable() {
    
           public void run()
           {
                   try
                   {
                           Looper.prepare();
                           ss = new ServerSocket(12345);
                           ss.setReuseAddress(true);
                           ss.setPerformancePreferences(100, 100, 1);
                           while (!stopped)
                           {
                                   Socket accept = ss.accept();
                                   accept.setPerformancePreferences(10, 100, 1);
                                   accept.setKeepAlive(true);
    
                                   DataInputStream _in = null;
                                   try
                                   {
                                           _in = new DataInputStream(new BufferedInputStream(accept.getInputStream(),1024));
                                   }
                                   catch (IOException e2)
                                   {
                                     e2.printStackTrace();
                                   }
    
                                   int method =_in.readInt();
    
                                   switch (method)
                                   {
                                     // notification
                                     case 1:
                                           doNotification(_in);
                                           break;
                                   }
                           }
                   }
                   catch (Throwable e)
                   {
                           e.printStackTrace();
                           Log.e(getClass().getSimpleName(), "Error in Listener",e);
                   }
    
                   try
                   {
                     ss.close();
                   }
                   catch (IOException e)
                   {
                     Log.e(getClass().getSimpleName(), "keep it simple");
                   }
           }
    
           },"Server thread");
         serverThread.start();
    
     }
    
     private void doNotification(DataInputStream in) throws IOException {
       String id = in.readUTF();
       displayNotification(id);
     }
    
     @Override
     public void onDestroy() {
             stopped=true;
             try {
                     ss.close();
             } catch (IOException e) {}
             serverThread.interrupt();
             try {
                     serverThread.join();
             } catch (InterruptedException e) {}
     }
    
     public void displayNotification(String notificationString)
     {
       int icon = R.drawable.mp_warning_32x32_n;
       CharSequence tickerText = notificationString;
       long when = System.currentTimeMillis();
       Context context = getApplicationContext();
       CharSequence contentTitle = notificationString;
       CharSequence contentText = "Hello World!";
    
       Intent notificationIntent = new Intent(this, MainApp.class);
       PendingIntent contentIntent = PendingIntent.getActivity(this, 0, notificationIntent, 0);
    
       Notification notification = new Notification(icon, tickerText, when);
       notification.vibrate = new long[] {0,100,200,300};
    
       notification.setLatestEventInfo(context, contentTitle, contentText, contentIntent);
    
       String ns = Context.NOTIFICATION_SERVICE;
       NotificationManager mNotificationManager = (NotificationManager) getSystemService(ns);
    
       mNotificationManager.notify(1, notification);
     }
    
   }

   This service listens on port 12345. When it receives some data it checks if the first “int” sent is “1”. If so, it then creates a new notification using the next piece of data (a string) that is received over the socket.

6. Modify the MainApp Java class to start the service when the onCreate() method is called:

   	@Override
   	public void onCreate(Bundle savedInstanceState)
   	{
   		try
   		{
   			Intent srv = new Intent(this, TestService.class);
   			startService(srv);
   		}
   		catch (Exception e)
   		{
   			// service could not be started
   		}
    
   		super.onCreate(savedInstanceState);
   	}

   That is all you need to do in the Android application.

7. Next, create a Flex application that will connect to the socket and send the right data. Here is some sample code for my Notifier.mxml class, which I used to test the Android service:

   <?xml version="1.0" encoding="utf-8"?>
   <s:Application xmlns:fx="http://ns.adobe.com/mxml/2009" 
                          xmlns:s="library://ns.adobe.com/flex/spark">
    
     <fx:Style>
       @namespace s "library://ns.adobe.com/flex/spark";
    
       global {
         fontSize: 32;      
       }
     </fx:Style>
    
     <s:layout>
       <s:VerticalLayout horizontalAlign="center" paddingTop="20"/>
     </s:layout>
    
     <s:TextInput id="t" text="test test"/>
    
     <s:Button label="create notification">
       <s:click>
         <![CDATA[
           var s:Socket = new Socket();
           s.connect("localhost", 12345);
           s.addEventListener(Event.CONNECT, function(event:Event):void {
             trace('connected!');
             (event.currentTarget as Socket).writeInt(1);
             (event.currentTarget as Socket).writeUTF(t.text);
             (event.currentTarget as Socket).flush();
             (event.currentTarget as Socket).close();
           });
           s.addEventListener(IOErrorEvent.IO_ERROR, function(event:IOErrorEvent):void {
             trace('error! ' + event.errorID);
           });
           s.addEventListener(ProgressEvent.SOCKET_DATA, function(event:ProgressEvent):void {
             trace('progress ');
           });
         ]]>
       </s:click>
     </s:Button>
    
   </s:Application>

   As you can see there is just a TextInput control that allows the user to enter some text. Then when the user clicks the Button the AIR for Android application connects to a local socket on port 12345, writes an int with the value of 1, writes the string that the user typed into the TextInput control, and finally flushes and closes the connection. This causes the notification to be displayed.

8. Now simply compile the Flex app and overwrite the assets/app.swf file with the new Flex application. Check out a video demonstration of this code.

Widgets

Widgets in Android are the mini apps that can be displayed on the home screen of the device. There is a fairly limited amount of things that can be displayed in Widgets. So unfortunately Widgets can’t be built with AIR for Android. However a custom application Widget can be packaged with an AIR for Android application. To add a Widget to an AIR for Android application you can use the default AppEntry class instead of wrapping it with another class (MainApp in my example). (It doesn’t, however, do any harm to keep the MainApp class there.) To add a Widget simply add its definition to the AndroidManifest.xml file, create the Widget with Java, and create a corresponding layout resource.

1. First define the Widget in the application section of the AndroidManifest.xml file:

   <receiver android:name=".AndroidWidget" android:label="app">
       <intent-filter>
           <action android:name="android.appwidget.action.APPWIDGET_UPDATE" />
       </intent-filter>
       <meta-data android:name="android.appwidget.provider" android:resource="@xml/airandroidwidget" />
   </receiver>

2. You need an XML resource that provides metadata about the widget. Simply create a new file named airandroidwidget.xml in a new res/xml directory with the following contents:

   <?xml version="1.0" encoding="utf-8"?>
   <appwidget-provider xmlns:android="http://schemas.android.com/apk/res/android"
       android:minWidth="294dp"
       android:minHeight="72dp"
       android:updatePeriodMillis="86400000"
       android:initialLayout="@layout/main">
   </appwidget-provider>

   This tells the widget to use the main layout resource as the initial layout for the widget.

3. Create a res/layout/main.xml file that contains a simple text display:

   <?xml version="1.0" encoding="utf-8"?>
   <LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
       android:id="@+id/widget"
       android:orientation="vertical"
       android:layout_width="fill_parent"
       android:layout_height="fill_parent"
       android:background="#ffffffff"
       >
   <TextView  
       android:layout_width="fill_parent" 
       android:layout_height="wrap_content" 
       android:text="hello"
       />
   </LinearLayout>

   Next, you’ll need to create the AppWidgetProvider class specified in the AndroidManifest.xml file.

4. Create a new Java class named AndroidWidget with the following contents:

   package com.jamesward;
    
   import android.app.PendingIntent;
   import android.appwidget.AppWidgetManager;
   import android.appwidget.AppWidgetProvider;
   import android.content.Context;
   import android.content.Intent;
   import android.widget.RemoteViews;
   import com.jamesward.MainApp;
    
   public class AndroidWidget extends AppWidgetProvider
   {
    
       public void onUpdate(Context context, AppWidgetManager appWidgetManager, int[] appWidgetIds)
       {
           final int N = appWidgetIds.length;
    
           // Perform this loop procedure for each App Widget that belongs to this provider
           for (int i=0; i<N; i++)
           {
               int appWidgetId = appWidgetIds[i];
               Intent intent = new Intent(context, MainApp.class);
               intent.setAction(Intent.ACTION_MAIN);
               PendingIntent pendingIntent = PendingIntent.getActivity(context, 0, intent, 0);
               RemoteViews views = new RemoteViews(context.getPackageName(), R.layout.main);
               views.setOnClickPendingIntent(R.id.widget, pendingIntent);
               appWidgetManager.updateAppWidget(appWidgetId, views);
           }
       }
   }

   This class will display the Widget when necessary and register a click handler that will open the MainApp application when the user taps on the Widget.

5. Run the application to verify that it works.
6. Now you can add the widget to the home screen by holding down on the home screen and following the Widget wizard.
7. Verify that tapping the widget launches the AIR application.

Application Licensing

Android provides APIs to help you enforce licensing policies for non-free apps in the Android Market. You might want to go read up on Android Licensing before you give this one a try.

To add Application Licensing to you AIR for Android application you first need to follow the steps outlined in the Android documentation. The broad steps are as follows:

1. Set up an Android Market publisher account
2. Install the Market Licensing Package in the Android SDK
3. Create a new LVL Android Library Project in Eclipse
4. Add a Library reference in the Android project to the LVL Android Library
5. Add the CHECK_LICENSE permission to your Android project’s manifest file:

   <uses-permission android:name="com.android.vending.CHECK_LICENSE" />

After completing these set up steps, you are ready to update the MainApp Java class to handle validating the license:

package com.jamesward;
 
import com.android.vending.licensing.AESObfuscator;
import com.android.vending.licensing.LicenseChecker;
import com.android.vending.licensing.LicenseCheckerCallback;
import com.android.vending.licensing.ServerManagedPolicy;
 
import air.Foo.AppEntry;
import android.os.Bundle;
import android.os.Handler;
import android.provider.Settings.Secure;
 
public class MainApp extends AppEntry {
 
    private static final String BASE64_PUBLIC_KEY = "REPLACE WITH KEY FROM ANDROID MARKET PROFILE";
 
    // Generate your own 20 random bytes, and put them here.
    private static final byte[] SALT = new byte[] {
        -45, 12, 72, -31, -8, -122, 98, -24, 86, 47, -65, -47, 33, -99, -55, -64, -114, 39, -71, 47
    };
 
    private LicenseCheckerCallback mLicenseCheckerCallback;
    private LicenseChecker mChecker;
    private Handler mHandler;
 
    @Override
    public void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        mHandler = new Handler();
        String deviceId = Secure.getString(getContentResolver(), Secure.ANDROID_ID);
        mLicenseCheckerCallback = new MyLicenseCheckerCallback();
        mChecker = new LicenseChecker(
            this, new ServerManagedPolicy(this,
                new AESObfuscator(SALT, getPackageName(), deviceId)),
            BASE64_PUBLIC_KEY);
        mChecker.checkAccess(mLicenseCheckerCallback);
    }
 
    private void displayFault() {
        mHandler.post(new Runnable() {
            public void run() {
                // Cover the screen with a messaging indicating there was a licensing problem
                setContentView(R.layout.main);
            }
        });
    }
 
    private class MyLicenseCheckerCallback implements LicenseCheckerCallback {
        public void allow() {
            if (isFinishing()) {
                // Don't update UI if Activity is finishing.
                return;
            }
            // Should allow user access.
        }
 
        public void dontAllow() {
            if (isFinishing()) {
                // Don't update UI if Activity is finishing.
                return;
            }
            displayFault();
        }
 
        public void applicationError(ApplicationErrorCode errorCode) {
            if (isFinishing()) {
                // Don't update UI if Activity is finishing.
                return;
            }
        }
    }
 
    @Override
    protected void onDestroy() {
        super.onDestroy();
        mChecker.onDestroy();
    }
}

Also add the following to a new res/layout/main.xml file in order to display an error when the license is denied:

<?xml version="1.0" encoding="utf-8"?>
<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
    android:orientation="vertical"
    android:layout_width="fill_parent"
    android:layout_height="fill_parent"
    >
 
  <TextView  
    android:layout_width="fill_parent" 
    android:layout_height="wrap_content" 
    android:text="@string/license_problem"
    />
 
</LinearLayout>

The text to display uses a string resource named “license_problem”, which must be added to the res/values/strings.xml file:

<string name="license_problem">THERE WAS A PROBLEM LICENSING YOUR APPLICATION!</string>

When the application runs it will check for a valid license. If the license comes back as valid then the AIR application will start and run as usual. However, if there is an invalid license then the application will set the ContentView to the R.layout.main resource, which displays the error message defined in the “license_problem” resource. To simulate different responses you can change the “Test Response” in your Android Market profile.

The Gory Details
I’ve wrapped up a generated AppEntry class and its resources to make the process of extending AIR for Android fairly easy. If you are interested in seeing how that is done, I’ve posted all of the source code on github.

Here is an overview of the procedure:

1. Use the AIR SDK to create an AIR for Android APK file.
2. Use the dex2jar utility to convert the AppEntry dex classes into a JAR file.
3. Pull the resource classes out of the JAR file so that they don’t conflict with the new resources.
4. Use apktool to extract the original resources out of the AIR for Android APK file.
5. Create a single ZIP file containing the airbootstap.jar file, resources, AndroidManifest.xml file, and assets.

Now you can simply copy and paste those dependencies into your Android project.

Conclusion
Hopefully this article has helped you to better understand how you can extend AIR for Android applications with Android APIs. There are still a number of areas where this method can be improved. For instance, I am currently working with the Merapi Project developers to get Merapi working with my method of extending AIR for Android. That will provide a better bridging technique for communicating between the AIR application and Android APIs. So stay tuned for more information about that. And let me know if you have any questions!

If you are building Flex apps and want to take advantage of AOP then Mixing Loom is probably a bit lower level than what you need. Mixing Loom combined with AS3 Commons Bytecode provides the foundation for AOP systems to be built on top of. We hope that by providing developers the hooks to modify bytecode that frameworks will emerge that provide application developers higher level APIs based on AOP. As Mike says, “Mixing Loom kicks off the Summer of AOP.”

If you are one of those developers who likes getting dirty with bytecode modification then you might want to check out the slides from the “Planet of the AOPs” session:

If you are still following along and looking for more details on how to use Mixing Loom, then keep reading. Flex applications are broken into at least two pieces. The first piece is the thing that displays the loading / progress bar. That is located on the first “frame” of an application’s SWF file. The rest of the application is on the second frame of the main SWF and possibly in other SWF files like Modules and/or Runtime Shared Libraries (RSLs). Mixing Loom provides two ways to modify the bytecode of a running application. First, using a custom preloader an application can modify its second frame and/or any Flex Modules before they are loaded into the VM. The second way is to use LoomApplication and a custom preloader, which allows an application to modify its second frame, modules, and/or RSLs (even the signed Flex Framework RSLs). Let’s walk through a simple example of an application that uses a custom preloader to modify a string that exists in its second frame.

Let’s take a simple object Foo that has a getBar method, which returns a string “a bar”:

package blah
{
public class Foo
{
  public function getBar():String
  {
      return "a bar";
  }
}
}

And here is a simple application that just displays the results of calling an instance of Foo’s getBar method:

<?xml version="1.0"?>
<s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
               xmlns:s="library://ns.adobe.com/flex/spark">
 
  <fx:Script>
    import blah.Foo;
  </fx:Script>
 
  <s:applicationComplete>
     var foo:Foo = new Foo();
     l.text = foo.getBar();
  </s:applicationComplete>
 
  <s:Label id="l"/>
 
</s:Application>

If you were to run this application as is then the Label would display “a bar” – as expected. But to give you an idea of how to do runtime bytecode modification let’s change the “a bar” string to something else. (BTW: If you are following along then you will need to pull down the mixingloom-core code from github and compile it on your own because we haven’t published a SWC for Mixing Loom yet.) The thing in Mixing Loom that actually does the bytecode modification is called a “Patcher” so we will need to create one of those that searches the bytecode for a string and then replaces that string. Before we do that, let me explain how a SWF file is structured. Every SWF file is a series of “tags”. There are many different tag types but the types we are interested in for bytecode modification are the ones that actually contain the ActionScript ByteCode (ABC). This is the DoABC tag – type 82. For a full list of SWF tags and their structures check out the SWF Spec. One of the tag types indicates an executable boundary called a Frame. As a SWF file is being loaded by Flash Player it is parsing it. When Flash Player parses a “ShowFrame” tag it knows it can load and run the preceding tags. The code doing the bytecode modification will be running on the first frame, which means that all of the tags to do the modification and those to display the Flex preloader will have already been loaded. That means we can’t modify those tags using this method at runtime. But we can modify the tags on the second frame of the SWF, which will be passed to our Patcher before they have actually been loaded.

Here is the code for the StringModifierPatcher:

package org.mixingloom.patcher
{
import flash.utils.ByteArray;
 
import org.as3commons.bytecode.tags.DoABCTag;
import org.as3commons.bytecode.util.AbcSpec;
 
import org.mixingloom.SwfContext;
import org.mixingloom.SwfTag;
import org.mixingloom.invocation.InvocationType;
import org.mixingloom.utils.ByteArrayUtils;
 
public class StringModifierPatcher extends AbstractPatcher
{
    public var originalString:String;
    public var replacementString:String;
 
    public function StringModifierPatcher(originalString:String, replacementString:String)
    {
        this.originalString = originalString;
        this.replacementString = replacementString;
    }
 
    override public function apply( invocationType:InvocationType, swfContext:SwfContext ):void
    {
        var searchByteArray:ByteArray = new ByteArray();
        AbcSpec.writeStringInfo(originalString, searchByteArray);
 
        var replacementByteArray:ByteArray = new ByteArray();
        AbcSpec.writeStringInfo(replacementString, replacementByteArray);
 
        for each (var swfTag:SwfTag in swfContext.swfTags)
        {
            if (swfTag.type == DoABCTag.TAG_ID)
            {
                swfTag.tagBody = ByteArrayUtils.findAndReplaceFirstOccurrence(swfTag.tagBody, searchByteArray, replacementByteArray);
            }
        }
 
        invokeCallBack();
    }
 
}
}

The StringModifierPatcher extends the Mixing Loom AbstractPatcher and takes two parameters, the originalString and the replacementString. The StringModifierPatcher has an apply method, which will be called by Mixing Loom during application startup. In the apply method the StringModifierPatcher creates a search ByteArray and a replacement ByteArray from the provided strings. Then it loops through each tag from the second frame of the SWF being loaded (ignoring everything that is not a DoABC tag) and then uses Mixing Loom’s ByteArrayUtils.findAndReplaceFirstOccurrence utility to replace the first occurrence of the search ByteArray with replacement ByteArray. Finally it notifies Mixing Loom that it is all done by calling the invokeCallBack method. So that is the simple example of actually modifying the application, but we still need to set the hooks in the main application so that Mixing Loom can do its thing.

Since this example only modifies frame 2 tags (no RSLs), we can just use a custom preloader to set up the Mixing Loom hooks. Here is the StringModifierPatcherPreloader:

package preloader {
import org.mixingloom.managers.IPatchManager;
import org.mixingloom.patcher.StringModifierPatcher;
import org.mixingloom.preloader.AbstractPreloader;
 
public class StringModifierPatcherPreloader extends AbstractPreloader {
    override protected function setupPatchers(manager:IPatchManager):void {
        super.setupPatchers(manager);
        manager.registerPatcher( new StringModifierPatcher("a bar", "not really a bar") );
    }
}
}

The StringModifierPatcherPreloader extends Mixing Loom’s AbstractPreloader and uses the setupPatchers method to register a new patcher. In this case the only patcher is an instance of the StringModifierPatcher that will search for the default “a bar” string and replace it with the “not really a bar” string.

The last thing to make this all work is to tell the main application to use the new preloader:

<s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
               xmlns:s="library://ns.adobe.com/flex/spark"
               preloader="preloader.StringModifierPatcherPreloader">

Here is the result:

Exciting! Our application code just modified itself at startup! Now this is obviously a very trivial example but I hope it provides a basic understanding of how to use Mixing Loom as the foundation for AOP. Let’s walk through some other examples that are more exciting (and complex).

For the next example let’s do something a little more AOP-ish. There will be an XML configuration file that is loaded on startup that will specify some classes and methods to apply interceptors to. An interceptor is simply a method call injected into the body of a method. First, here is the FooInterceptor class:

package
{
import mx.core.FlexGlobals;
 
public class FooInterceptor
{
    public static function interceptAll():void
    {
        FlexGlobals.topLevelApplication.setStyle("backgroundColor", Math.random() * 0xffffff);
    }
}
}

For demo purposes this interceptor is very simple – it just changes the application’s background color. Here is the XML configuration file that the application will load on startup to determine where to apply the interceptor:

<interceptors>
    <interceptor>
        <swfTag>blah/Foo</swfTag>
        <methodEntryInvoker>
            <className>FooInterceptor</className>
            <methodName>interceptAll</methodName>
        </methodEntryInvoker>
    </interceptor>
</interceptors>

In this case it is saying to only apply the interceptor to the SWF tag with the name “blah/Foo”. In a debug version of the application the Foo class from above will be in its own SWF tag named “blah/Foo”. The reason that the SWF tag is specified in this case is because by doing this the application won’t need to deserialize and reserialize every class. The downside to doing things this way is that it won’t work if we create an optimized SWF where all of the frame 2 classes are contained in one SWF tag. With some more work in AS3 Commons Bytecode we could optimize things for this kind of use case. Volunteers? :) The methodEntryInvoker simply specifies the class and method name to call on method entry. This interceptor will be added to every method, on every class in the SWF tag with the name “blah/Foo”.

Now for the fun part… Here is the patcher that loads the XML config file, parses it, and then applies the interceptor:

package patcher {
import flash.events.Event;
import flash.events.TimerEvent;
import flash.net.URLLoader;
import flash.net.URLLoaderDataFormat;
import flash.net.URLRequest;
import flash.utils.ByteArray;
 
import org.as3commons.bytecode.abc.AbcFile;
import org.as3commons.bytecode.abc.InstanceInfo;
import org.as3commons.bytecode.abc.LNamespace;
import org.as3commons.bytecode.abc.MethodInfo;
import org.as3commons.bytecode.abc.Op;
import org.as3commons.bytecode.abc.QualifiedName;
import org.as3commons.bytecode.abc.enum.Opcode;
import org.as3commons.bytecode.io.AbcSerializer;
 
import org.mixingloom.SwfContext;
import org.mixingloom.SwfTag;
import org.mixingloom.invocation.InvocationType;
import org.mixingloom.patcher.AbstractPatcher;
 
import org.as3commons.bytecode.io.AbcDeserializer;
 
public class SampleXMLPatcher extends AbstractPatcher {
 
    public var url:String;
 
    private var swfContext:SwfContext;
 
    public function SampleXMLPatcher(url:String) {
        this.url = url;
    }
 
    override public function apply( invocationType:InvocationType, swfContext:SwfContext ):void {
        if (invocationType.type == InvocationType.FRAME2) {
 
            this.swfContext = swfContext;
 
            var urlLoader:URLLoader = new URLLoader();
            urlLoader.dataFormat = URLLoaderDataFormat.TEXT;
            urlLoader.addEventListener(Event.COMPLETE, handleXMLLoad);
            urlLoader.load(new URLRequest(url));
        }
        else {
            invokeCallBack();
        }
    }
 
    private function handleXMLLoad(event:Event):void {
        var xmlData:XML = new XML((event.currentTarget as URLLoader).data as String);
 
        var swfTagName:String = xmlData.interceptor.swfTag;
        var methodEntryInvokerClassName:String = xmlData.interceptor.methodEntryInvoker.className;
        var methodEntryInvokerMethodName:String = xmlData.interceptor.methodEntryInvoker.methodName;
 
        var methodEntryInvokerClassQName:QualifiedName = new QualifiedName(methodEntryInvokerClassName, LNamespace.PUBLIC);
        var methodEntryInvokerMethodQName:QualifiedName = new QualifiedName(methodEntryInvokerMethodName, LNamespace.PUBLIC);
 
        for each (var swfTag:SwfTag in swfContext.swfTags) {
            if (swfTag.name == swfTagName) {
 
                // skip the flags
                swfTag.tagBody.position = 4;
 
                var abcStartLocation:uint = 4;
                while (swfTag.tagBody.readByte() != 0) {
                    abcStartLocation++;
                }
                abcStartLocation++; // skip the string byte terminator
 
                swfTag.tagBody.position = 0;
 
                var abcDeserializer:AbcDeserializer = new AbcDeserializer(swfTag.tagBody);
 
                var abcFile:AbcFile = abcDeserializer.deserialize(abcStartLocation);
 
                for each (var instanceInfo:InstanceInfo in abcFile.instanceInfo) {
 
                    for each (var methodInfo:MethodInfo in instanceInfo.methodInfo) {
                        var startIndex:uint = 0;
                        for each (var op:Op in methodInfo.methodBody.opcodes) {
                            startIndex++;
                            if (op.opcode === Opcode.pushscope) {
                                break;
                            }
                        }
 
                        var findOp:Op = new Op(Opcode.findpropstrict, [methodEntryInvokerClassQName]);
                        var getOp:Op = new Op(Opcode.getproperty, [methodEntryInvokerClassQName]);
                        var callOp:Op = new Op(Opcode.callproperty, [methodEntryInvokerMethodQName, 0]);
 
                        methodInfo.methodBody.opcodes.splice(startIndex, 0, findOp, getOp, callOp, new Op(Opcode.pop));
                    }
                }
 
                var abcSerializer:AbcSerializer = new AbcSerializer();
                var modifiedBytes:ByteArray = new ByteArray();
                modifiedBytes.writeBytes(swfTag.tagBody, 0, abcStartLocation);
                modifiedBytes.writeBytes(abcSerializer.serializeAbcFile(abcFile));
 
                swfTag.tagBody = modifiedBytes;
            }
        }
 
        invokeCallBack();
    }
}
}

The constructor for this patcher takes a URL, which is used to specify the XML config file. Then in the apply method, if the invocation type is “FRAME2″ (meaning the patcher is being applied to the SWF tags on the second frame of the loading SWF) then it uses URLLoader to load the XML config file. Notice that URLLoader is used, not HTTPService. That is because anything that goes into a patcher is put on the first frame of the SWF and if HTTPService was used here, then there would be a ton of additional classes (dependencies) that would need to also be moved to the first frame. While technically this would work, it’s not a good practice because the more that is on the first frame, the longer the user has to wait before the preloader shows up (remember: all of the frame must be transferred across the network before the frame is loaded into the VM). If the invocation type is not “FRAME2″ then the invokeCallBack method is called to tell Mixing Loom that this patcher is done with the current invocation. Side note: patchers can block for as long as they want. Nothing moves forward in Mixing Loom until a patcher calls the invokeCallBack method.

When the data for the XML file arrives it is parsed using the E4X library. Then new QualifiedName instances are created based on the interceptor’s class and method names. Now the SWF tag with the name specified in the XML file is processed. First it is deserialized by AS3 Commons Bytecode. This provides an object representation of the underlying ABC code contained in the SWF tag. Then for every class and method the interceptor is applied at the beginning of the method. Kinda. There are a few operations that must happen at the very beginning of the method. For each method being intercepted we need to move past the “pushscope” opcode before we can insert new opcodes. Then four new opcodes are spliced into the array of opcodes for the method: findpropstrict, getproperty, callproperty, and pop. Those four opcodes are the ABC equivalent of calling the static method on the specified interceptor class. In this case the rest of the opcodes in the method will be left alone. Finally the ABC is recreated using AS3 Commons Bytecode and the original SWF tag is overwritten and the invokeCallBack method is called.

Just like before we need a custom preloader to register the patchers:

package preloader {
import org.mixingloom.managers.IPatchManager;
import org.mixingloom.preloader.AbstractPreloader;
 
import patcher.SampleXMLPatcher;
 
public class SampleXMLPatcherPreloader extends AbstractPreloader {
 
		override protected function setupPatchers(manager:IPatchManager):void {
			super.setupPatchers(manager);
			manager.registerPatcher( new SampleXMLPatcher("interceptors.xml"));
		}
	}
}

Notice that a new instance of the SampleXMLPatcher is created and given the URL to the interceptor XML file. Here is a little test application containing a button that calls Foo’s getBar method every time it’s clicked:

<?xml version="1.0"?>
<?xml version="1.0"?>
<s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
               xmlns:s="library://ns.adobe.com/flex/spark"
               preloader="preloader.SampleXMLPatcherPreloader">
 
    <fx:Script>
        import blah.Foo;
        import FooInterceptor; FooInterceptor;
    </fx:Script>
 
 
    <s:Button label="call foo.getBar()" fontSize="32" top="20" horizontalCenter="0">
        <s:click>
                var foo:Foo = new Foo();
                foo.getBar();
        </s:click>
    </s:Button>
 
</s:Application>

Notice that since there wasn’t a reference anywhere else to the FooInterceptor we had to include one manually otherwise it will not exist in the compiled SWF. Here is a demo of that application:

Well, that was fun! And I hope you can see how Mixing Loom can be the foundation for doing AOP in Flex / ActionScript! But before I let you go I want to show you one more crazy thing we can do with Mixing Loom. Patchers can do just about anything they want since Mixing Loom provides hooks to modify the second frame, RSLs, and Modules. For instance, say there is a private method or property in the Flex framework that you need access to. One option is to use Monkey Patching to replace that class with one that you maintain. This is not a very maintainable way to get access to something that is private. Using Mixing Loom you can simply patch the class at runtime. Here is a simple (but impractical) example… The spark.components.Application class has a private method called “debugTickler” on it. Using the RevealPrivatesPatcher from Mixing Loom we can make that method public at runtime. First extend the base RevealPrivatesPatcher class and tell it only to apply the patcher on the “spark_” RSL:

package {
import org.mixingloom.SwfContext;
import org.mixingloom.invocation.InvocationType;
import org.mixingloom.patcher.RevealPrivatesPatcher;
 
public class MyRevealPrivatesPatcher extends RevealPrivatesPatcher {
 
    override public function apply( invocationType:InvocationType, swfContext:SwfContext ):void {
        if ((invocationType.type == InvocationType.RSL) && (invocationType.url.indexOf("spark_") >= 0)) {
            super.apply(invocationType, swfContext);
        }
        else {
            invokeCallBack();
        }
    }
}
}

Then create a custom preloader that registers a new instance of MyRevealPrivatesPatcher and tells it to reveal the “spark.components:Application” class and the “debugTickler” method:

package preloader {
import org.mixingloom.managers.IPatchManager;
import org.mixingloom.preloader.AbstractPreloader;
 
	public class RevealPrivatesPatcherPreloader extends AbstractPreloader {
 
		override protected function setupPatchers( manager:IPatchManager ):void {
			super.setupPatchers( manager );
			manager.registerPatcher( new MyRevealPrivatesPatcher("spark.components:Application", "debugTickler") );
		}
 
	}
}

Finally, use the LoomApplication and the custom preloader in order to have the hooks to patch RSLs:

<?xml version="1.0"?>
<ml:LoomApplication xmlns:fx="http://ns.adobe.com/mxml/2009"
                    xmlns:ml="library://ns.mixingloom.org/flex/spark"
                    xmlns:s="library://ns.adobe.com/flex/spark"
                    preloader="preloader.RevealPrivatesPatcherPreloader">
 
    <ml:applicationComplete>
            try {
                this['debugTickler']();
                l.text = "Yeah.  We just modified an RSL at runtime.";
            } catch (e:Error) {
                l.text = "booo";
            }
    </ml:applicationComplete>
 
    <s:Label id="l" text="nothing happened."/>
 
</ml:LoomApplication>

Notice that we can’t use the dot syntax “this.debugTickler()” to call the method since the compiler won’t let us do that. Instead we have to use the object key syntax “this['debugTickler']()” in order to make the method call. Now watch as Mixing Loom’s magic wand modifies a signed Flex Framework RSL right before your very eyes:

Fun stuff!!! And there is more to come! We are working on ways to also modify the first frame of the SWF and to modify a SWF pre-runtime. But now it’s your turn! All of the code for everything you’ve seen here, as well as some other demos, and goodies is all on github. We’d love to see the community create some interesting and useful patchers! So fork away and have fun! Let me know if you have any questions.

I used my Census SOAP Service as a simple service to test this with. In this case, my WSDL is publicly available at: http://www.jamesward.com/census2-tests/services/CensusSOAPService?wsdl

First, I created a new Flex project and saved the WSDL into the src dir of the project. I built a simple test program using the WebService API directly:

<?xml version="1.0" encoding="utf-8"?>
<s:Application xmlns:fx="http://ns.adobe.com/mxml/2009" 
			   xmlns:s="library://ns.adobe.com/flex/spark">
 
	<fx:Declarations>
		<s:WebService id="ws" wsdl="http://www.jamesward.com/census2-tests/services/CensusSOAPService?wsdl"/>
	</fx:Declarations>
 
	<s:applicationComplete>
		ws.getElements(0, 50);
	</s:applicationComplete>
 
	<s:DataGrid dataProvider="{ws.getElements.lastResult}" width="100%" height="100%"/>
 
</s:Application>

Then I ran the application in Chrome with the Network view open in the Chrome Developer Tools panel. This indicated that, just as expected, the WSDL is used at runtime:

Next I had a look around the WebService source code (available in <FLEX_SDK>/frameworks/projects/rpc/src/mx/rpc/soap) and discovered there is a loadWSDL method that can be overwritten to handle the embedded loading of the WSDL instead of the default network loading of the WSDL. So I created a new class that extends the base WebService class, embeds the WSDL file, and overrides the loadWSDL method:

package
{
	import mx.core.ByteArrayAsset;
	import mx.core.mx_internal;
	import mx.rpc.events.WSDLLoadEvent;
	import mx.rpc.soap.mxml.WebService;
	import mx.rpc.wsdl.WSDL;
 
	use namespace mx_internal;
 
	public dynamic class MyWebService extends WebService
	{
		[Embed(source="CensusSOAPService.xml", mimeType="application/octet-stream")]
		private static const WSDL_CLASS:Class;
 
		public function MyWebService(destination:String=null)
		{
			super(destination);
			loadWSDL();
		}
 
		override public function loadWSDL(uri:String=null):void
		{
			var thing:Object = new WSDL_CLASS();
			var baa:ByteArrayAsset = (thing as ByteArrayAsset);
			var xml:String = baa.readUTFBytes(baa.length);
 
			deriveHTTPService();
 
			var wsdlLoadEvent:WSDLLoadEvent = WSDLLoadEvent.createEvent(new WSDL(new XML(xml)));
			wsdlHandler(wsdlLoadEvent);
		}
	}
}

In the regular WebService class, setting the wsdl property will trigger the loadWSDL method, but since we are embedding the WSDL, we must manually call the loadWSDL method. I do that in the constructor.

Embedded assets become a class, so first an instance of that class must be instantiated as a ByteArrayAsset (the default type for files embedded with the application/octet-stream mimeType). Then the instance is read into a string. Then the deriveHTTPService method is called to set up the underlying HTTPService‘s channel information. Finally, we create a WSDL object from the XML that was read from the ByteArrayAsset, create a new WSDLLoadEvent with the WSDL, and call the wsdlHandler method, passing it the wsdlLoadEvent. This essentially is doing the same thing as the original WebService class, but now doing it without the network request.

I can now switch my test application to use my extension to WebService instead of the original one:

	<fx:Declarations>
		<local:MyWebService xmlns:local="*" id="ws"/>
	</fx:Declarations>

Now when I run the application and monitor the network activity I no longer see the WSDL being requested at runtime! So everything works when using the WebService API directly. However, the customer I was working with was using the Service wizard in Flash Builder. So we needed to figure out how to get the generated code to use the new WebService extension instead of the original WebService class. I went through the Data Wizards and had it generate the client-side stubs for my Census SOAP Service. This created a CensusSOAPService class that extends the generated _Super_CensusSOAPService class. The CensusSOAPService is intended to give us a place to make modifications to the generated stuff, while the _Super_CensusSOAPService class is not supposed to be modified because it will be overwritten if we refresh the service. Looking in the _Super_CensusSOAPService class I discovered that the WebService instance is being created directly in the constructor:

    public function _Super_CensusSOAPService()
    {
        // initialize service control
        _serviceControl = new mx.rpc.soap.mxml.WebService();
 
        // rest of method omitted
    }

These are the kinds of things that really make you wish the Flex framework used dependency injection because we need to set _serviceControl from the CensusSOAPService class. So we thought… Alright, this is not ideal but we can just copy the contents of the _Super_CensusSOAPService‘s constructor into CensusSOAPService‘s constructor, replace the line that instantiates the WebService, have it instantiate MyWebService instead, and then just not call super(). We gave it a try and for some reason kept getting _serviceControl set as a WebService not MyWebService. WTF? It made no sense until we found this little gem in the Flex docs:
“If you define the constructor, but omit the call to super(), Flex automatically calls super() at the beginning of your constructor.”
Now it all made sense! Since we didn’t call super(), Flex conveniently inserted a super() call for us! Fun. So we had to figure out a way to convince the Flex compiler that we were going to call super(), but then not call it.

if (0)
{
    super();
}

Voila! Now the CensusSOAPService‘s constructor sets _serviceControl to a new instance of MyWebService and _Super_CensusSOAPService doesn’t get the chance to mess that up.

We tested the new CensusSOAPService and everything worked perfectly!

I hope that helps some of you who are using the Flex WebService API. Let me know if you have any questions.

Very fun stuff! Let me know what you think.

public class Foo {
  private function getPrivateBar():String {
    return "private bar";
  }
}

var foo:Foo = new Foo();
foo['getPrivateBar']();

Yup! It’s gonna be fun! The session will be on Tuesday April 12th at 2:50pm. Hope to see you there!

Also, Mike and I are doing a 360|Flex speaker chat today at 11am (MDT).