Codename One is a set of tools for mobile application development that derive a great deal of its architecture from Java. It stands both as the name of the startup that created the set of tools and as a prefix to the distinct tools that make up the Codename One product.

The goal of the Codename One project is to take the complex and fragmented task of mobile device programming and unify it under a single set of tools, APIs and services to create a more manageable approach to mobile application development without sacrificing development power/control.

How Does Codename One Work?

Codename One is a unification of several different pieces:

  • API - The API allows us to abstract the differences between the various devices.

  • Plugin - The plugin is the only piece of software installed on client machines, it includes the following features:

    • IDE integration - provides preferences, completion and the ability to send a native build

    • Simulator - A native device simulator that runs locally and allows debugging the application

    • Designer - visual design tool/GUI builder, theme creator etc.

  • Build Servers - The build servers accept native device builds sent by the plugin and convert the binaries (JAR’s not sources) to native applications as explained below.

  • Cloud Servers - The cloud servers provide features such as push notification, storage, cloud logging etc.

Codename One tool-chain

Why Build Servers?

The build servers allow building native iOS Apps without a Mac and native Windows Phone apps without a Windows machine. They remove the need to install/update complex toolchains and simplify the process of building a native app to a right click. Since building native iOS applications requires a Mac OS X machine with a recent version of xcode Codename One maintains such machines in the cloud and when developers send an iOS build such a Mac will be used to generate a completely native app!

The same is true for most other platforms. For the Android, J2ME & Blackberry the standard Java code is executed as is. Java 5 syntax is translated seamlessly to the JDK 1.3 cldc subset on J2ME/Blackberry to provide those language capabilities and API’s across all devices. This is done using a server based bytecode processor based on retroweaver and a great deal of of custom code.

On iOS Codename One is using a VM that translates Java to C code and boasts a non-blocking GC as well as 64 bit support. This VM is open source in the Codename One git repository. In the past Codename One used XMLVM to generate native code in a very similar way but the XMLVM solution was too generic for the needs of Codename One.

On Windows Phone a C# translator is used currently it too relies on XMLVM. Notice that the XMLVM backend that translates to C# is very different from the one that translates to iOS.

What makes Codename One stand out is the approach it takes to UI where it uses a "lightweight architecture" to allow the UI to work seamlessly across all platforms and be developed almost entirely in Java. It is augmented by the ability to embed "heavyweight" widgets into place among the "lightweights". You can learn more about this in this blog post.

A lightweight component is written entirely in Java, this allows developers to preview the application accurately in the simulators & GUI builder.

Codename One achieves fast performance by drawing using the native gaming API’s of most platforms e.g. OpenGL ES on iOS.

Versions In Codename One

One of the confusing things about Codename One is the versions. Since Codename One is a SaaS product versioning isn’t as simple as a 2.x or 3.x moniker but we do make releases with such numbers that contribute to the general confusion.

When a version of Codename One is released the version number refers to the libraries at the time of the release which are then frozen and are made available to developers who use the Versioned Builds feature. The plugin which includes the designer as well as all development that is unrelated to versioned builds continues immediately after release and updates dynamically with updates to the build servers. The secondary utility of having a "release" of a Codename One version is for the stability it implies thru the code freeze.


LWUIT App Screenshot

Codename One was started by Chen Fishbein & Shai Almog who authored the Open Source LWUIT project at Sun Microsystems starting at 2007. The LWUIT project aimed at solving the fragmentation within J2ME/Blackberry devices by targeting a higher standard of user interface than the common baseline at the time. LWUIT received critical acclaim and traction within multiple industries but was limited by the declining feature phone market. In 2012 the Codename One project has taken many of the basic concepts developed within the LWUIT project and adapted them to the smartphone world which is experiencing similar issues to the device fragmentation of the old J2ME phones.

Limitations & Capabilities

J2ME & Blackberry are very limited platforms to achieve partial Java 5 compatibility Codename One automatically strips the Java 5 language requirements from bytecode and injects its own implementation of Java 5 classes. Not everything is supported so consult the Codename One JavaDoc when you get a compiler error to see what is available. Due to the implementation of the NetBeans IDE it is very difficult to properly replace and annotate the supported Java API’s so the completion and error marking might not represent correctly what is actually working and implemented on the devices. However, the compilation phase will not succeed if you used classes that are unsupported.

Lightweight UI

The biggest differentiation for Codename One is the lightweight architecture which allows for a great deal of the capabilities within Codename One. A Lightweight component is a component that is written entirely in Java, it draws its own interface and handles its own events/states. This has huge portability advantages since the same code executes on all platforms, but it carries many additional advantages.

The components are infinitely customizable just by using standard inheritance and overriding paint/event handling. Theming and the GUI builder allow for live preview and accurate reproduction across platforms since the same code executes everywhere.


Installing Codename One In NetBeans

For the purpose of this document we will focus mostly on the NetBeans IDE for development, however most operations are almost identical in the Eclipse IDE as well. For instructions specific for Eclipse please go to the following section.

These instructions assume you have downloaded NetBeans 7.x, installed and launchedit.

Select the Tools→Plugins menu option & select the Available Plugins Tab then Check The CodenameOne Plugin

Netbeans Plugin Install Wizard

After that click the install button below. Follow the Wizard instructions to install the plugin

Netbeans Plugin Install Wizard step 2

You will be informed that the plugin is unsigned which is indeed true, you just continue anyway.

Installing Codename One In Eclipse

Startup Eclipse and click Help→`Install New Software`. You should get this dialog

Eclipse Install New Software

Click the Add button on the right side & fill out the entries

Eclipse Add Repository Dialog

Enter Codename One for the name and for the location.

Select the entries & follow the wizard to install

Eclipse Install Wizard select entries

Installing Codename One In IntelliJ IDEA

Download & install IntelliJ/IDEA, notice that Android Studio will not work.

Install the plugin using The Plugin Center

Use the search functionality in the plugin center to find and install the Codename One plugin.

GUI Builder Hello World

Start by creating a new project in the IDE and selecting the Codename One project.

New Project
New Project Dialog
Use a proper package name for the project!
Netbeans Setting the Package Name

It is important to use proper package names for the project since platforms such as iOS & Android rely on these names for future updates. They are thus painful to change! The convention is the common Java convention of reverse domain names (e.g. com.codenameone for the owner of etc.).

By default a GUI builder project is created, we will maintain this default for the purpose of this hello world.

Default project structure

Since this is a GUI builder project you can open the Codename One Designer with the content of the theme.res file by double clicking the file.

If you choose to rename this file in the future it is important to update the resource file name in the project properties settings.
GUI Builder Hello World

Within the Codename One Designer we can see several categories the most interesting of which are theme & GUI. We will start by opening the theme section and clicking the entry there. The default Codename One theme, derives from the platform native theme. We can easily change the "base theme" in the preview to see how the theme will act in different devices by clicking the native theme option in the application menu as such.

Native Themes Menu

To edit the UI for the application we need to select the GUI section and click “GUI 1” within that section. We are then faced with a drag and drop interface to manipulate the GUI of the application we saw within the theme preview. All changes made here are reflected instantly to the theme preview.

Binding Events

The GUI builder allows us to bind events, we will drag a new button into the GUI and use this functionality to select the button from the GUI and then add an action event to a button listener to a button..

ActionListener generated

Clicking the "action event" button creates a new method within the IDE which we can can use to bind functionality to the button. Within the code we show a dialog by adding the code:"Hello", "Hi There", "OK", null);

Show Dialog

If we inspect the Codename One project to some degree we will notice that it is pretty close to a standard Java project hence it can be modified/used in very similar ways. You can use the debugger and most refactoring functionality as usual.

You should not change the classpath settings for the project since library support is a more complex issue than just modifying the classpath! Furthermore, if you change package/class names for some of the core classes you will need to update the project settings accordingly.
Update project settings

In order to get a native application for the devices you need to send a build to the build server. Before you get started you will probably need to read the signing section of this guide in order to produce an actual working application. Right click the project and select the device type for which you wish to build. If you haven’t registered in the build server just visit and signup for free to get an account there!

Send Build to Build Server

Within the build server at you can follow the status of your current build.

Build Server QR Code

In the build server we can follow the progress of the build and the results for the current build. We can email a link to the deployment files, download them or use a QR reader to install them to the phone. The Codename One LIVE! application allows following the status and installing applications directly from the build server.

Manual Hello World

Some developers prefer writing all their code and avoiding the GUI builder like a plague, for them this tutorial covers the creation of a hello world application without the GUI builder.

Start by creating a new project in the IDE and selecting the Codename One project.

New Project
New Project Dialog
Use a proper package name for the project!
Netbeans Setting the Package Name

It is important to use proper package names for the project since platforms such as iOS & Android rely on these names for future updates. They are thus painful to change! The convention is the common Java convention of reverse domain names (e.g. com.codenameone for the owner of etc.).

Make sure to select the Hello World project and NOT the GUI Builder project!

Within your project main class you will see a start method that contains the code:

Form f = new Form("Hello World");

to add a button to the form that will show a dialog add the following:

   Button d = new Button(“Show Dialog”);
    d.addActionListener(new ActionListener() {
        public void ActionPerformed(ActionEvent ev) {
  "Hello", "Hi There", "OK", null);

This will show a dialog when the user clicks the button. You can use the play button in the IDE to run the application.