J2ME Polish
J2ME Polish 2.4 Documentation
Enough Software

Developing for Nokia Asha Devices

Nokia Asha is a popular line of smartphones that comes with proven Java ME as well as Nokia specific extensions (the Nokia-UI-API). It's easy to support Nokia Asha from within J2ME Polish.

Preparations

Download Nokia's Asha SDKs from http://forum.nokia.com for testing locally.

After the installation you should define the nokia.home in either ${polish.home}/global.properties, ${project.home}/${user.name}.properties or in your build.xml script. nokia.home should point to the directory that contains all Nokia SDKs, by default it is installed in C:\\Nokia. If it's in installed in the default position you don't need to specify it. In your build.xml script the definition could look like this:

<property 
	name="nokia.home" 
	location="D:/SDKs/Nokia" 
/>

Asha Target Devices

Currently we support four virtual Asha devices:

  • Nokia/Series40JR20 Asha devices with Nokia Java Runtime 2.0, Nokia-UI API 1.6 and Nokia In-App-Purchase API 1.0 support
  • Nokia/Series40JR11UI11b Asha devices with Nokia Java Runtime 1.1 and Nokia-UI API 1.1b support
  • Nokia/Series40JR11 Asha devices with Nokia Java Runtime 1.1 and Nokia-UI API 1.1 support
  • Nokia/Series40JR10 Asha devices with Nokia Java Runtime 1.0 Nokia-UI API 1.1 support

Target these devices using the <deviceRequirements> section of your build.xml script.

To compare the differences between these implementations visit http://www.developer.nokia.com/Resources/Library/Java/#!developers-guides/ui-and-graphics/nokia-ui-api/changes-between-platform-releases.html.

To check if a minimum Nokia UI API is supported, just use a preprocessing comparison:

//#if polish.NokiaUiApiVersion >= 1.1b

Asha-specific J2ME Polish Features

J2ME Polish supports the following Nokia Asha-specific features:

  • Native text input native text input is automatically enabled when building for Asha devices.
  • Native icon commands: you should enable native command rendering, you can also easily add icons for native commands.
  • Native alerts you can improve the native integration of your app using native alerts.
  • Nokia Maps: use our Nokia Maps integration for realizing location based services and more.

Native Text Input

Native text input is automatically enabled when targeting a Nokia Asha device. You can use any MIDP or J2ME Polish supported text input mode.

Native Icon Commands

We highly recommend to use native commands when targeting Nokia Asha devices. Do this by setting the polish.FullScreen variable to menu only for standard Java ME devices:

<variables>
	<variable name="polish.polish.FullScreen" value="menu" unless="polish.blackberry or polish.android or (polish.NokiaUiApiVersion >= 1.1)" />
</variables>

You can define icon-images for commands in their style:

//#style cmdWithIcon
Command command = new Command("Send", Command.OK, 1 );
.cmdWithIcon {
	icon-image: url(send.png);
}

Native Alerts

While not Asha-specific we recommend to enable native alerts for Nokia Asha devices. This improves the overall user-experience and Asha-specific look and feel of your app.
Just define the polish.useNativeAlerts preprocessing variable in your build.xml script:

<variables>
	<variable name="polish.useNativeAlerts" value="true" if="polish.blackberry or polish.android or (polish.NokiaUiApiVersion >= 1.1)" />
</variables>

Font Heights

Like on Android and BlackBerry you can define a font-height also in pixels or in percent.

title {
	font-height: 28px;
}

Nokia Maps

TBD

Debugging

Okay, so the steps towards integrating On-Device debugging with vanilla Eclipse + Polish are detailed below. They may seem complicated at first, but once you go through them once it only takes 5-10 minutes to do this for another project. After everything is set up, it also takes less than 1 minute to start a new debugging session for a new build.

Initial setup

  1. Download the Nokia On-Device Debugger kit: http://www.developer.nokia.com/info/sw.nokia.com/id/c39911e1-6031-4722-9091-55b723b3c938/Series_40_ODD_Tool.html.
  2. Unzip it to a folder, henceforth called ${ROOT}.
  3. In ${ROOT}/application you will find a special Debugger app. Copy the app to the device, for example by sending it via Bluetooth.

Connecting the device to the PC

  1. In ${ROOT}/bin you will find the Connection Manager utility. Start it up. Select "Add Device". Choose to connect by IP (Bluetooth should also work, but we haven't tested it yet).
  2. On the device, start the debugger app. Connect it to the PC by entering the PC's IP. If all goes well, you should see "Status: connected" in the connection manager on the PC.
  3. On the device, press "Hide" in the debugger app. Don't worry, the debugger is still running in the background.

Required sourcecode change

Next, it's time to configure your application to work with on-device debugging:

  1. In order to use on-device debugging, you must make one change to the app. Specifically, somewhere in the source code you must ensure that System.getProperty("com.nokia.targetdebug") gets called, preferably as early as possible in the app's lifecycle. A great place to do this is in the startApp() method. *** UNTIL THIS SPECIFIC METHOD CALL IS MADE, YOU WILL NOT BE ABLE TO DEBUG YOUR APP ON THE DEVICE! ***
protected void startApp() throws MIDletStateChangeException {
	System.getProperty("com.nokia.targetdebug");
	[...]
}

Seeing Logger Output

  1. Once the build with the System.getProperty() call has been created (see above step), copy it to the device. Also keep a copy of the JAR on the PC.
  2. Run the app on the device.
  3. On the PC, in the Connection Manager, go to "Session". You should see your MIDlet in the "Running applications" list. Select it.
  4. If you want to see the app's console output, it's enough to press "Get Trace". A console window with the application output will appear. If you want full debug support, read on. *** ONCE YOU ARE DONE WITH THE CONSOLE OUTPUT, OR IF YOU WANT TO SWITCH TO FULL DEBUGGING SUPPORT, ALWAYS MAKE SURE TO PRESS "END SESSION". YOU WILL NOT BE ABLE TO USE BOTH CONSOLE OUTPUT AND FULL DEBUGGING SUPPORT AT THE SAME TIME, AND YOU CANNOT USE FULL DEBUGGING SUPPORT IF A CONSOLE SESSION IS ALREADY RUNNING (AND VICE-VERSA)! ***

Start debugging for real

Part 1: Setting up the debugger

  1. Select your MIDlet from the list and press "Attach". A pop-up window will appear.
  2. Navigate to the location of the application JAR and select it.
  3. If all is OK, you should see a pop-up saying "Please attach the debugger to port 5000".

Part 2. Setting up Eclipse

  1. Open Eclipse.
  2. Go to Run/Debug Configurations.
  3. Create a new "Remove Java Application" configuration, based on the application's project (use "Browse" to change the currently selected project, if needed).
  4. Change the port to 5000 and save the configuration.

Part 3. Start debugging!

  1. Run the debug configuration you created above. The pop-up from Part 1should now disappear, and Eclipse should be connected to the debugger. Congratulations!

Part 4. Restart debugging

If you want to restart the debugging like after an exit of the app, follow these steps:

  • Make sure the debugger is running (a green symbol should be present on the status bar on some devices) and connected to the PC (connection manager says "Status: connected". If not, repeat Connecting the device to the PC.
  • If you've changed anything in the source code or if you have created a new build, repeat steps copy the JAR again to the device.
  • Run the app again and create a new debugging session for it (like in Start debugging for real).

Debugging Troubleshooting

On-device debugging mostly works great, but there are a few caveats.

  • On-device debugging sometimes causes the device to reset itself.
  • If you are not careful (e.g. forget to close console sessions before starting a full debug session), you might end up with a "hanging" session. This means that the debugger won't connect properly and that the console output won't show in the dedicated window. In this case, from experience it's fastest if you just close everything (Eclipse, Connection Manager & Debugger app on the device) and start again clean (start eclipse, start connection manager, start debugger app, connect debugger app to connection manager).
  • For some reason, the debugger (or Eclipse) does not like some breakpoints. In particular, we can reproduce this with a a breakpoint inside an anonymous Thread class (see below). In this case, you won't be able to connect Eclipse to the on device debugger (with an error code of 41) and you'll be left with a hanging session (see previous bullet point).
Thread th = new Thread() {
	public void run() {
		while (true) {
			// break here and prepare to die:
			System.out.println("TIME " + System.currentTimeMillis()); 
			try
			{ 
				Thread.sleep(1000); }
			catch (InterruptedException e)
			{  
				e.printStackTrace(); 
			}
		}
	}
};
th.start();

Deadlock Detection with the Nokia Asha Emulator

Finding deadlocks can be tough work in J2ME development. J2ME Polish can help you to track down deadlocked threads by providing the deadlock emulator filter. Use this filter by extending your <emulator> setting in your build.xml script:

<filters>
	<filter name="deadlock">
		<package name="de.enough.polish.ui" />
		<package name="com.company.myproject" />
	</filter>
</filters>

After you have started the emulator, and your are about to approach the deadlock situation, go to the Tools -> Preferences -> MIDP Monitor and select to monitor Method calls. Please note that this tracing option will slow down your app considerably.

J2ME Polish will now regularly print out the traces of methods that are called. In a deadlock situation you will easily spot stuck threads as their method trances will be repeated often. You can now check the synchronized statements within these methods to trace the order of locks that have been obtained by each thread.

back to top