My previous Merapi tutorial is by far one of the most popular posts on this blog. It is however out of date by now since a new version of Merapi has been released. The previous tutorial was based on an Alpha release, while this tutorial is based on the 0.1.8 Beta release. The API between the alpha and beta has changed quite a bit, which is why I decided to write a new tutorial instead of simply updating the old one. This tutorial is aimed at beginners, but hopefully more seasoned coders will also find something useful in it.
So, on with the show. Since you’re reading this, I assume you at least know about Merapi. In case you don’t, head over to the Merapi site and read through the basics.
The app I built here is an extension of the application in the previous tutorial. We’re still looking at round trip times, but in order to show of Merapi’s capabilities to send more complex data, I’m also adding a basic byte packet and some memory usage information. The source code is well documented and should describe what the different parts do, so I won’t go into all the details of the code in this tutorial. I’ll just guide you through the setup and highlight some general things regarding Merapi instead.
The first part of this tutorial is all about setting up SVN access to get the Merapi source and setting up the tutorial source projects. If you just want some pointers on working with Merapi, feel free to jump directly to Notes on working with Merapi.
Prerequisites
To follow this tutorial, you’ll need the following:
- Flash Builder 4 Beta 1 plugin for Eclipse installed and running (since we’ll be using the Flex 3.4 SDK you should be fine using Flex Builder 3 also) (download free trial from Adobe website)
- The source files for this tutorial (download here). Contains Eclipse projects for both the Java and AIR project.
- About 30 minutes to spare, and intially some patience
I’m assuming that you know your way around the Eclipse IDE and Flash builder. I also assume you’ve done at least some Hello world level applications in both Java and Flex and know the basics of debugging (Since Merapi is still beta software, you might run into some odd problems here and there). Having said that, if you do get stuck feel free to post your questions in the comments and I’ll try to help. Also, if you notice that someone has asked a question that you know the answer to, feel free to post the answer if I haven’t had a chance yet.
My Eclipse install is running on OS X 10.5, so if you run Windows you’ll need to adjust paths etc. to suit your environment. Also, as I said earlier, I’m using Flash builder 4 beta 1. You should be able to use Flex Builder 3 also, but some of the screen shots might look a bit different.
Getting the framework
I could have added the framework to the source package of the tutorial, but since it’s a beta project I’m thinking you’ll be better off knowing how to get the latest from the SVN repository instead so that you can keep up to date. So, the first step will be to setup Eclipse to fetch the Merapi source from the Merapi Google SVN repository.
Make sure you have the package explorer view visible in Eclipse (menu: Window->Show view->Package Explorer). Control-click (Win: right click) in an empty area of the Package Explorer and choose Import. Type SVN into the filter input or browse the options to find the Checkout Projects from SVN option. Choose it and click next.
In the next screen, choose Create a new repository location and press Next. Paste the URL http://merapi.googlecode.com/svn/trunk/ into the location input field and press Next again.
Eclipse will work a bit before asking you to choose a folder to checkout from SVN. Choose trunk/java/merapi-core and press Next.
Eclipse again works a bit and should then present you with a view where you can choose the type of checkout. Set Check out as project configured using the New Project Wizard, leave everything else as default and press Finish. The New Project Wizard will open. Choose to create a new Java project, then click Next. Give the project a name (I set it to merapicore.java), set it to create new project in workspace and press Finish. Click ok if Eclipse warns you about overwriting some sources in the future. Eclipse will start to download the java source files from SVN.
Once the Java sources have been downloaded, Eclipse will moan about a whole bunch of errors in the source files. This is because we haven’t linked in the libs that are required by the source. Control-click (Win: right-click) on the Java project in the Package Explorer, open Java Build Path and the libraries tab. Click Add JARs, open up the merapicore.java/libs folder and select all *.jar references you see, then click OK. Your Java build path should look something like this:
Click ok and all the compiler errors should be gone.
Next, we’ll do the same for the Flex source files. Control-click on an empty area in the Package explorer, choose import, then Checkout Projects from SVN. In the Select location view the repository location we used for the Merapi Java project should exist, so you can choose it from the list and click next. In the select folder view, instead of choosing the java folder, choose flex/merapi-core and click Next. Again choose Check out as project configured using the New Project Wizard. In the New project wizard, choose to create a Flex library project and click Next. Give the project a name (I gave mine merapicore_flex (sidenote: someone please explain to me why library project names cannot contain dots) and set the Flex SDK to be 3.4. Leave the rest at default and choose Finish.
Once the sources have downloaded Eclipse will moan that nothing was selected to be included in the library. Control-click on the Flex project in the package, choose properties->Flex library build path and in the Classes tab put a check next to the src folder, then press ok. The error should be gone.
You now have two projects in your workspace that you can always use to get the latest version of Merapi onto your computer. Simply Control-click on the projects in the package explorer and choose Team->Synchronize with repository.
Import the tutorial source files
If you haven’t done so yet, download the tutorial source files zip. Then continue reading.
Open the Java perspective in the Eclipse IDE (Window->Open perspective->Java). Control-click an empty area in the Package Explorer and choose Import. In the Import dialog, choose Existing projects into workspace and press Next. In the Import projects dialog, choose Select archive file and browse to the zip file you downloaded. Once you’ve selected the zip and pressed open, your view should look like this:
Press Finish.
Since the projects that you imported still have some of the settings from my workspace, we’re going to have to change that before the projects can compile. First Control-click the imported AIR project in the Package Explorer and choose properties->Flex Build path and open the Library tab. Select the libs folder and click Remove. Do the same for the merapicoreflex.swc. Click Add SWC, browse to the bin folder of the merapicore_flex project and choose the swc from there. Your properties should look like this:
MerapiStats AIR project build path
Press ok and Eclipse should not give any errors on the AIR project anymore. Next right click on the MerapiStats.java project, choose properties->Java build path and the Source tab. Remove the source folder that points to MerapiStats.java/MerapiStats-core
then click Link Source. Browse to the src folder in the merapicore.java project we downloaded from SVN. If you want you can give the folder a more descriptive name also. It should look something like this:
Press Finish then open the Libraries tab. Remove all linked in *.jar resources except the JVM, then click Add JARs. These are the same steps as we did before when working with the Merapi java source project, so choose all *.jar resources in the merapicore.java/libs folder and press ok. Your build path should look like this:
MerapiStats java project build path
Click Finish to close the properties panel.
Provided all went well, you should now be able to run the projects. The order however is important. You first need to start the Java application, then start the AIR application. Otherwise the AIR application will throw a security error eventually since it cannot connect to the Java application. So first, open the src->(default package) of the MerapiStats.java project, Control-click the MerapiStatsRunner.java file and choose Debug As->Java Application. The console should output the following messages
log4j:WARN No appenders could be found for logger (merapi.Bridge).
log4j:WARN Please initialize the log4j system properly.
IntiMessageHandler created
PingMessageHandler created
Java runner initialized
Next, Control-click the MerapiStats.air project and choose Debug As->Desktop Application. If all goes well the AIR app starts and the TextArea is populated with the text Bridge connection established. Click the Start button and you should start to see lines drawn in the graphs as in the screen shot below:
Screen shot of MerapiStats AIR application
Notes on working with Merapi
In order to start up the Merapi bridge on the Java side, you call
MessageHandler-objects are what you use to listen for data that is passed over the bridge (this goes for both the Java and the Flex code). You should extend the MessageHandler class to provide your own implementation of the handleMessage method. This is the method that gets called when a message is received by the handler. You register a MessageHandler to handle a message of a particular type by calling addMessageType() or by passing the type into the constructor of a MessageHandler object. One MessageHandler can register interest in several different types of messages. Simply call addMessageType() for each type of message that should be handled. How many MessageHandler classses you create is of course entirely up to you, but any complex project will probably require more than one.
You can think of Messages as being similar to Events in AS3. They both should be kept simple and they both act as data transfer objects or notify a listener that something has changed. Compared to the Events of AS3, a Message has one important difference, the send() method. This is what you use in order to send a message over the Merapi bridge. So basically all it takes to send a message over the bridge is to create an instance of a Message and call the myMessage.send() method. e.g.
var myMessage:MyCustomMessage = new MyCustomMessage(”myMessageType”);
-
myMessage.send();
Then have a MessageHandler on the other side that has been registered to handle messages of type myMessageType.
Extend the Message class in order to add any custom data you want to transfer. Messages can contain complex data also and variable types are automatically converted to their corresponding type in both ends of the bridge.
Note that you never actually create an instance of a Bridge (as you did before when working with the Alpha of Merapi). It is all handled implicitly through MessageHandlers and Messages now.
That’s it for me, hope this tutorial was useful for you. If you have any questions or feedback, feel free to post a comment.
Additional resources:
