Developing for Android Devices

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.

Preparations

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 Download 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:

<property 
	name="android.home" 
	location="C:/Program Files/android-sdk-windows-1.5_r1" 
/>

Building Android Application

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/android1.1 for Android 1.1 phones and Generic/android1.5 for Android 1.5 phones. You can also target a specific phone like HTC/G1.

The building of the application is done in these steps (fully automatically):

An activity is created in /activity of the Android build folder.
The R.java / Manifest.java files are created from the resources and sources via aapt of the Android SDK
The code is compiled with target and source set to Java 1.5
A file named classes.dex is created from the source code using the dx utility of the Android SDK
The resources are packed to a .ap_ file with aapt
The application is packaged to a .apk file with the SDK's apkbuilder command

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

Testing Android application

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 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 Manifest.xml file

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

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

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.
MIDlet-Icon	This variable is the path to an icon.

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.

Publishing 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 offical Android Market site for details.

Configuring 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 nativly.

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. Note that at the moment you need to use J2ME Polish rendering when using subcommands.

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

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.

Native Android commands.

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 ); 
}

Supported APIs

The following common 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, and http: and tel: platform requests
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.

For playing back audio please use the de.enough.polish.multimedia.AudiPlayer for now. Direct usage of the MMAPI is not yet supported.

Roadmap

Future versions of the Android conversion will support the conversion of the following Java Packages:

MMAPI (use de.enough.polish.multimedia.AudiPlayer for now)
Bluetooth API

Troubleshooting

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:

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

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] 

BUILD FAILED 
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;

Username:
Password: