Category Archives: Mobile Development

Hacking the OSCON 2014 Schedule with Codename One & Mirah

I gave a tutorial on Codename One at OSCON this year. Part way through the conference, I learned that OSCON had published its schedule as a public JSON feed and were encouraging developers to create their own schedule apps out of it. I was too busy at the time – but I wish I had known about this before hand as it would have made for a good subject for the tutorial. Alas, five months too late, here is a rough stab at this challenge, for the purpose of showing off a Mirah macro I just developed to make JSON Parsing easier in Codename One.

The State of JSON Parsing In Codename One

Codename One apps are Java apps, so they usually consist of a well-structured data model of Java classes and their instantiated objects. JSON (Javascript Object Notation) data is not strongly typed. It encapsulates a generic tree of maps, lists, and primitive data types. Codename One can easily parse JSON strings to a corresponding but generic data structure consisting only of java.util.Maps, java.util.Lists, Strings, and Doubles:

   JSONParser parser = new JSONParser();
   Map data = parser.parseJSON(jsonString);

This is a start, but it is not satisfactory. For example, our schedule application will have classes like Schedule, Event, Speaker, and Venue. We will definitely want to convert this Map into more specific Java types to help achieve a better level of abstraction in our app. But how?

Currently We need to Manually copy the contents of the generic data structure into the associate java types : Tedious and Error-prone

Why can’t we use a library like Jackson?

Libraries that automate the mapping of JSON data to Java types (like Jackson does) all require reflection. Codename One doesn’t support reflection because it needs to know what code is being used before it is deployed as a means of optimizing the performance and size of the app. If it were changed to support reflection, it would mean that the entire Java class library would have to be included in the app because the compiler wouldn’t know until runtime which classes were in use.

So using a library to handle this is out.

Mirah Macros to the Rescue

If you’ve been following any of my recent development, you know that I have been getting pretty deep into Mirah lately. Why Mirah?

It provides Ruby-like syntax, yet compiles directly to .class files with no runtime dependencies. This makes it ideal for Codename One development. You get all of the performance of Java but the productivity of Ruby.

In order to be able to use Mirah in my own projects, I developed a plugin for NetBeans that allows you to include Mirah source inside existing Java projects and work interchangeably with Java source. This capability is handy since some things are still better done in Java. It also allows me to sprinkle little bits of Mirah into my projects as I see fit.


One of the most powerful features of Mirah is its support for macros. A Mirah macro is a bit of code that is executed at compile time and is able to modify the AST. This allows you to do cool things like add properties and methods to classes, or even generate new classes entirely. This ability is also very powerful for Codename One development as it gives us the ability to perform compile-time reflection.

The data_mapper Macro

I created a macro named data_mapper that generates a class that knows how to convert between JSON and objects of a particular class. It works as follows:

   data_mapper MyClass:MyClassMapper

This generates a class named MyClassMapper that knows how to convert between JSON data and objects of MyClass. All generated “mapper” classes are subclasses of DataMapper.

The OSCON Schedule

The OSCON schema includes 4 types:

  1. Schedule : The umbrella structure.
  2. Event : Represents a single event on the schedule.
  3. Speaker : Represents a speaker at OSCON.
  4. Venue : A venue or room.

In my OSCON application, I created 4 corresponding classes. A simplified version of the Schedule class is:

    public class Schedule {
        private List<Event> events;
        private List<Speaker> speakers;
        private List<Venue> venues;

        // getters & setters, etc...

And the Event class is roughly:

public class Event {
    private String serial;
    private String name;
    private String eventType;
    private String venueSerial;
    private String description;
    private String websiteUrl;
    private Date timeStart;
    private Date timeStop;

    private List<String> speakers;
    private List<String> categories;

    // getters & setters, etc...

Parsing the JSON schedule into my class types, first, involved using the data_mapper macros to generate mappers for my classes:

data_mapper Event:EventMapper
data_mapper Venue:VenueMapper
data_mapper Speaker:SpeakerMapper
data_mapper Schedule:ScheduleMapper

The following is the sum total of the code that is used to actually load the JSON feed and parse it into my Java types:

ScheduleMapper scheduleMapper = new ScheduleMapper();
        new EventMapper(),
        new VenueMapper(),
        new SpeakerMapper()
), new DataMapper.Decorator() {

    public void decorate(DataMapper mapper) {
Schedule schedule = scheduleMapper.readJSONFromURL(

Let’s walk through this example, because there are a couple of implementation details included in this example because it is real-world, and thus not completely trivial.

  1. If we were only mapping a JSON feed that contained a single Java type, we could just instantiate the DataMapper object and parse the feed. However, since there are multiple types in the feed, and the mappers need to know to use each other (e.g. The EventMapper needs to know that when it encounters a Speaker, that it should use the SpeakerMapper etc..), we need to set up a shared context. That is what the DataMapper.createContext() call does. It binds all of the mappers together so that they work as one.
  2. The properties in the JSON feed use snake_case, whereas our Java classes use camelCase for their properties respectively. We use the setReadKeyConversions() method on all mappers to specify that it should convert these automatically.
  3. The readJSONFromURL() method includes a third parameter that specifies the sub-key that is treated as the root of the data structure. Without this it would try to map the top-level JSON object to the Schedule object which would fail. (The schedule is contained in a sub-object with key Schedule).

There are other settings that you can play with such as date formats, but luckily the rest of the default settings work fine with this JSON feed.

At this point, the schedule object is completely populated with the OSCON schedule data, so it can be used to build our app.

Painless, right?


Screen Shot 2014-12-05 at 6.40.35 PM

Screen Shot 2014-12-05 at 6.40.57 PM

Screen Shot 2014-12-05 at 6.40.47 PM

Download the App Source Code

This app is just a work in progress, but it may form the foundation for your own schedule app if you choose. You can download the source from GitHub here.

Build Instructions

Requires Netbeans 7.4 or higher with the following plugins installed:

  1. Codename One
  2. Netbeans Mirah Plugin
  3. Netbeans CN1ML Plugin


  1. Clone the cn1-mirah-json-macros Gitub Project clone
  2. Open the OSCONSchedule project that is a subdirectory of the main project directory, in NetBeans.
  3. Build the project. Modify it at will


Apache 2.0


I created a short screencast of this tutorial so you can see the data_mapper macro in action.


  1. Codename One Homepage
  2. DataMapper API Docs
  3. Codename One Reflection Utilities Download – Contains the libraries necessary to do the JSON parsing in a Codename One app.
  4. Mirah Netbeans Module
  5. OSCON App Source
  6. OSCON DIY Schedule JSON Feed

CN1ML: Using HTML to Design Codename One User Interfaces

post-header In Codename One, you traditionally have two choices for designing user interfaces:

  1. Use the GUI builder (i.e. WYSIWYG)
  2. Code the UI manually

Although the GUI builder is great, I often find myself coding the UI by hand because it gives me the most control – and it lets me get directly to the code. Of course, you can mix and match GUI builder GUIs with custom code, and I often do. E.g. I’ll set up each Form’s structure in the GUI builder and populate the details in code. Sometimes shifting back and forth between a WYSIWYG context and Java source code can be trying, though.. For some reason, I don’t like shifting gears. When I’m working in code, I like to dive deep in code and look at nothing else but code. When I’m doing desktop WYSIWYG designs, I want to stay in that environment. But I don’t alternate between them terribly well.

Anyhoo… so that’s why I sometimes find myself coding the entire UI in Java.

This has an ENORMOUS down-side, though. For simple UIs with under 5 components, it is manageable. But when you start to get into a complex UI with multiple levels of nested containers, things become something of a mess. And when you go back to modify the code later, it can be difficult to tell the forest from the trees.

A Codename One UI form is very similar to the HTML document model. It defines a tree structure of user interface components. Expressed in HTML, tree-based document models are quite clean and easy to navigate. It is easy to tell which tags are parents of other tags. Not so with Java code. So I thought:

Wouldn’t it be great if I could express my user interface in HTML?

So I set off to do just that.


Before starting on this mission, I had a few requirements in my head:

  1. The HTML should compile down to Java source code so that it can be compiled just like all of the rest of the classes in Codename One. I.e. The HTML should not be parsed, processed, or converted at runtime. It should be handled completely at compile-time. The reason for this is that we want the build server to be able to optimize the app executables and strip out unneeded classes to keep the app file-size down. It knows how to do this for Java source code, but not with extra HTML files that I might provide to it.
  2. I should be able to access any parts of the Component hierarchy from Java. Complex UIs require much more than just a simple template structure. You need to be able to attach event listeners, and possibly decorate the components dynamically using Java in ways that just can’t be expressed declaratively. Hence I wanted to make it easy to “access” parts of the generated UI objects.
  3. I should be able to work with these files seamlessly inside the IDE. I didn’t want to add an extra step when dealing with these HTML UI interfaces. I’d probably forget how to do it when it came time to return to the project.
  4. No Performance Penalty. I want the UIs to be just as fast as a hand-coded UI.

And so, based on these requirements, I came up with CN1MLCodename One Markup Language. Which is basically just HTML with a couple of special attributes to help specify how the resulting Codename One UI should look.

How it works

I created a Netbeans plugin for CN1ML so that you can add CN1ML templates directly into your Codename One projects. When you save the CN1ML template, it automatically generates a corresponding Java file with the same name, but different extension. E.g. If I have a CN1ML file at com/myapp/MyForm.cn1ml, it will automatically generate a java file at com/myapp/ (which is a Java class with fully qualified class name “com.myapp.MyForm”.

You can then instantiate the form in Java my calling the com.myapp.MyForm constructor – which takes a single “Map” argument that can be used to pass parameters to the template. E.g.

    MyForm form = new MyForm(new HashMap());

    // Get the root container from the form 
    Container root = form.getRoot();

What it looks like

Here is a sample Contact Form in CN1ML

The resulting Java source code is long and ugly, but you can check it out here

And here is a screenshot of what this form looks like in an app:

Screen Shot 2014-09-24 at 5.19.05 PM

More about CN1ML

If you’re interested in this project, you can read more about it on the GitHub page.

How I Built It

I built the CN1ML parser/compiler in Mirah. This was one of my first Mirah projects since releasing the Mirah Netbeans Plugin last month. So far so good. I can safely say that Mirah is making me more productive than if I had coded this in Java. There are still some rough edges that I’m shaving off, but nothing major. And in places where Java would be a better choice, I can still write those portions in Java in the same project seamlessly.

In fact it was my experience developing the Mirah Netbeans module that gave me some of the inspiration for this CN1ML module. I looked at the problem and knew it could be achieved quite easily using the NetBeans API.


I created this screen cast to demonstrate how the CN1ML plugin works.


  1. CN1ML Netbeans Plugin Homepage
  2. CN1ML Tag and Attribute Reference
  3. Some Samples with Screenshots

Mirah for Codename One App Development


One afternoon, a few months ago, I was working on an iOS app in Codename One, and I began to wonder if there was some non-drastic way to remove some of the boiler plate from the coding process. I love Java. Its static-typing and verbosity enable me to build large, complex, fast, robust applications without losing my mind. However, these strengths can feel like weaknesses when you just want to get down to business and code up an algorithm.

I wasn’t looking to replace the whole Java eco-system – I chose most of my current development tools (e.g. Codename One) because they use Java – so I wasn’t imagining abandoning this. I still wanted to be able to use NetBeans, and Codename One, and all of my Java libraries. I just wanted to be able to occasionally skip some of the ceremony. I was imagining a sort of Javascript-like macro language with some type hints that could be automatically expanded to the full Java source by some automated preprocessor.

I was aware of all the popular JVM languages (e.g. Scala, Groovy, Kotlin, JRuby, Jython, etc..) and I do use them for some projects, but none of these are appropriate for mobile development with Codename One (which was the primary platform I wanted to target). The problem with these is that they all require runtime libraries that would have to be included in the final app. This substantially increases the app size, and, with mobile development, I need to keep the app size as small as possible. Some of these languages are statically compiled, and therefore, compile-time tools (e.g. Proguard) can be used to strip out portions of the runtime that aren’t used, but porting their runtimes into Codename One would have still been difficult, since the CN1 class library is only a small subset of the JavaSE libraries (for the purpose of keeping apps small, and maintaining compatibility with legacy devices e.g. BlackBerry and J2ME).

So, what I was looking for was a language that:

  1. Compiled to JVM bytecode.
  2. Did not add any runtime dependencies.

Mirah: The Silver Bullet

It turns out the Mirah was exactly what I was looking for. Mirah was originally developed in 2009 by Charles Nutter under the name “Duby”. This video of his presentation at Ruby Conf 2009 gives a good preview the language. It is heavily inspired by Ruby, and uses aggressive compile-time type inference to be able to remove most of the verbosity and boiler plate that is customary in a static language. I’m not going to get into the specifics of the language in this post. You can read about Mirah and its syntax on the Mirah website. I do want to mention, though, that it is awesome and that I intend to start shifting as much development to Mirah as possible going forward.

IDE Support

As it stood the day I discovered it, Mirah had potential as a language for Codename One development, but it still would not have been practical to start developing apps with it because there was no IDE support. Most/all of the Mirah devs seemed to be Ruby devs who migrated to Mirah for the performance. And Ruby devs don’t use IDEs like Java devs do.

I was not going to give up my IDE… Not for any language

If I were to switch to using a text editor, any productivity gains that I realized due to the streamlined language syntax would have been offset by the loss of IDE nicities like code completion, unit test generation, code navigation, and GUI builder integration. Even if there were a Mirah IDE or support for Mirah projects in an existing IDE, I was not willing to sacrifice all of the tools that are provided in the core Java Codename One projects.

I needed to be able to use Mirah inside my existing Java projects, interchangeably with Java.

In order to accomplish this, I decided to create a Mirah NetBeans plugin.

The Mirah NetBeans Plugin

I just released an update for the Mirah Netbeans Plugin today. It is now at a point where you can reasonably incorporate Mirah code into a Codename One application. There are lots of features, big and small, but the utility of the plugin boils down to two things:

  1. It can build Codename One applications that include .mirah source files. (It also supports other project types, but I’ll focus on CN1 here).
  2. It allows you to edit .mirah source files with all of the things you expect in an IDE (method completion, type hints, incremental compiling/error reporting).

So, if you have, this plugin installed in your NetBeans instance, you should be able to just add Mirah source files inside your existing Codename One projects. Two-way dependencies are supported. E.g. Your .java files can use classes defined in .mirah source, and vice-versa. This way you can choose to implement some parts of your App in Java, and other parts in Mirah. This is important because some parts need to be written in Java still (E.g. If you are writing a GUI builder app, the GUI Editor will be adding methods to the StateMachine class, which needs to be Java.

Download the Mirah Netbeans Plugin and start writing Mirah code in your Codename One apps today.

Proof of Concept: Poker Demo

Poker Demo Screenshot

As a proof of concept, I decided to port the Poker Demo that Shai wrote into Mirah.

You can clone the entire project and build it yourself using Netbeans with the Codename One and Mirah plugins installed.

Read more about this project along with some detailed code comparisons on the Poker Demo readme page.

The following screencast demonstrates the use of the NetBeans Mirah plugin to develop a Codename One application using Mirah.

OSCON 2014 Reflections

I’m sitting in Portland International Airport waiting for the chariot that will return me to Vancouver, so I thought I’d pass the time by reflecting on my experience at OSCON. I am not generally the kind of guy that gets the fullest experience out of a conference. I attend the talks, maybe meet a few people, and return to my hotel room to watch some Netflix. But even a social caterpillar like me has fun at these things. I thoroughly enjoyed all of the talks that I attended. I learned a lot from the tutorials, and I found the keynotes engaging.

Three talks particularly stood out to me, for various reasons:

Using D3 for Data Visualizations

The first tutorial that I attended (on Sunday), was led by Josh Marinacci on the topic of HTML5 Canvas, SVG, and D3 for data visualization. It was based on his onine book HTML Canvas Deep Dive. I found the teaching style well structured and engaging. I picked up a few tips on style that I adopted for my tutorial which I gave the following day.

It is amazing how far Javascript has come. D3 has brought data visualization to the point where every researcher (i.e. people who are producing data) should at least try to learn it. I have recommended it to my wife, who has only taken one programming course in her life and does not program on a regular basis. She will be my guinea pig to see if it’s easy enough for non-devs to pick up.

Here are the results of three exercises in the tutorial:

  1. Agricultural Productivity By State
  2. Bar Chart Using Canvas
    • A bar chart drawn with HTML5 Canvas
  3. Pie Chart
    • A Pie Chart drawn using SVG


I attended a talk by some of the OpenUI5 team. OpenUI5 is an HTML5 framework developed by SAP for cross-platform/mobile development. It provides a large number of widgets and development tools that you can use for developing a cross-platform app. And the only dependency it has is a single Javascript file.

The things that I like about it are:

  1. Light-weight. Single JS include.
  2. Really nice looking controls and layouts.
  3. Apache License
  4. Backed by a big company (so it has a better chance of survival than some of the other little promising HTML UI kits out there).

More about this talk

AsciiDoc and AsciiDoctor

I attended a talk by Dan Allen on JRuby where he demonstrated some cool aspects of the language, compared its performance with MRI (the canonical Ruby) and shows some tips on making Ruby and Java work nicely together. Dan is one of the developers behind AsciiDoc which, until OSCON, I hadn’t been aware of. Asciidoc looks like an excellent tool for developing documentation and writing books. I have experimented with lots of solutions over the past several years in this space, including (but not limited to) Doxygen, TeX, DocBook, JSDoc, PHPDocumentor, restructured text, and, more recently, Markdown.

I will definitely be giving Asciidoc a go as it appears to provide the simplicity of Markdown with the power of DocBook. The fact that it is a format that is supported by O’Reilly for their authors, lends weight to its viability for arbitrary documentation projects.


OK, there weren’t any talks on Mirah per-se, but the JRuby talk that I mentioned above reminded me of my unfinished netbeans module for Mirah. I ended up spending most of my evening hours of OSCON getting the Mirah module ready for release.

I fell in love with Mirah at first sight. It deserves a lot more attention than it is getting. Hopefully the Netbeans module will convince a Java developer or two to take a look. At the very least, it will enable me to start writing code in Mirah that I would otherwise write in Java. And nobody will be the wiser 🙂

My plans for Mirah center around Codename One. It is uniquely positioned to provide an alternate language for developing Codename One applications. I plan to use its macro ability to provide a sort of DSL specifically for removing the ceremony and boiler plate (inherent in Java) surrounding all of the common functions. I think I can improve productivity on CN1 apps by at least a factor of 2, and perhaps even more.

I’ll be posting more on that later.

Some Keynotes that You Should Watch

Andrew Sorensen : The Concert Programmer

This was really amazing to watch. This guy uses a special programming language to compose and sequence music. He codes up a pretty cool song right in front of your eyes.

Simon Wardley : Introduction to Value Chain Mapping

Simon demonstrates a really cool method to visually analyze and depict the value-chain in a company. I’m not really a management guy, but this technique looks like it could be applied to quite a few things. Watch it. You’ll learn something.

My Own Talk

Oh yeah. I led a tutorial on Codename One also. I’ll talk more about that in a separate post.

Make the World A Better Place by Making A Codename One Library

Codename One recently opened up a plugin repository on their website where you can download libraries to extend the functionality of Codename One. Right now it is really just a static webpage because the list of available modules is small. Let’s change that! I cannot think of an easier platform to develop modules for. There is a Netbeans project type that does all of the packaging work for you.

All you have to do is write your code and hit build. Then upload it to GitHub (or wherever you want to host it) and let the CN1 folks know that your module exists.

What Kinds of Modules Should I Build?

UI Components

The Codename One UI Component model is both simple and flexible. It is modelled loosely after Swing (e.g. Base “Component” class, a “Container” class which is a component that can contain other components, Label, Button, TextField, etc..) but they ditched a lot of the chaff and bloat to come up with a solution that light, simple and portable.

Creating a custom component is as simple as subclassing the Container class (or Component) and laying out some child components inside it. Once you have your custom class, you can package it up in as a cn1lib, and upload it to github. Don’t forget to write some javadocs and examples for it so people know how to use it.

I see requests in the mailing list all the time asking whether Codename One has a component that does X. The answer is often “yes”, but if the answer is no, I generally don’t hear anything else – even though the asker has likely gone off and implemented it themselves for their application. I saw a recent request for a “Color Chooser” component. Such a component would be relatively easy to create using the CN1 API. Create a dialog that gives a few slider controls to select RGB, provide some callbacks and public methods to be able to obtain the selected color, and you have a reusable color chooser component that the whole community can enjoy.

Data Processing

If you find yourself solving a problem that involves converting data from one format to another (e.g. extracting or compressing a ZIP file, MP3 Encoding, etc..) why not wrap it in a cn1lib so that others can use and improve your library.

One of the main strengths of Java was that you could almost always find a 3rd party library to do what you need. Because Java follows strict standards for name-spacing, documentation, and packaging (jar files) you could find, download, and learn how to integrate modules into your application without having to spend days looking through code to see how it works.

Having a healthy ecosystem of 3rd-party libraries is preferable to having one large monolithic core because it allows us to streamline our applications to our particular purposes and not be weighed down by features we don’t need. Many processing tools don’t belong in the CN1 core because they are too niche.

If you are developing a method to do something useful, think for a moment whether this method might be useful to someone else. You might have to make some changes to your design to decouple your library from the rest of your app – but this is a good idea anyways.

Native Functionality

Codename One is a cross-platform tool for mobile development. However it also allows you to tap into native functionality if needed by writing native interfaces (sort of like JNI, but easier to user IMO). Does your application target a platform on which you want to make use of some native libraries? Then you’ll have to write a native interface to access them. If you’re going to write a native interface anyways, why not write it in such a way that it can be reused in other projects.

The iOS, Android, and Windows Phone SDKs have tons of goodies. Usually I try to find a cross-platform solution for a requested feature, but in some cases your app will be better for making use of native APIs. If we all do our share, and publish native interfaces in cn1libs as we write them, we collectively make the Codename One ecosystem richer and more capable. And all of our apps will get better.

HTML5/Javascript Components

The big 3 platforms (iOS, Android, and Windows Phone) all support HTML5 inside the BrowserComponent in Codename One. This opens up a lot of possibilities for integrating HTML5 components into your codename one apps. There are countless Javascript/CSS libraries and components that can easily be ported to Codename One. You can even use the Codename One Javascript bridge to communicate between Java and Javascript.

A word of caution with including HTML inside your Codename One apps. HTML components are much more difficult to debug than Java components because you don’t get the nice stack trace. Generally, I find it best to debug as much HTML/Javascript as I can separately inside Chrome, then integrate it into CN1 with as few Java-Javascript dependencies as possible.

Port Existing Java Libraries

This type of library can be, arguably, the most useful for the CN1 ecosystem. You can’t just use a regular Jar with Codename One because it only supports a subset of the libraries in JavaSE. The Codename One class library includes basically the CLDC 1.1 less the javax.microedition.* classes. It also includes a number of other classes that have been added as needed (e.g. the Java Collection classes) in addition to a number of its own packages under the com.codename1.* namespace. You can check out the Codename One javadocs for a full list of supported classes.

For porting existing Java libraries to Codename One, I generally try to find a J2ME library that does what I want, since J2ME is closest to CLDC. I then go through all of the source files and look at the import sections (at the top of each source file) to see if any classes outside of the, java.lang, and java.util packages are used. If I find any dependencies outside of these packages, I take a closer look to see how easy it would be to remove the dependency. Sometimes I can find another class in the Codename One SDK that will do something similar, or I might just disable some of the functionality of the library if it isn’t needed.

After removing all of the illegal dependencies, I create a new Codename One Library project in Netbeans, and copy the library’s source files into the project. Building this project will force compliance with the Codename One libraries. If the project builds successfully, then you will have a library that is compatible with all devices on Codename One.

Performance: J2ME libraries will generally use the Thread-safe collection classes (e.g. Hashtable and Vector) instead of their faster cousins (HashMap and ArrayList). Since Codename One supports the more modern collection classes, and these perform much better, I generally go through libraries that I have ported from J2ME and change all references of Vector and Hashtable to ArrayList and HashMap respectively. I also replace StringBuffer instances to StringBuilder for the same reason.

JavaSE Libraries: JavaSE libraries can be trickier to port because they often rely on many classes that fall outside of the Codename One SDK. If they make heavy use of AWT and Swing then you might have difficulty finding Codename One equivalents to maintain the functionality. You may have to take some time to understand how the library works so that you can figure out how best to substitute out the illegal class references. The recent release of the CN1Pisces library means that you should now be able to port over most Java2D code into Codename One by changing calls from Java2D into the equivalent Pisces or Codename One Graphics calls.

A Word about the cn1lib File Format

If you are a Java developer, you might be wondering why the CN1 guys didn’t just use jars to distribute libraries. There are two reasons:

  1. Libraries may need to package both java and native code together in a standard way so that they can include native implementations. The cn1format supports this, while jar does not have a standard way of doing this.

  2. Codename One supports a slightly different API than standard Java so, for any given jar file, it is unlikely that CN1 will work with it without some modifications. Having its own format helps to ensure that all code in a cn1lib file is actually supported in Codename One. In this way it serves as a sort of compliance test.


There are only so many hours in the day to develop cool things, so I would prefer to develop components that work on as many devices as possible. Codename One has provided us with a platform for building cross-platform mobile apps that doesn’t have the same performance sacrifices as other cross-platform solutions. The foundation is strong. The user interface is built on a high-performance, light-weight stack that takes advances of hardware accelerated graphics. All code is compiled to native code so it should run just as fast as native, and sometimes even faster.

This is a foundation that we can build on. So let’s take advantage of it.

The Case For Light-Weight UI Toolkits

This post is motivated by a recent Reddit thread where someone posted an announcement about the 1.0 release of Codename One, a toolkit for building cross-platform mobile applications. I was quite surprised by the stream of negativity in the responses from developers who had never tried the framework, but who mistakenly assumed that they knew everything about it because they have tried other cross-platform toolkits in the past.

Before I discuss the thread itself, I just want to take a minute to talk about light-weight UIs and why they are important.

Light-Weight UI vs Heavy-Weight UI

When people refer to a light-weight user interface toolkit, they are generally referring to a toolkit where all of the widgets and components are drawn using graphics primitives using the toolkit itself. A heavy-weight user interface, on the other hand, is one where the components from the underlying platform are just placed in the user interface, and aren’t drawn manually. Swing, JavaFX, HTML5, QT, and Codename One are examples of light-weight UI toolkits. AWT, SWT, and Appcelerator Titanium are examples of heavy-weight UI toolkits.

Why Are Light-Weight UI Toolkits Important for Cross-Platform Development?

When you are developing for multiple platforms, then a heavy-weight UI will be one that addresses the lowest common denominator. If every platform has a “Text box” widget, then you can safely add a text box to your UI, and the correct widget will be shown on the current platform. But if one of the platforms doesn’t have a text box widget, you need to either say that “text boxes aren’t supported on platform X”, or you have to come up with an alternative for that platform.

With a light-weight UI, every platform can have a text box because you don’t depend on the underlying platform for the actual widget. This opens quite a bit of flexibility.

It is kind of like the difference between creating art work with stickers vs painting the art directly onto canvas. Imagine you are teaching an art class via a webcast and you have 5 different art students each with their own toolkit. These toolkits consist of a set of stickers and stamps that they have brought from their own collection, and a paint set. For the “heavy-weight” portion of the class, you would be instructing the students to place stickers onto the canvas. E.g. You might say “Now place a sticker of a dog in the top right corner”. But what if some of the students don’t have a sticker of a dog? Then you might say, “If you don’t have a dog, just use a cat. And if you don’t have a cat, then just leave the space blank”.

At the end of the lesson, the art work produced by each student would be radically different. The stickers would be different, might be different sizes, and some canvases might be completely blank if the student didn’t have the appropriate sticker.

The alternative “light-weight” lesson would just involve some paint brushes and paints. Imagine that students were able to replicate your painting perfectly. So if you paint a dog in the top corner, they will be able to paint an identical dog in the top corner of their canvas.

At the end of the lesson, then, every canvas will look more-or-less identical. At some point, you might actually tell the students to draw something different in a section that reflects their local culture. This would be fine also, and the variation would be reflected in the finished product.

This is basically the difference between a heavy-weight and a light-weight UI toolkit.

The mobile development space is getting very fragmented and form factors vary greatly. If any space needs a good platform for lightweight UI development, it is the mobile space.

Back to the Reddit Post

Responses were full of hate for Java, light-weight user interfaces, and the concept of cross-platform toolkits in general. One pervasive, yet misinformed, line of reasoning the came through in some of the frequent posters’ comments was as follows:

  1. Cross platform toolkits result in “lowest common denominator” applications that don’t take advantage of the features of any particular platform.

  2. Lightweight UIs won’t look or behave like a native on any platform so it is much better to use a heavyweight UI (i.e. wrap native components) so that the app at least looks and behaves natively.

  3. Lightweight UIs are slow! There are a million HTML5 solutions out there, but they are all laggy. It is better to just use a heavyweight UI.

  4. Cross-platform toolkits sound good at the start, but, inevitably you will hit a road block that will prevent you from achieving your goal, and have to resort to building native applications for each target platform, wasting, perhaps, a year or more of the time that you spent trying to use the cross-platform framework.

This line of reasoning appears to make sense if you don’t dig into some of the embedded assumptions. For example, #1 and #4 only hold true for heavy-weight toolkits, and #2 and #3 simply aren’t true. Let me address all of these points individually.

Do Cross-Platform Toolkits Result in a Lowest Common Denominator App?

If you develop a lightweight UI, then there is no reason why the resulting application should be the lowest common denominator of all platforms. This is because, in a lightweight UI, you are not dependent on the native widgets. You can embed native components in cases where it makes sense, but you are not limited by this. Any component in a lightweight UI can be used across all platforms, and configured to behave differently on each platform if it makes sense. Components can be created on top of a lightweight UI that don’t even exist in any of the underlying platforms. This adds a tremendous amount of flexibility and offers enormous potential.

Take, for example, the JFXtras project, which is built upon JavaFX, a light-weight UI framework for the desktop. It is a collection of components and widgets that are all light-weight (so they are truly cross platform) and they look and feel fantastic. If you wanted to develop this set of widgets using a heavyweight toolkit it would be 5 times the work, and would be impossible to maintain.

Are lightweight UIs doomed to look “un-native”?

While lightweight UIs give you the flexibility to create an app that doesn’t look native, you can come very close to a native look, if that is what you are trying to achieve. Light-weight UIs that are well designed enable you to develop themes that look and behave just like the native platform. The Swing has been doing this for years on the desktop and, while you may think that you can spot a Swing application a mile away, I am willing to bet that you have probably used many Swing applications without knowing it. Of course you can spot the ones that don’t look native – where the author didn’t place a priority on following native UI guidelines. But if you ran across one that did follow the guidelines, you would be none the wiser.

In my opinion, the Codename One folks have done a fantastic job of developing native looking themes for all of the main mobile platforms. I showed an app with the iOS theme to quite a number of savvy users and none of them could tell, at all, that it wasn’t actually using native widgets. All of the buttons look the same, and it behaved the same. This is a testament to the design acumen of their team.

And if you don’t like the look and feel, that is no problem. It is light-weight. You can override the look and behaviour of any component to conform to your preferences, if you like. Apply these changes across all platforms or only specific ones.

So, lightweight UIs certainly are not doomed to look un-native.

Are Lightweight UIs Slow?

Well, they can be, but so can heavyweight UIs. Performance depends on many factors, and if you have tried any of the HTML5 toolkits out there for building mobile apps you have probably noticed that these apps are indeed sluggish. So you might be tempted to apply the logic that since HTML5 apps are slow, and HTML5 is a lightweight UI toolkit, that all lightweight UI toolkits are slow. This is certainly incorrect. HTML5 requires very complex layout rules, and it relies on Javascript as its language that is quite a bit slower than a native executable would be. This is very hard for low-powered mobile devices to handle in a performant way. Ultimately as device performance improves (maybe in a couple years), the HTML5 performance problems will dissipate.

Codename One uses a different strategy that is much more similar to Swing than to HTML. It uses 2D drawing technology of the host platform to build its components (OpenGL on iOS, etc..) which is very fast and flexible. This allows for the creation of complex user interfaces without barely any performance hit.

So, no, lightweight UIs don’t have to be slow, and in Codename One’s case, it is not slow.

Are You Destined to Hit a Wall If You Use a Cross-Platform Framework?

I have been burned. You have probably been burned. I think everyone has been burned once or twice when they start a project with a toolkit, then sometime later, they hit a wall and the toolkit just can’t be used to take the next step. Is this inevitable with a Cross-Platform framework?

The answer is, maybe. But if you choose your framework carefully, they you shouldn’t have a problem. Some key items to look for would include:

  1. Is it open source? If it isn’t open source, then the chances are you will get stuck at some point and have to abandon it.

  2. Can you access native APIs if necessary? If you can’t access native APIs, then you will likely have to abandon it at some point.

  3. Is it built on a strong, robust, and fast foundation? If it isn’t, then you’ll likely have to abandon it at some point.

If the framework hits all three of these points, then you should be OK. If you need to access a new API on a particular platform, you can just write a native plugin for that. If you run into a bug or a limitation, you can fix it yourself, as long as it is open source. And as long as the core of the framework is strong and fast, you can build your own component libraries as time goes on to extend the platform, without worrying about breaking the platform.

Most HTML5/Javascript frameworks will fail on #3. HTML5 and Javascript just aren’t robust. There are many commercial cross-platform frameworks out there also. I would be careful with those.

In the few months that I have been working with Codename One, I have found the platform to be open and robust. If I find something that it doesn’t do, it is usually quite easy for me to add it myself. The fact that they allow you to write native plugins, wrap native components when necessary (to add to the UI), and develop my own libraries and components that run on top of it, give me confidence that there is no “wall” that I could hit in the future that would be a show-stopper.

Develop for Mobile or Die!

If you develop software that is designed to be used by Humans, then you are now required to develop mobile-friendly user interfaces.

In 2011, a mobile user interface was a luxury. In 2012, it was a nice add-on. In 2013, it is a requirement, or your software will be headed for the junk bin. Smart phones are now ubiquitous, and tablets are taking the place of the laptop in many contexts. People are becoming savvy to what can be accomplished with a tablet, and their expectations have been significantly raised for all software that they use.

Of course, the desktop (i.e. computers with mouse or trackpad and keyboard) is not going anywhere. It is just being reserved for those heavy-duty tasks that cannot be performed with a touch device like (and this list is shrinking every year) video editing, software development, and word processing. One class of application this can now be handled wholly via a mobile interface is the CRUD application. And if it can be created for mobile, it should be created for mobile – or your users will complain (either silently by seeking out other solutions, or loudly in email).

One trend that I noticed in 2012, was a shift of user gripes originating from users using IE to users on mobile devices. At first, my canned response was: “please use a computer, not your iPad, for using this database”. Of course, the software worked on iPad, but it wasn’t optimized for the platform so it was a little painful to use. And even under the best of conditions, users will find a way to break a UI. At first, there were some valid reasons why the app had to be used on a computer. But at this point, there are no longer any technical barriers in the way of providing a mobile interface to a (mostly) CRUD application.

Transitioning CRUD Applications to Mobile

The easiest way to transition a CRUD application to mobile, is to use an HTML library like jQuery mobile. It provides a slick UI that is very similar to native. The simple act of adding a UI in jQuery mobile that is tailored specifically for mobile users will eliminate most gripes. The larger buttons and fields, combined with a more familiar mobile workflow will make your users much more at home inside your application.

Unfortunately, the similarity to native applications will invariably lead your users to start requesting features that they have seen in other native applications. E.g.:

  • We want to be able to take videos with our phone and upload them into the database. Can we do that?
  • We want to be able to use the database without being online. Can we do that?
  • We want the database to be able to track our movement and velocity and store this in the database. Can we do that?
  • The application is kind of sluggish when loading pages and scrolling, etc…. Can you improve it?

The list of feature requests is not even limited to things people have seen before … the possibilities are endless.

While HTML5 is improving all the time, and it does technically support offline apps, and limited video access, it is still very flaky, and does not approach a native experience yet. Ultimately, when your users start asking for native-like features, you need to start looking for a way to build an application that is treated as a first-class citizen on the mobile platform of choice.

Mobile Platform of Choice??? Do I really need to Choose?

The next step after outgrowing your HTML5 mobile interface (with jQuery Mobile), is to look at your options for developing a native application. I’m using “native” in a very loose sense here. Really what I mean is an application that is installed on a mobile device in the same way as the platform’s native applications. This could be an application that is written directly using the platform’s SDK or using some other toolkit that ultimately builds an application that can be installed on the device.

If you are developing a CRUD application for an organization (like I usually am), you may or may not be able to dictate that your users use a specific device. In my case, I usually can’t… or if I try it is a world of pain dealing with people that use “the other” platform. Therefore, developing separate applications for each platform is not really an option (or good use of resources). I’m still choked at having to venture outside the web-box, much less create multiple versions of the same app.
At the minimum you’ll need to develop versions for Android and iOS (but BB and WinPhone users might get on the gripe-wagon, so watch out!!).

Phone Gap

As a web developer, naturally, the first thing I looked at was Phone Gap. It allows you to develop your application using the same web tools (HTML/Javascript/CSS) and deploy it as a “native” application. The native application is essentially just a thin wrapper around a web view component. It provides some additional libraries for working with the device’s hardware like accelerometer, GPS, video camera, etc.. Because it is just a web view wrapped in an app, you can use all of the same libraries (e.g. jQuery Mobile if you like) for developing the app. If you’re lucky you won’t have to modify the existing web app at all.

Building the applications for Phone Gap can be a little more involved, as different platforms need to be set up differently, and some even differences in the application code to make it work. However, the PhoneGap build service is available to provide building in the cloud for multiple different devices. This should ease the “pain” substantially.

Phone Gap will probably give you enough flexibility to add most features you need in a CRUD application. However, you may run into issues with performance. Javascript/HTML runs much more slowly (and noticeably so on low-powered mobile devices) than native code. Facebook’s shift away from HTML5 apps to native apps last year is a key indicator that, for mobile at least, HTML5’s time has not yet come. This performance will be most noticeable when performing scrolling operations and in some transitions, but it can rear its head anywhere.

To make matters worse, on iOS, the UIWebView component doesn’t use the same Javascript engine that is used in the Safari web browser. It is substantially slower. So, by moving your application from the Web into a PhoneGap app, you will be facing a performance penalty directly from Apple.

If you are running into performance problems, or you require native features that just aren’t offered in Phone Gap, you may need to graduate to the next level: Real Native Apps

“Real” Native Apps

First, let me define what I mean when I say “Real” native apps. I mean applications that are compiled down to native executables on the supported platform. I disqualify Phone Gap from this category (and the many other HTML5 in WebView solutions) because the actual code is running inside a web sandbox.

If you have reached this level, you should at least take the various platforms’ native toolkits for a spin so that you understand how they work. Each platform offers its own unique vision for their mobile worlds. And some concepts don’t transfer easily from one platform to another. Developing for iOS is very similar to developing for Mac OS X. You use Xcode and Interface builder to develop your application logic and user interface. Generally the entire user interface is contained inside a single Nib file, and you can use the many UIController classes to control the user interface. iOS includes many useful frameworks such as CoreData which makes it easier for you to develop CRUD apps on iOS.

Android, on the other hand, is an XML jungle. The UI is defined in XML files, and so is the application configuration. It is a much more open environment than iOS, in that it is set up to encourage applications to share its components with other applications on the system.

Blackberry and Windows Phone provide their own models, but I’m not familiar with either of these platforms.

In the course of auditing the respective SDKs you’re bound to observe the elephant in the room: All of these SDKs use different programming languages. iOS uses Objective-C, Android uses Java, Windows Phone uses C# (or C++ depending on version), and Blackberry uses C++ (at least for BB10… older versions use Java).

This makes it very difficult to share code across multiple platforms. Since I don’t have the resources to maintain separate code bases for each platform, I need to either pick a single platform and run with it, or look for a solution that will allow me to develop for all of the platforms with a single code base (remember I have disqualified Phone Gap and its HTML5 ilk already if I have reached this point).

Luckily there are options:

  1. MonoTouch provides C# bindings for pretty much the entire Cocoa Touch API (iOS). It also provides bindings for Android.

  2. J2ObjC is a tool developed by google to convert Java code to Objective-C so that it can be reused for iPhone development.

  3. Oracle ADF provides a full development toolkit that allows you to build for most mobile platforms. It uses an embedded JVM for business logic, and Phone Gap for the UI…(should we disqualify this out the gate because of Phone Gap?)

  4. Appcelerator Titanium provides a cross-platform solution that provides Javascript wrappers around native components. It is different than Phone Gap in that it doesn’t run inside a web view, it merely uses the native platform’s built-in Javascript interpreter and bindings to access native components.

5. XMLVM is a low level converter that allows you to convert code between many different languages. It provides compatibility libraries for working with Android and iOS. In my opinion, this is the most ingenious software development of the past 10 years.

  1. Codename One. Codename One allows you to write mobile applications in Java and compile them into native executables for most major platforms. It uses XMLVM under the hood for its iOS port. This is, by far, the best option right now for cross-platform native mobile development, and I’ll explain why in the following section.

If you know of other options, please let me know.

These solutions can be grouped into 3 categories:

  1. Tools that assist in porting from one platform to another, but don’t provide a full development solution. These include J2ObjC and XMLVM. While these are very interesting projects, it our aim is to be able to build a cross-platform web app, then these projects won’t get us there directly. If you are developing a tool or SDK that is designed to help you and others build cross-platform apps, then these projects may be of great interest to you.

  2. Tools that allow you to share your business logic between platforms, but ultimately require a rewrite of the user interface for each platform. MonoTouch falls into this category. Really MonoTouch is a solution for C# developers who want to develop for iOS and would prefer to use C# instead of Objective-C. It isn’t really a solution for building cross-platform mobile applications.

  3. Tools that provide a full solution for developing cross-platform mobile applications. Codename One, Oracle ADF, and Appcelerator Titanium fall into this category.

Oracle ADF

I have watched videos and read documentation for Oracle ADF, but have never actually tried to build an application with it. There are a couple of show-stoppers for me on this platform:

  1. It is commercial. I wasn’t clear on the license costs, but it makes it sound like they are hoping to make large license fees off of large enterprises.

  2. They use Phone Gap for the UI. If I’m at this point (looking for a native solution and Phone Gap won’t cut it), then, ADF doesn’t meet the requirements.

Appcelerator Titanium

Appcelerator Titanium is a clever project. I spent some time last year using the desktop version to develop some desktop applications using Javascript and CSS (the desktop version actually works more like Phone Gap than their mobile version does… it embeds a web view in a native window). Ultimately I abandoned all of my desktop Titanium projects as it was apparent that the Appcelerator people were putting all of their development resources into their mobile edition and letting the desktop version languish.

The mobile edition has some promise and apparently it has their full weight behind it. The concept of using Javascript bindings for native components is interesting, although it leaves open some of the same performance problems that plague PhoneGap. From what I have read in various forums and blogs, Appcelerator mobile apps do run into performance and memory problems if they are not developed carefully. Although they seem to be getting better with each release.

Appcelerator provides an API that generalizes commonalities between different platforms, but it enables you to write plugins that are platform specific if you need to use features of a platform that aren’t available in the API. This blog (presumably by someone who knows titanium – “titaniumninja”), argues that Appcelerator isn’t really a “Write Once Run Anywhere” tool:

Titanium isn’t a write-once-run-everywhere platform. As Appcelerator’s guys use to say, its aim is to be a write-once-adapt-everywhere tool, since, while using a common high level language and API, it enables the exploitment of platform specific features when needed. This philosophy is clearly visible in the API, as we have entire sub-namespaces dedicated to either iOS, or Android. This allows adapting our mobile applications to the platforms where they’re executed, thus avoiding a write once, suck everywhere effect. Moreover, the possibility to develop custom native extensions to the framework opens up a wide range of development scenarios, ideally allowing us to create user experiences that are practically undistinguishable from those of applications developed with native SDKs.

This description/warning seems realistic and makes me optimistic about the platform. If you are a Javascript/CSS ninja, then Appcelerator will probably provide an accelerated path to a mobile application, while not inhibiting you with a glass ceiling. I really like to be able to build native plugins for high-level frameworks. Otherwise I feel like I’m one feature request away from having to abandon the platform.

Without having dug too deeply into Appcelerator’s API, there are a couple of negatives (when compared with Codename One or native app development) that appear right off the bat:

  1. Javascript is a bitch to debug compared with managed languages like Java and C#.
  2. Memory management and performance are likely issues, and you may need to dig into the “native plugins” crutch sooner than later to resolve such issues.

If Appcelerator was the only cross-platform solution on the market, you can bet I’d be using it.

But Codename One exists…

Codename One

I have been developing with Codename One for a couple of months now. Based on that, you would probably guess that it was my choice for developing native mobile apps. You would be correct. When you line up all of the other options for development (native SDKs, Appcelerator, ADF, etc..), Codename One wins on almost every front.

What do I like about Codename One?

Codename One is the only true write-once-run anywhere solution out there (for native apps). It uses OpenGL (I believe on all platforms, but any graphics toolkit could be used if something better came along) as the foundation upon which its rich set of components are built. This makes it much easier to port to different platforms than, say Appcelerator, because all of the widgets are light weight (Similar to Swing in the Java Desktop world). The user interface can be styled using themes to look exactly like the native platform, and they provide native themes for all platforms for which they produce apps.

Applications are written in Java and they are compiled into native binaries (on iOS they use XMLVM to produce native C code that is compiled into an ARM binary using LLVM). They provide plugins for Netbeans and Eclipse, as well as a simulator to be able to run and preview your apps right in the IDE. The resource editor application also provides rich GUI development tools for forms and themes.

Basically, they have provided for the entire development cycle. They don’t leave you hanging. They even provide a cloud build server for you to build your applications without having to install the native SDKs. This allows Windows users to build iOS apps, and Mac users to build Windows Phone apps. (Initially I was concerned that I wouldn’t be able to do my own builds offline, but this was unfounded, as I was able to, without too much difficulty, set up my own build environments for iOS and Android… and I have no reason to believe it will be any more difficult for Blackberry).

The performance of CodenameOne apps is near native, and may even be faster than native apps in some case (e.g. Java method calls are 3 to 4 times faster than Objective-C message calls).

All of these features (the GUI builder, simulator, build server, Netbeans plugins, etc..) was enough to make me try it. But I stayed for the API. CodenameOne’s API is a joy to use. Their founders have a real knack for building clean UIs that are easy for developers to figure out. It appears to be heavily influenced by Swing, but with all of its demons exorcised. As an experiment I set out to write an application using the Android SDK, the iOS native SDK, and Codename One separately to get a feel for the differences in the API. By far, the Codename One API provided the most fluent experience.

In places where the API doesn’t support something, Codename One provides native interfaces that allow you to develop your own native libraries that interoperate with Codename One. This means there is no glass ceiling. Anything you can do on a native platform, you can do on Codename One.

If you are a Java developer, you really should be using Codename One to develop your mobile apps. Otherwise you are wasting precious resources and excluding potential users and platforms from enjoying your application.

If you are not a Java developer, and you want to develop mobile apps, I still think that you would be better off learning Java and jumping on the Codename One wagon than spend your time developing for another platform.

Codename One iOS Offline Build Project

To build upon my last post, I have encapsulated the steps to build an iOS application offline (i.e. without having to send to the CodenameOne build server) into a single ANT script that can easily be installed on your local system, and imported into the build.xml file of your CodenameOne application.

The CodenameOne folks have provided me with space in the CodnameOne incubator subversion repository to host this project so it will be available to everyone.


The Offline Build Tools project includes some scripts to perform the building of CodenameOne applications on any computer running Mac OS X 10.7 and Xcode 4+. The applications it produces should be equivalent to those apps produced by the build server in every way (including Native Interface support). Please let me know if you run into any cases that the build tools do not support).


Before you can use the offline build tools in your Netbeans project, you need to install the build tools project. You only need to do this once. Installation involves only two steps:

  1. Check out the offline-build-tools project from the SVN repository:
svn checkout codenameone-build-tools
  1. Run the ant install script:
$ cd codenameone-build-tools
$ ant install

This will check out the entire CodenameOne SVN repository into the “tools” subdirectory so that it can be used for building your projects. It may take some time to complete as the SVN repository is quite large.

When the installation is complete, you should notice that it created a file named “build-ios.xml” inside the codenameone-build-tools/dist directory. This contains a ready-to-use ANT target that can be imported into the build.xml files of your CodenameOne applications.

Adding the “build-for-ios-device-locally” Target to Your Netbeans Project

Now that the Offline Build Tools have been installed, you can freely add the resulting ANT target to your CodenameOne application. If you haven’t already done so, you’ll need to create a CodenameOne project in Netbeans (e.g. File > New Project, and select “Codename One” as the project type).

Under the “Files” tab in Netbeans, you should be able to see and open the “build.xml” file for your project. Just add the following <import> statement anywhere inside the <project> tags of the build.xml file:

<import file="/path/to/codenameone-build-tools/dist/build-ios.xml"/>

Now, if you right click on the build.xml file, and select “Run Target” > “Other Targets”, you will see a target named “build-for-ios-device-locally”. Select this target to build your project.

Alternatively, you can build from the command line using:

ant build-for-ios-locally

Note: If building from the command line, you may need to set your JAVA_HOME environment variable to point to your JDK’s Home directory. e.g.

export JAVA_HOME=/Library/Java/JavaVirtualMachines/1.7.0u10.jdk/Contents/Home

If you’re not using CodenameOne yet, for building mobile apps, you really need to start. It is the only solution that currently allows you to write apps for all major platforms in a performant way.


This project is meant for development purposes. I created it to allow me to be able to test and develop patches for CodenameOne without having to submit them to the CodenameOne people to be applied to the server. The current settings work directly off of the CodenameOne trunk, which is probably not ideal for production apps … it is bleeding edge.

I recommend using the CodenameOne build server for all production builds as it has been refined with (probably) some optimizations, and it makes it much easier to build on many different platforms with great ease.

Building CodenameOne iOS Apps Locally

Note: This post discusses the mechanics around building CodenameOne iOS projects locally. See my subsequent post for information about a project that automates this entire process.

I’ve been playing around with Codename One quite a bit recently, as it appears to offer enormous potential in the field of mobile development. One initial stumbling block that I had with CodenameOne was that you needed to use their build server to actually build your application. Since the code is open source, it is actually possible to build it yourself, but there were no build scripts available to automate this task, and the only instructions on how to do still required a fair bit of tinkering to get it to work.

Last month, as an exercise, I created an iOS port for CodenameOne that runs on Avian (a light-weight AOT compiler for Java), just to see if it was possible. It was indeed possible, and I was able to successfully get applications built with CodenameOne up and running using Avian on my iPhone. After some benchmarking, I found that there wasn’t a compelling performance difference between my Avian port and the XMLVM port that they are currently using on the build server. Therefore, rather than sink a lot of time into a competing port, it would be better to start working with the “official” XMLVM port for my development.

Today, as another exercise, I built an ANT target that would automate the building of a CodenameOne application for iOS on my local machine. To use it, you simply copy and paste the target into your Netbeans CodenameOne project’s build.xml, and modify some of the properties to point to the proper locations in my environment. Most of the logic is based on the build instructions that had previously posted in the CodenameOne forum.

Installation Prerequisites

You will need the following components to be in place on your system before you can use the ANT target:

After these are installed, the ANT target should work for any application you try to build.

Step 1: Checking out the CodenameOne repository

You simply need to open Terminal and check out the codename one repository. The following example creates a directory called “src” inside your home directory, and checks out codenameone in a directory named codenameone-read-only inside this src directory.

$ cd ~
$ mkdir src
$ cd src
$ svn checkout codenameone-read-only

At this point, the CodenameOne repository trunk will be located at ~/src/codenameone-read-only.

Step 2: Install XMLVM

The iOS Port project of the CodenameOne repository includes a copy of XMLVM that you can install if you don’t have it installed yet. It is located at:


You can find installation instructions for XMLVM at

Update Dec. 14/2012: Currently you need to use the xmlvm distribution that is included inside the iOSPort directory. Installation instructions are still the same:
$ cd /path/to/codenameone-read-only/Ports/iOSPort/xmlvm
$ sudo ant
$ sudo ant install

The above instructions would install xmlvm at /usr/local/bin/xmlvm

Once you have XMLVM installed, you should be able to use the ANT target in your own projects.

Step 3: Add Build Scripts to iOSPort

The ANT target depends on a Python script to be able to add files to Xcode projects from the command line. You will need to download this buildscripts directory, and copy it into the codenameone-read-only/Ports/iOSPort directory (i.e. the final location would be


You can download these build scripts here

You also need to add a template for the Main application entry point into the iOSPort directory. Create a file at codenameone-read-only/Ports/iOSPort/ with the following contents:

Adding the Ant Target to Your Project

  1. Create a CodenameOne application project in NetBeans (if you haven’t already).
  2. Open the build.xml file for your project. (e.g. you can click on the “Files” tab, then expand the tree node for your project, and double click the “build.xml” file.
  3. Paste the following snippet into the build.xml file. It can appear anywhere inside the <project>…</project> tags.
  4. Modify the codename1.repo.path property to point to the codenameone-read-only directory (i.e. where you checked out the CodenameOne repository to).
  5. Modify the xmlvm.path property to point to the XMLVM binary on your system.
  6. Modify the ant.path property to point to the ANT binary on your system.
  7. Modify the python.path property to point to the python binary on your system.

Building your Project in NetBeans

Once you have successfully added the the ANT target to your build.xml file, you should be able to build the project.

  1. Click on the “Files” tab.
  2. Right click on the “build.xml” file in your project, and select “Run Target” > “Other Targets” > “build-for-ios-device-locally”
  3. Wait. It should open Xcode with your project when it is finished building.
  4. You should be able to just run or build your project in Xcode like it is a normal iOS project. It will take some time (usually about 5 minutes per build), because XMLVM produces a couple thousand Objective-C files and includes them in the Xcode project. (Don’t worry, LLVM will strip out all unused code so that the resulting binary isn’t too big).

*Note: It doesn’t seem to like building for the simulator. You can only build for an iOS device currently. I believe this is because it includes a library, zbar, that is only compiled for arm devices (not the i386 emulator).

iOS Signing Identity & Provisioning Profile

It is worth noting that you will need to set up Xcode to use your iPhone Developer identity, or it will stop you in your tracks. You will also have to set up a provisioning profile if you are doing development builds. This was a real pain in the ** to get right (in fact it was probably harder than writing the ANT script), but there is lots of documentation on this on both the CodenameOne site and the Apple site (and all around Google too).

You’ll need to make sure that your App ID (set in Project Properties in NetBeans) will need to begin with your the unique code that your provisioning profile is set up with.

Current Limitations : Native Interfaces

This build script doesn’t currently build native interfaces that you may have developed as part of your application. Native Interfaces need to have some special glue generated at build time for them to work, and the code and specs for this glue have not been released. If you are using native interfaces, you’ll need to use the CodenameOne build server in order to access them.

I am working on replicating that glue so that Native interfaces will work in local builds, and will post it when complete. An inability to develop native interfaces locally is a major impediment to being able to contribute to the CodenameOne project. It is critical that *all* build functions can be performed locally or I fear that it will be difficult for a community to form around this wonderful project.

More Thoughts on Avian vs XMLVM for iOS

I’ve only been using CodenameOne for a couple of weeks now, and I’ve been experimenting with both Avian and XMLVM on iOS. As I mentioned above, the fact that XMLVM actually outperforms Avian on many benchmarks means that I may not pursue the Avian port much further. However there are a few aspects of using Avian that have come to my attention in the short time that I’ve been playing with CodenameOne:

  1. Debugging and Stack Traces are better on Avian. XMLVM currently isn’t a whole lot of help if you run across an exception. It states that stack traces are currently unavailable and simply prints the error message. Avian, on the other hand, will give you a full stack trace, which makes it easy to debug problems.
  2. A full Java runtime environment. In XMLVM there are a few things that don’t work the way you expect if you’re used to the Java runtime environment. E.g. I was trying to print debugging information to the console using the familiar System.out.println() only to find out that this doesn’t seem to output anything in XMLVM. (Not sure if there’s anything special I need to do to get this working). Also, things like loading resources from Jar files using Class.getResource() and Class.getResourceAsStream() don’t work on XMLVM. You need to use equivalents from the CodenameOne API which are thin wrappers over native methods that do the same thing.
  3. Well that’s all I have come up with so far..

Building Locally vs Sending to the CodenameOne build server

It is important for me to be able to build my CodenameOne projects locally because I want to start contributing to the project and I need to be able to test my changes to the CodenameOne core without sending them into Shai to add to the build server. However, for production releases, I still recommend using the build server. They have taken the time to sort of all of the kinks and add many optimizations that I just don’t have time to work out. Their build server is also a bit faster than building locally.

Avian vs XMLVM: AOT Java on iPhone Benchmarks

In my last post, I discussed the results of a benchmark comparison between XVMLVM and Avian both solving the Towers of Hanoi problem on an iPhone 4s. Originally it looked like XMLVM ran slightly faster, solving the problem in 35 seconds (vs 42 seconds for the Avian version).

The code that I used for the benchmark are as follows:

Codename One controller contains the actual benchmark timing code:

However, today I decided to try writing the same code directly in C using CodenameOne’s native interfaces. This way I would have a baseline with which to compare the performance – so that we know just how much performance we are giving up by using Java instead of C to write an iPhone App.

The native code for this benchmark is as follows:

And it was used in a CodenameOne controller to actually perform the benchmark timing as follows:

I was initially frustrated to find that the C version of my benchmark ran in 0 milliseconds (compared to about 35,000 ms for my Java version compiled with XMLVM/GCC and 42,000ms for my Java version compiled with Avian). Something had to be wrong. I checked to make sure that it was actually calling my function. It was indeed running the function. I tried increasing n to ridiculously large values (3000000), but it still ran in 0ms.

As it turns out the GCC/LLVM compiler was outsmarting my benchmark. Because the benchmark function didn’t return any values to to the caller, and didn’t affect any state outside of its local variables, it decided that the entire function could be replaced with No Op. This is sort of like a compiler’s version of “if a tree falls in the woods and nobody sees it…”. As far as GCC is concerned, the tree didn’t fall.

To solve this problem, I added a static variable that is incremented each time the function is called. This way the compiler wouldn’t be able to eliminate the code as dead. The revised C code looks like:

After modifying the benchmark to update a static variable (so that the compiler could no longer cheat), I was able to finally get a benchmark result. However, this discovery cast a shadow over my previous benchmark results, so I decided to modify the Java version to update a static variable (so that no cheating could take place).

The modified Java version looks like:

This time around, I found that Avian was marginally faster than XMLVM (about 15% faster).

The results of the revised benchmark are as follows:

Hand-coded C version (GCC/LLVM) 31.7 seconds
XMLVM version 65.8 seconds
Avian version 57.1 seconds

Changing to Use Object Methods Instead of Static Method Calls

After posting the above results in the XMLVM forum, Arno (the creator of XMLVM) suggested I try changing the TowerOfHanoi.move() method to not be static. I made the change as follows:

And the the actual benchmark timing code changed to:

Clearly, Arno had some insider knowledge about how the method dispatching works because this produced wildly different results for both XMLVM and Avian:

XMLVM version 40.2 seconds
Avian version 77.4 seconds

So XMLVM, in this test, narrows the gap between native C function calls, and its own method dispatching performance. (Less than 33% difference, which is negligible in the scheme of things). Avian clearly doesn’t handle object methods as quickly as it does static methods, and this really brings to a forefront Joel Dice’s comment that little benchmarks like this don’t really mean much. Applications do much more than perform recursive functions with simple integer arithmetic. The true performance of an application comes down to many factors including graphics, networking, memory allocation, floating point calculations, etc…

These experiments, for me, at least reaffirm that Java is a viable platform for developing for mobile. It should *not* suffer from the same performance problems that current HTML5 solutions do.

A Victory Lap for Java

The benchmarks above make it look like Java is at a disadvantage when compared to purely native apps written in Objective-C (even if in some tests XMLVM appears to have almost caught up). But these benchmarks are comparing to C function calls, which are very fast. What if we change the benchmark to use Objective-C messages. This, is not really fair, since it is well-known that Objective-C message passing is much slower than typical function and method dispatching. Nonetheless, let’s make try, if for no other reason than to know just *how* slow it is.

I changed the Native code as follows, so that it is using message calls for all recursive calls.

Not surprisingly, this benchmark ran much more slowly than the previous version:

Objective-C Message Calls 154.5 seconds

Thoughts in Summary

AOT-compiled Java (either by Avian or via XMLVM) produces performance that is comparable to native C code. It may actually perform better, but these benchmarks are very narrow in scope. The relative performance of XMLVM and Avian seem to vary widely depending on which operations are being performed. XMLVM seems to handle object methods very well, whereas Avian seemed to have slightly quicker dispatching of static methods.

In any case, I don’t have any reservations about the performance of CodenameOne in relation to native apps. Whether it uses XMLVM, Avian, or some other solution for deploying Java to iOS, it should be able to provide sufficient performance for any sort of application.

See Also

  1. CodenameOne + Avian = Java on iOS – My blog post discussing my experiment to create an Avian port for CodenameOne to run on iOS
  2. XMLVM is Actually Pretty Fast – My blog post discussing my initial benchmark results comparing Avian to XMLVM
  3. Codename One Avian Project on Github