Running Java ME Applications

There are multiple ways of running your Java ME technology-based application. The easiest and most straightforward way is to use the Sun Java Wireless Toolkit (WTK) or the NetBeans IDE with the NetBeans Mobility Pack. But there are also substantial benefits to running and testing your application on the phoneME Feature and/or phoneME Advanced platforms. These various options are discussed below.

Running Your Application on the Sun Wireless Toolkit (WTK) or the NetBeans Mobility Pack

The Sun Wireless Toolkit (WTK) is a complete emulation platform that supports the latest Java ME functionality and APIs and allows you to run your application easily and quickly.

The NetBeans IDE with the NetBeans Mobility Pack includes the core functionality of the WTK by adding the WTK as an emulator environment.

For more information on WTK and Netbeans Mobility Pack, see our Developer Tools page.

Running Your MIDlet on the phoneME Feature Platform

You can benefit substantially from using the phoneME Feature and/or Advanced platform during the development and testing of your applications. By running an application regularly on the phoneME platform, you will understand how your application works on a real-world Java ME software stack, you can catch problems early, and you can make your application more robust. You will also gain insight into the phoneME platform itself; you can view the platform sources in the phoneME project community; and you can interact with phoneME developers. All of these benefits give you unprecedented access to the Java ME platform implementation.

Basically you have two options for running phoneME Feature:

From the Command Line
The most direct way is to run it from the command line. Use this option if you just want to try out phoneME Feature without using the NetBeans IDE, or if you are considering running phoneME Feature from within your own development environment.

Within the NetBeans IDE
Alternatively, you can run phoneME Feature as an emulator platform within the NetBeans IDE. Use this option if you are developing your application in NetBeans with the NetBeans Mobility Pack and you would like to benefit from the tight integration and ease-of-use that NetBeans software provides with emulator platforms.

Running phoneME Feature From the Command Line

Here are the quick-start instructions to run a MIDP application on phoneME Feature Milestone Release 2 (MR2) on your machine.

Download and install the binary bundle.
Navigate to the phoneME Feature MR2 downloads section.

Locate the latest binary bundle appropriate for your platform, for example:
MR2 binary bundle (b10) - Windows/x86 platform
or
MR2 binary bundle (b10) - Linux/x86 platform
Note: The higher the build number (e.g., b10), the more current the build.

Extract the compressed file to a directory that we will refer to as <rootdir>.

Following are Windows instructions. Linux is similar if you replace the path and variable syntax.

Install the MIDlet. This can be done in any of three ways.

From the DOS command line, enter:
set MIDP_HOME=<rootdir>\bin\win32_x86_javacall_mvm cd %MIDP_HOME%

Then, to install a MIDlet from the file system:
bin\i386\installMidlet file:///c:/<jad-dir>/<jad-file>.jad (or .jar)

Or, to install a MIDlet from a URL:
bin\i386\installMidlet http://<server>/<jad-uri>/<jad-file>.jad

Or, to install a MIDlet from a URL using the emulator user interface:

bin\i386\userTest
From the emulator, select Install Application and launch.
Enter the URL of the jad file to install.

Run the MIDlet. This can be done in either of two ways.

From the command line:
bin\i386\runMidlet <midlet-suite-number>
(Note: If this is the first suite you install, the suite number will be 1.)

Via the emulator interface:

bin\i386\userTest
From the emulator, select the installed application and launch.

You can find more information about phoneME Feature on the phoneME project pages.

Using phoneME Feature From Within the NetBeans IDE

As described previously, phoneME Feature can be used from the command line to run MIDlets. However, by integrating phoneME Feature into the NetBeans IDE, you can much more easily use phoneME to run and debug MIDlets.

The NetBeans IDE supports the concept of multiple Java platforms. More importantly, with NetBeans Mobility Pack you can work with multiple Java ME emulator platforms, one for each Java ME device platform that will support your MIDlet. By defining a new emulator platform for phoneME Feature along with existing emulator platforms (such as the default WTK emulator), you can switch between phoneME and other emulator platforms with the push of a button. This makes it extremely easy to run your MIDlet on phoneME Feature during all phases of your development process.

Java ME Platforms Supporting the Unified Emulator Interface (UEI)
If an emulator platform supports the UEI, NetBeans can automatically detect the emulator and configure it for instant use. Unfortunately, phoneME Feature does not yet support the UEI, so some manual work needs to be done to integrate phoneME Feature with the NetBeans IDE. We plan to update phoneME Feature with UEI support in the near future, so eventually the manual steps described below will become unnecessary.

Integrating phoneME Feature Into NetBeans (Windows Instructions)

To integrate phoneME Feature into the NetBeans IDE, follow these steps.

Make sure you have the NetBeans IDE and NetBeans Mobility Pack installed.
Download the phoneME binary and unzip it onto your hard disk. Note the location of the midp directory in the phoneME package.
Start the NetBeans IDE.
Create a new Java platform with the following steps:
- Select Tools>Java Platform Manager.
- Select Add Platform.
- Select Custom Java Micro Edition Platform Emulator and click Next.
Define the platform home, platform name, device name, and preverify command. The platform home directory must be the midp directory noted above. Click Next.

The NetBeans IDE detects all possible libraries of the platform. Remove all except for classes.zip. Click Finish.

At this point, the new phoneME Feature MR2 platform and the pMEFDefaultDevice configuration have been created.

Updating NetBeans Projects to Use the Newly Defined phoneME Feature Emulator Platform

After creating the new pMEFDefaultDevice configuration, you will need to update your NetBeans project properties to be able to use this new configuration and device.
- Select File-->Set Main Project to choose the project you want to update. In this example the project is WTK-Demos.
- Select File-->WTK Demos Properties.
- Click on Manage Configurations and add a new configuration using the pMEFDefaultDevice_template. Click OK to confirm and close.

Next, you must override the NetBeans default run and debug ant targets to instruct NetBeans how to execute the phoneME Feature runMidlet.exe command with the appropriate parameters.

In NetBeans, open your project build.xml file in the top level project directory.
Add the following to the end of the file (before the tag):


<target description="Run MIDlet suite" depends="init" name="run"> 
        <condition property="run.phoneME"> 
            <!-- arg2 must match the configuration name 
                    you would like to use the special emulator --> 
            <equals arg1="${config.active}" arg2="pMEFDefaultPhone"/> 
        </condition> 
        <ant inheritrefs="true" inheritall="true" target="run_normal"/> 
        <ant inheritrefs="true" inheritall="true" target="run_phoneME"/> 
    </target> 

    <target name="debug" description="Debug MIDlet suite" depends="init,clean,jar"> 
        <condition property="debug.phoneME"> 
            <!-- arg2 must match the configuration name 
                    you would like to use the special emulator --> 
            <equals arg1="${config.active}" arg2="pMEFDefaultPhone"/> 
        </condition> 
        <ant inheritrefs="true" inheritall="true" target="debug_normal"/> 
        <ant inheritrefs="true" inheritall="true" target="debug_phoneME"/> 
    </target> 

    <target description="Run MIDlet suite the normal way" depends="init" 
    	name="run_normal" unless="run.phoneME"> 
    	<nb-run commandline="${platform.runcommandline}" 
        securitydomain="${evaluated.run.security.domain}" 
        	execmethod="${run.method}" platformtype="${platform.type}" 
        	platformhome="${platform.home}" device="${platform.device}" 
        	jadurl="${dist.jad.url}" jadfile="${dist.dir}/${dist.jad}"/> 
    </target> 
    
    <target description="Run MIDlet suite on phoneME" 
    	depends="init" name="run_phoneME" if="run.phoneME"> 
        <property name="project.home" location="."/> 
        <exec executable="${platform.home}/bin/i386/runMidlet_g.exe" 
              dir="${platform.home}/bin"> 
<arg line="internal -classpathext ${project.home}/${dist.dir}/${dist.jar} example.manyballs.ManyBalls"/> 
        </exec> 
    </target> 

    <target description="Debug MIDlet suite on phoneME" 
    	depends="init" name="debug_phoneME" if="debug.phoneME"> 
        <property name="project.home" location="."/> 
        <delete file="${build.dir}/.timestamp"/> 
        <property name="jpda.port" value="2810"/> 
        <parallel> 
            <exec executable="${platform.home}/bin/i386/runMidlet_g.exe" 
                  dir="${platform.home}/bin"> 
<arg line="-debug internal -classpathext ${project.home}/${dist.dir}/${dist.jar} example.manyballs.ManyBalls"/> 
            </exec> 
            <sequential> 
              <sleep seconds="2"/> 
              <java jar="${platform.home}/bin/i386/kdp.jar" fork="true"> 
<arg line="-l ${jpda.port} -p -r localhost 2808 -cp ${platform.bootclasspath};${dist.dir}/${dist.jar}"/> 
              </java> 
            </sequential> 
            <sequential> 
              <sleep seconds="4"/> 
              <antcall target="nbdebug"/> 
            </sequential> 
        </parallel> 
    </target> 

    <target description="Debug suite the normal way" 
        depends="init" name="debug_normal" unless="debug.phoneME"> 
        <property name="project.home" location="."/> 
        <echo message="debug normal"/> 
        <delete file="${build.dir}/.timestamp"/> 
        <parallel> 
            <nb-run debug="true" debugsuspend="true" debugserver="true" 
            debuggeraddressproperty="jpda.port" 
            platformtype="${platform.type}" 
            platformhome="${platform.home}" 
            device="${platform.device}" 
            jadfile="${dist.dir}/${dist.jad}" 
            jarfile="${dist.dir}/${dist.jar}" 
            execmethod="${run.method}" 
            securitydomain="${evaluated.run.security.domain}" 
            commandline="${platform.debugcommandline}" 
            classpath="${platform.bootclasspath}:${dist.dir}/${dist.jar}" 
            cmdoptions="${run.cmd.options}"/> 
            <sequential> 
                <sleep seconds="5"/> 
                <antcall target="nbdebug"/> 
            </sequential> 
        </parallel> 
    </target>

Note that the class name of the MIDlet to be run (example.manyballs.ManyBalls) is hard-coded. If you modify your MIDlet and change that class name or package, you must manually update both of the corresponding entries in build.xml. Unfortunately, for non-UEI platforms, this cannot be avoided.

Running Your MIDlet on phoneME Feature From Within the NetBeans IDE
At this point you have completed the integration of phoneME Feature MR2 with the NetBeans IDE and updated your NetBeans project properties. You are now ready to try it out.

When debugging Java ME applications the KDWP protocol is used for communication between the debugger and the debug proxy via specified network ports. To enable debugging you need ensure your local firewall is not blocking this network traffic. For example, in the below build.xml file ports 2808 and 2810 are used and must be open for network traffic.

In the drop-down menu in the NetBeans toolbar, select the default WTK emulator configuration (DefaultConfiguration).
Press the F6 key to run the main project.
The WTK emulator should start up in a separate window and run your MIDlet as usual.

Now run your project on phoneME Feature.
In the drop-down menu, switch from DefaultConfiguration to pMEFDefaultPhone.
Press the F6 key again.
phoneME Feature should start up in a separate window and run your MIDlet, just as it did with the WTK emulator (DefaultConfiguration) before.
This demonstrates how easy it is to switch between the WTK emulator and phoneME Feature for testing and development purposes.

Now you are ready to try debugging your project.
With the configuration still set to pMEFDefaultPhone, press the F5 key.
Again, phoneME Feature will start up in a separate window, but it will not yet start executing the MIDlet.
After a few seconds (be patient, this can take up to 15 seconds), the debugger session is established between the NetBeans software and phoneME.
You now have full source-code debugging capabilities just as you do with the WTK emulator.

In the screen shot below, the ManyBalls MIDlet is running. A breakpoint was set in the commandAction() method. The phoneME window is on the right. The MIDlet is started and executes until the MIDlet menu item 2 (Help) is selected. At that point the breakpoint is hit, and execution of the MIDlet is interrupted, as shown in the screen shot. The window of the call stack is shown to demonstrate full debug support.
Note: While debugging with phoneME Feature, the MIDlet execution speed might be substantially slower than that of the WTK emulator. Debugging on a real embedded platform stack, such as phoneME Feature, incurs substantially larger overhead than on an emulation platform, such as WTK. This is generally not a problem, because typically speed is not a concern during debug sessions.

How to Build Your Own phoneME Feature Binary

If you simply want to use phoneME Feature to run and debug your MIDlets, the easiest approach is to download and use the pre-built binary as described above.

However, if you are interested in experimenting with phoneME options and configurations, or if you want to modify the phoneME source code, you will need to build the phoneME binaries yourself.

Building phoneME Feature binaries from the sources takes some effort because phoneME Feature consists of multiple modules and supports a wide array of configurations and options. However, the phoneME Feature build process is fully automated. Once you have built the first phoneME binary yourself, it is easy to make changes to the source code and to build configurations and re-build. This means you can experimentally dig into the platform, enhance your understanding, and participate fully in the evolution of phoneME and Java ME software.

You will find a complete guide to building phoneME Feature Milestone Release 2 (MR2) on the phoneME Feature wiki.

The instructions in the wiki have been tested and should work for most environments. Because it is a wiki, you can annotate the instructions there to help fellow community members.

Happy experimenting!

Main Menu