J2ME Polish
J2ME Polish 2.4 Documentation
Enough Software

Developing for Android Devices

         Commands rendered by Android.

The Android platform is an operating system and application environment for mobile devices developed by Google. J2ME Polish will convert your MIDlet applications to this platform without further work on your site.


To create and deploy an application for Android you need the Android SDK with a version of 1.0 or higher. Please visit the Android Developer Site to download the SDK for your operation system and install it.

Optionally, you can install the Android ADT Plugins for eclipse. For further information how to install the plugins, go to the Android Installation Guide.

After the installation of the Android SDK you should define the android.home property in either ${polish.home}/global.properties, ${project.home}/${user.name}.properties or in your build.xml script. In your build.xml script the definition could look like this:

	location="C:/Program Files/android-sdk" 

Building Android Apps

J2ME Polish ports your application to Android automatically. All you need to do is to target an Android device (using the <deviceRequirements> section).

Java 1.5 Syntax

The Android platform is based on Java 1.5 and your application can use the full range of features of this Java version like generics.

Android Target Devices

To compile, convert and package your source code for the Android platform, you build your application for the device Generic/android. To depend on a specific SDK version use Generic/android2.3 for Android 2.3 phones and Generic/android4.0 for Android 4.0 tablets or phones. You can also target a specific phone like Motorola/Photon.
Here are some useful generic target devices that are plain-vanilla Android devices:

DeviceAndroid Version
Android API Level
Display ResolutionAdditional APIs
Generic/android4.0.3_WXGA8004.0.315WXGA: 1280x800-
Generic/android4.0.3_WXGA7204.0.315WXGA: 1280x720-
Generic/android4.0.3_WSVGA4.0.315WSVGA: 1024x600-
Generic/android4.0.3_WVGA8004.0.315WVGA800: 480x800-
Generic/android4.0.3_WVGA8544.0.315WVGA854: 480x854-
Generic/android4.0.3_WQVGA4324.0.315WQVGA432: 240x432-
Generic/android4.0.3_WQVGA4004.0.315WQVGA400: 240x400-
Generic/android4.0.3_QVGA4.0.315QVGA: 240x320-
Generic/android4.0.3_HVGA4.0.315HVGA: 320x480-
Generic/android4.0_WXGA8004.014WXGA: 1280x800-
Generic/android4.0_WXGA7204.014WXGA: 1280x720-
Generic/android4.0_WSVGA4.014WSVGA: 1024x600-
Generic/android4.0_WVGA8004.014WVGA800: 480x800-
Generic/android4.0_WVGA8544.014WVGA854: 480x854-
Generic/android4.0_WQVGA4324.014WQVGA432: 240x432-
Generic/android4.0_WQVGA4004.014WQVGA400: 240x400-
Generic/android4.0_QVGA4.014QVGA: 240x320-
Generic/android4.0_HVGA4.014HVGA: 320x480-
Generic/android3.2_WXGA3.213WXGA: 1280x800-
Generic/android3.1_WXGA3.112WXGA: 1280x800-
Generic/android3.0_WXGA3.011WXGA: 1280x800-
Generic/android2.3.3_WVGA8002.3.310WVGA800: 480x800-
Generic/android2.3.3_WVGA8542.3.310WVGA854: 480x854-
Generic/android2.3.3_WQVGA4322.3.310WQVGA432: 240x432-
Generic/android2.3.3_WQVGA4002.3.310WQVGA400: 240x400-
Generic/android2.3.3_QVGA2.3.310QVGA: 240x320-
Generic/android2.3.3_HVGA2.3.310HVGA: 320x480-
Generic/android2.3_WVGA8002.39WVGA800: 480x800-
Generic/android2.3_WVGA8542.39WVGA854: 480x854-
Generic/android2.3_WQVGA4322.39WQVGA432: 240x432-
Generic/android2.3_WQVGA4002.39WQVGA400: 240x400-
Generic/android2.3_QVGA2.39QVGA: 240x320-
Generic/android2.3_HVGA2.39HVGA: 320x480-
Generic/android2.2_WVGA8002.28WVGA800: 480x800-
Generic/android2.2_WVGA8542.28WVGA854: 480x854-
Generic/android2.2_WQVGA4322.28WQVGA432: 240x432-
Generic/android2.2_WQVGA4002.28WQVGA400: 240x400-
Generic/android2.2_QVGA2.28QVGA: 240x320-
Generic/android2.2_HVGA2.28HVGA: 320x480-
Generic/android2.1_WVGA8002.17WVGA800: 480x800-
Generic/android2.1_WVGA8542.17WVGA854: 480x854-
Generic/android2.1_WQVGA4322.17WQVGA432: 240x432-
Generic/android2.1_WQVGA4002.17WQVGA400: 240x400-
Generic/android2.1_QVGA2.17QVGA: 240x320-
Generic/android2.1_HVGA2.17HVGA: 320x480-
Generic/android2.0.1_WVGA8002.0.16WVGA800: 480x800-
Generic/android2.0.1_WVGA8542.0.16WVGA854: 480x854-
Generic/android2.0.1_WQVGA4322.0.16WQVGA432: 240x432-
Generic/android2.0.1_WQVGA4002.0.16WQVGA400: 240x400-
Generic/android2.0.1_QVGA2.0.16QVGA: 240x320-
Generic/android2.0.1_HVGA2.0.16HVGA: 320x480-
Generic/android2.0_WVGA8002.05WVGA800: 480x800-
Generic/android2.0_WVGA8542.05WVGA854: 480x854-
Generic/android2.0_WQVGA4322.05WQVGA432: 240x432-
Generic/android2.0_WQVGA4002.05WQVGA400: 240x400-
Generic/android2.0_QVGA2.05QVGA: 240x320-
Generic/android2.0_HVGA2.05HVGA: 320x480-
Generic/android1.6_WVGA8001.64WVGA800: 480x800-
Generic/android1.6_WVGA8541.64WVGA854: 480x854-
Generic/android1.6_QVGA1.64QVGA: 240x320-
Generic/android1.6_HVGA1.64HVGA: 320x480-
Generic/android1.5_WVGA8001.53WVGA800: 480x800-
Generic/android1.5_WVGA8541.53WVGA854: 480x854-
Generic/android1.5_QVGA1.53QVGA: 240x320-
Generic/android1.5_HVGA1.53HVGA: 320x480-

Many Android devices contain a set of additional Google APIs:. You will find corresponding JAR files in ${polish.home}/import, for example ${polish.home}/import/android-google-maps10.jar.

DeviceAndroid VersionAndroid API LevelDisplay ResolutionAdditional APIs
Google/android4.04.014-android-google-maps-api14, android-google-usb-api14
Google/android3.23.213-android-google-maps-api13, android-google-usb-api13
Google/android3.13.112-android-google-maps-api12, android-google-usb-api12
Google/android2., android-google-usb-api10

Manufacturer devices may also contain vendor specific APIs, e.g.:

DeviceAndroid VersionAndroid API LevelDisplay ResolutionAdditional APIs
Sony-Ericsson/AndroidXperia2.3.310(various)android-google-maps-api10, android-google-usb-api10, android-sony-ericsson-eventstream-api10, android-sony-ericsson-infinite-api10
Sony-Ericsson/AndroidXperia_WVGA2.3.310480x854android-google-maps-api10, android-google-usb-api10, android-sony-ericsson-eventstream-api10, android-sony-ericsson-infinite-api10
Sony-Ericsson/AndroidXperia_HVGA2.3.310320x480android-google-maps-api10, android-google-usb-api10, android-sony-ericsson-eventstream-api10, android-sony-ericsson-infinite-api10
Motorola/Photon2.3.310540x960android-motorola-storage-api10, android-motorola-hdmi-api10, android-motorola-edm-api10
Motorola/DroidX22.3.310480x854android-motorola-hdmi-api10, android-motorola-edm-api10
Motorola/Titanium2.17320x480android-motorola-iexchange-api7, android-motorola-provider-api7

Manually Selecting an Emulator Target and Skin

The J2ME Polish Android devices have an associated emulator target and skin, but you can override both values. To find out available skins you should call the ${android.home}/tools/android tool on the command line, e.g. on a Mac:

/Applications/android-sdk-mac_x86/tools/android list targets

This will give you a list of targets and their respective skins like this:

Available Android targets:
id: 1 or "android-3"
     Name: Android 1.5
     Type: Platform
     API level: 3
     Revision: 4
     Skins: HVGA (default), HVGA-L, HVGA-P, QVGA-L, QVGA-P
id: 2 or "android-4"
     Name: Android 1.6
     Type: Platform
     API level: 4
     Revision: 3
     Skins: HVGA, QVGA, WVGA800 (default), WVGA854
id: 3 or "android-7"
     Name: Android 2.1-update1
     Type: Platform
     API level: 7
     Revision: 3
     Skins: HVGA, QVGA, WQVGA400, WQVGA432, WVGA800 (default), WVGA854
id: 4 or "Motorola Mobility, Inc.:Motorola Titanium APIs:7"
     Name: Motorola Titanium APIs
     Type: Add-On
     Vendor: Motorola Mobility, Inc.
     Revision: 1
     Description: Motorola Titanium Device.
     Based on Android 2.1-update1 (API level 7)
      * motorola.provider (motorola.provider.jar)
          APIs for Motorola iDEN contacts provider
      * com.motorola.android.ptx (iexchangelib.jar)
          APIs for Motorola iExchange service
     Skins: WVGA854, WQVGA400, HVGA, TITANIUM (default), WQVGA432, WVGA800, QVGA

You can set the emulator skin by specifying the polish.Emulator.Skin variable either as an Ant property or in the <variables> section of your build.xml script, e.g. on the command line:

ant emulator -Dpolish.Emulator.Skin=WVGA800 -Ddevice=Generic/android2.1

You can override the target emulator with the polish.build.Android.Platform.Target variable, e.g.:

ant emulator -Dpolish.Emulator.Skin=WVGA800 -Dpolish.build.Android.Platform.Target="Motorola Mobility, Inc.:Motorola Titanium APIs:7" -Ddevice=Generic/android2.1

Testing Android Apps

The building of the application is done and a complete project will be generated within the temporary build folder, e.g. ${project.home}/build/Generic/android2.3/en/activity. This can be useful for debugging purposes.

There are two possibilities to test Android applications which are build with J2ME Polish:

  • If the Ant property test is set to true or if you call the emulator target, the Android emulator is started automatically and the application is installed. Before launching your application, please wait for the build.xml to output Successfully installed. To rebuild the application and test it, just cancel the running build.xml and leave the emulator running, the build process will automatically detect if there's an emulator running and install the application to the running emulator. If you application is running at deployment time, it will be shut down beforehand. You can also start the emulator before the build process is started. The launch parameters are printed during the build process.
  • The created activity in the build folder can be imported to Eclipse and used to test via the Android ADT Plugins if they're installed. Please note that you need to fix the project to use it with the ADT plugins. To do so, right-click the imported activity and run Android Tools / Fix Project Properties.

To view output send to System.out or System.err you can either use the Eclipse plugin or start the Android tool ddms, which you can find in ${android.home}/tools.

Configure your AndroidManifest.xml

You can customize the generated AndroidManifest.xml file by defining variables in the build.xml file.

		<variable name="android.targetSdkVersion" value="4" />

Alternatively you can specify the path to an existing AndroidManifest.xml file. In that case the element of the specified manifest will be added to the generated manifest:

		<variable name="android.manifest" value="configuration/AndroidManifestStub.xml" />
<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android">
    <supports-screens android:resizeable="true"

In the above example we support small, normal, large and extra large screens. Note that this is done by default with the additional setting that all screen densities are also supported.

If you are using an Android service in your application, you need to define within the <application> element:

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android">

Note that the <application> element is automatically populated by J2ME Polish, so you do not need to enter your details there. This is the same for any elements that are auto-populated; in that case the existing elements will not be replaced but only complimented by your changes.
An element attribute, however, will overwrite an existing attribute of an existing element. The following code sets the label of the application to a custom Android one, for example:

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android">
	<application android:label="Custom Android Name" >
Variable Description
android.minSdkVersion See http://developer.android.com/guide/topics/manifest/uses-sdk-element.html#min for details.
android.targetSdkVersion See http://developer.android.com/guide/topics/manifest/uses-sdk-element.html#target for details.
android.maxSdkVersion See http://developer.android.com/guide/topics/manifest/uses-sdk-element.html#max for details.
android.versionCode See http://developer.android.com/guide/topics/manifest/manifest-element.html#vcode for details.
android.versionName See http://developer.android.com/guide/topics/manifest/manifest-element.html#vname for details.
android.skipSupportsScreens If android.skipSupportsScreens is set to true, J2ME Polish will not generate a corresponding supports-screens section in the AndroidManifest.xml. This will result in your app being automatically scaled for higher density screens.
MIDlet-Icon This variable is the path to an icon.
android.hideStatusBar Set this variable to the value true to hide the status bar at the top of the screen.
android.manifest Path to a manifest file - all elements in that file will be added to the generated manifest.

Sign your Application

Every Android application needs to be signed. The build process will automatically sign your application with a development signature which is accepted by a device or an emulator. To sign your application with your own signature you can use the signing mechanism provided by J2ME Polish. Please see the sign tag for details.

Tip: Changing the signature of an application will not change its identity. If you try to install an already installed application with the same id but a different signature, the system will assume fraud and will not allow the operation. So in order to change the development signature to a real one you need to deinstall the old application first. This also implies that you should not deploy an application with a development signature to your customers. The customer would be forced to deinstall the application by hand in case you want to update the application.

Publish your Application on Android Market

The Android Market is the One-Stop-Shop for applications on any Android handset. A published application can be downloaded by every Android user and you need not provide hosting and delivery methods.

To publish your application you need an Android Market account. Please see the official Android Market site for details.

Configure Commands and Alerts

You can and should configure so that it uses native commands and alerts for your android ports. This improves the native integration of your app considerably.

Configure Commands

The rendering of commands can be done by J2ME Polish or by the Android system. A command rendered by J2ME Polish will be stylable by you where a system rendered command will look natively.

This is being configured with the fullscreen mode of J2ME Polish - set it to false for using native Android commands and to menu for using J2ME Polish rendered commands.

<variable name="polish.FullScreen" value="false" if="polish.android || polish.blackberry" />


<variable name="polish.FullScreen" value="menu" unless="polish.android || polish.blackberry" />

This setting needs to be applied to the <variables> section of the <j2mepolish> task in your build.xml script.
Here you can see the difference in the rendering behavior in the J2ME Polish rssbrowser sample application:

Commands rendered by J2ME Polish.
Commands rendered by J2ME Polish.
Commands rendered by Android.
Native Android commands (=recommended).

When using native commands, you cannot design colors or the general design of the commands, but like in normal J2ME Polish commands you can specify command images with icon-image CSS attribute:

In your Java code use a #style preprocessing directive to bind a style to a specific command:

//#style commandNext
Command cmdNext = new Command( "Next", Command.SCREEN, 2 );

Then define this style in your polish.css file accordingly:

.commandNext {
	icon-image: url( cmd_next.png ); 

Configure Alerts

Use the polish.useNativeAlerts preprocessing variable for enabling native alerts:

<variable name="polish.useNativeAlerts" value="true" if="polish.android || polish.blackberry" />

Native Android Alert

Configure Permissions

J2ME Polish adds all sorts of permissions that are required for full MIDP compatibility by default. To restrict the required permissions to the ones that you actually require in your app use the polish.build.android.permissions preprocessing variable:

<variable name="polish.build.android.permissions" value="READ_PHONE_STATE,ACCESS_COARSE_LOCATION,SEND_SMS,INTERNET,VIBRATE,WAKE_LOCK" />

Other Configuration Options

J2ME Polish provides following additional configuration options for Android builds:

  • polish.android.ResizeOnSoftInput: configures whether screens should resize when the soft input panel/virtual keyboard is opened. This is done by default. To deactivate this set it to false:
    <variable name="polish.android.ResizeOnSoftInput" value="false" />
  • polish.android.VibrateOnAutomaticStart: vibrates the device when the MIDlet is restarted on a previous PushRegistry.registerAlarm() setting. To activate the vibration set it to true:
    <variable name="polish.android.VibrateOnAutomaticStart" value="true" />

Supported APIs

The following J2ME APIs are supported by J2ME Polish:

  • JSR 139 CLDC 1.1: The basic Java technologies are provided by the Android stack itself
  • JSR 118 MIDP 2.0: The basic mobile information device profile APIs are supported, including RMS, low level LCDUI functionalities, HTTP connections, http: and tel: platform requests, PushRegistry alarms and audio playback.
  • JSR 075 FileConnection: Access the filesystem on the device.
  • JSR 075 PIM: Read information from the native address book.
  • JSR 179 Location: Access GPS information.

Using Native Android Views in your App

You can use native Android views in your application as well using the de.enough.polish.android.lcdui.ViewItem item. This item embeds any android.view.View:

//#if polish.android
	import de.enough.polish.android.lcdui.ViewItem;
	import de.enough.polish.android.midlet.MidletBridge;
	import android.widget.AnalogClock;

public Form createForm() {
	//#style screenClock
	Form form = new Form("Hello Clock");
	//#style info
	form.append("An the time is...");
	//#if polish.android
		AnalogClock clock = new AnalogClock(MidletBrige.getInstance());
		//#style itemClock
		ViewItem nativeItem = new ViewItem(clock);

Combining native views with a J2ME Polish application

Using Native Android Libraries in your App

You can use native libraries (*.so) files easily in J2ME Polish. Integrate libraries as you would normally do using the <libraries> element in your build.xml script:

  <library file="lib\nativejarwithsofiles.jar" if="polish.android"/>

In case your JAR file does not contain the native *.so files meaning the *.so files are placed separately, you can integrate a complete directory:

  <library dir="lib/android" if="polish.android"/>

Please note that in this case you should place the native libraries within a folder that is called "libs". In the above example, you will then end up with a folder hierarchy like this (assuming your library files are called "native.jar" and "libnative.so"):

+ lib
  + android
	+ libs
	   + libs
	      + armeabi
	      + armeabi-v7a
	      + mips
	      + x86	


You might encounter some issues when building Android applications:

OutOfMemory for dex

The creation of the .dex file terminates with an OutOfMemoryError. This error is quite common and due to insufficient memory settings in the dx executable of the android installation. Please go to ${android.home}/tools and remove the REM from the line

REM set javaOpts=-Xmx256M

and rerun the build process. If the error occurs again, increase the settings for -Xmx to a higher amount, e.g. -Xmx512M.

Verifier Error when using binary libraries

From J2ME Polish 2.1.3 onwards you can use binary libraries normally with Android:

    <library file="lib/mylib.jar" />   

This works fine but the Android Virtual Machine cannot cope with several variables having the same name but different types. Obfuscators can produce such 'name shadowing' as this is allowed in Java bytecode. In case you are encountering such problems, please either use the library in source code or ask the vendor of the library to provide a version without overloaded variable names.

Error: Missing argument for flag --package.

The problem:

[j2mepolish] Invoking precompiler [de.enough.polish.android.AndroidPreCompiler]... 
[j2mepolish] android: Usage: 
[j2mepolish] android: Error: Missing argument for flag --package. 
[j2mepolish] android: android [global options] action [action options] 
[j2mepolish] android: Global options: 
[j2mepolish] android: -h --help This help. 
[j2mepolish] android: -s --silent Silent mode: only errors are printed out. 
[j2mepolish] android: -v --verbose Verbose mode: errors, warnings and informational messages are printed. 
[j2mepolish] android: Action "create project": 
[j2mepolish] android: Creates a new Android Project. 
[j2mepolish] android: Options: 
[j2mepolish] android: -k --package Package name [required] 
[j2mepolish] android: -n --name Project name 
[j2mepolish] android: -a --activity Activity name [required] 
[j2mepolish] android: -t --target Target id of the new project [required] 
[j2mepolish] android: -p --path Location path of new project [required] 

C:\somewhere\build.xml:92: Unable to create activity / project: android returned 1

The solution: Your MIDlet needs a package hierarchy of at least two. Add a package definition to your MIDlet file like this:

package foo.bar;

Failure [-12]

The problem: When you build for the Android platform, you get the error message Failure [-12].

The solution: Your android.home points to an old Android SDK version. Please upgrade your Android installation and point the build property android.home to this upgraded installation.

Screen Resolution is too low

The problem: Your application is running on a device with a WVGA screen but the application is not using all available space.

The solution: Make sure you address the right target API. Different screen resolutions support from API version 4 upwards. Use the variables android.targetSdkVersion, android.minSdkVersion and android.maxSdkVersion to adjust the API versions.

Using DDMS

ddms (Dalvik Debug Monitor Server) is a debug and monitoring tool for your Android apps on both emulator and real devices. It is installed in ${android.home}/tools/ddms.

Starting ddms

Open console and use the cd command to target the console to the tools folder of the Android SDK: cd "C:\Program Files\android-sdk\tools" (by default). Now you can start ddms with the command ddms. After a few seconds the ddms window will open.

ddms Functionalities

n the upper left corner of the window you can see the device list. In this table all active devices, emulators and there active processes are listed. By left clicking a device the log screen at the bottom of the window will show the log output of the selected device. By clicking a process, the information screen at the right side will show some information about the selected process. Above the device list are some buttons, hover the mouse over and a short description will show up:

Show heap updatesAllows ddms to read the heap updates of the selected device
Dump HPROF FileDumps a HPROF profiling file of the selected process and saves it to the selected location
Cause an immediate GCCauses the Garbage Collector to free unused memory immediately
Show thread updatesAllows ddms to read the thread updates of the selected device
Start Method Profiling / Stop Method ProfilingAllows ddms to read and profile the used methods in the selected process
Halt the target VMStops the selected process

In the upper right corner of the window is the information screen. It is divided into seven parts:

InfoShows some basic information about the selected process.
ThreadsShows information about the threads of the selected process.
VM HeapShows information about the heap of the selected, such as size and what it contains.
Allocation TrackerWith Start Tracking, you can start the tracking of the allocations. Get Allocations list the actual allocations in the table below. Be careful, they are added to the table instead of updated.
SysinfoShows the usage of the CPU and memory of the selected device
Emulator ControlAllows you to simulate certain situations like incoming calls, position changes and so on.
Event LogHere you can configure your own event log (i.e. your are interested in only one kind of events).

Use ddms on Real Devices

For using ddms on real devices, you need to install the corresponding USB driver first. Normally this is done automatically when you connect your device via a USB cable. On the Android device itself you need to allow the USB debugging mode:

Settings-->Applications-->Development-->USB Debugging

Install Apps over USB with adb

You can install your apps using the adb tool (Android Debug Bridge). For that you need to install the USB driver first. On the device you also need to allow the installation of files from unsecure places:

Settings-->Applications-->Unknown Sources

You can now cd into the ${android.home}/tools directory and install your app with this command

adb -d install PATH
-dindicates that you want to install the application on the only connected USB device.
-rndicates that you want to reinstall an existing application
PATHreplace PATH with the APK that you want to install, e.g. dist/Google-Android2.2-en_US-rss.apk

If all worked correctly the console will show a 'Success!' Message.

back to top