This section describes how to set up your system before starting the tutorial.

Obtaining and Installing the Required Software

The following software is required for the example:

• The NetBeans™ Integrated Development Environment (IDE) with the NetBeans Mobility Pack 4.0 Beta 2 or FCS.
  You can obtain this software from the NetBeans download site: http://www.netbeans.info/downloads/index.php
• Java™ 2 Software Development Kit, Standard Edition (J2SE™ SDK), v. 1.4.2 or higher
  You can obtain the J2SE SDK from http://java.sun.com/j2se/downloads.html
• J2ME™ Wireless Toolkit 2.0 or higher
  The J2ME Wireless Toolkit is installed with the NetBeans Mobility Pack. You also can obtain the Wireless Toolkit from http://java.sun.com/products/j2mewtooklit/index.html.
• Nokia Series 60 SDKs for Symbian OS
  The SDK can be obtained at http://www.forum.nokia.com/main/0,6566,034-483,00.html
• SDK for one or more of the following: Nokia Series 40, Nokia Series 80, Nokia Series 90, Motorola SDK4.1 for J2ME GA, Vodafone
  • You can obtain Motorola SDK4.1 for J2ME GA from http://www.motocoder.com/motorola/pcsHome.jsp?node_name=SDK (registration required)
  • You can obtain Nokia SDKs from http://www.forum.nokia.com/main/1,6566,030,00.html. Select Java in the "View tools by technology area" drop down box.
  • The Vodafone SDK is available only to Global Partners, and can not be obtained via simple online registration.

Use the instructions provided at the download sites to install the software.

Starting the IDE

To start the NetBeans IDE:

• On Microsoft Windows
  Choose Start > Programs > NetBeans version > NetBeans IDE.
• On UNIX, or Linux environments
  In a terminal window, type sh IDE-install-path/bin/runide.sh

The IDE-install-path variable stands for the path to the IDE's home directory.

Obtaining the Required Source Files

The MarvTheMiner_120_all.zip file contains the source files of the original Marv The Miner application. The zip includes a MarvTheMiner directory, which contains the src and res subdirectories that you will use in this tutorial.

To unzip the MarvTheMiner_120_all.zip file:

1. In your file system, create a temporary location for the contents of MarvTheMiner_120_all.zip.
   For example, this tutorial refers to this directory as the C:\temp directory.
2. Use an application that unzips files to unzip the MarvTheMiner_120_all.zip file to the temp directory.
   The temp directory now has a MarvTheMiner directory, which contains the following files and subdirectories:



File or Subdirectory	Description
/products/index.htmlsrc	The source files which make up the Marv The Miner program.
res	Contains the resource files used by the program. This includes graphics as well as .map files which are used to define the game level's layouts.
MarvEditor	A level editor (outside the scope of this tutorial).
Nokia.full	A Nokia build of the game.
MIDP.full	A generic MIDP build of the game.



3. Move the res directory to C:/temp/MarvTheMiner_120_all/src/. This is a small work-around to make sure the resource files maintain the correct relative path once we create a new NetBeans project.

Import existing sources

Creating the Project

The first step is to create a new project in the NetBeans IDE.

1. Choose File > New Project from the main menu.
   The New Project wizard is displayed.
2. In the Categories list select Mobile. Then select Mobile Project from Existing MIDP Sources and click Next.
3. If you did not install NetBeans using the installer, you are shown a panel here instructing you to install a mobile platform. Follow the instructions and install some version of the Wireless Toolkit. Then click next.
4. For the Imported Sources Location, click the Browse button and navigate to C:/temp/MarvTheMiner_120_all/src directory that you created when you unzipped the MarvTheMiner_120_all.zip file. Select the src directory, and click Open. Click Next.
5. Enter a name for your New Project. For example, name it MarvTheMiner.
6. Now select a directory where the new project directory should reside. Make sure the Set as Main Project check box is enabled, and click Finish.
   A new project, MarvTheMiner, is created and displayed in the IDE's Projects tab.
7. Expand the MarvTheMiner root project node to see the project's sources and resources. Expand the <default package> node and then double click on Main.java to open that file in the editor.

Creating Project Configurations

The NetBeans device fragmentation solution is based on the use of project configurations. A project should have one project configuration for each distribution Jar/Jad you would like created for that project.

If you examine the file Main.java, you will see that the the authors support multiple platforms with a combination of comments (for Nokia's FullCanvas) and Class.forname(). They also define a variable vendor that is used to track on which phone the application is running. Based on this information, you can see that they are supporting five different groups of phones:

• Nokia Series 60
• Other Nokia
• Motorola
• Vodafone
• Other

As such, you will create four configurations to handle differences between these distributions.

Creating a Configuration

1. Right-click on the MarvTheMiner project node and select Properties.
   This opens the Project Properties page that is used to control most aspects of the project.
2. Click the Manage Configurations button at the top of the page. This opens the Manage Configurations dialog.
3. Click Add and then type NokiaSeries60 and press OK.
4. Repeat the previous step for Motorola, Vodafone, and NokiaOther. Click Close to close the Manage Configuration dialog.

The Project Configuration combo box at the top of the Project Properties page should now contain five configurations. We will use these configurations in a moment, but for now lets add some emulators into the IDE.

Adding Emulators to the IDE

To run the project using the emulator platforms you have installed on your computer, you must first register them with the IDE.

1. Select DefaultConfiguration in the Project Configuration combo, and then select the Platform node. Click the Manage Emulators button. The Platform Manager dialog appears.

   Note that this dialog can also be accessed from the main menu at Toeols>Java Platform Manager.

2. Click Add Platform and navigate to the directory where you installed your Nokia Series 60 emulator. Click Next.
3. Ensure that the emulator settings were detected correctly, and then click Next.
4. Here you can point to the source and javadoc files for the emulator if you want. Otherwise just hit Finish to complete the installation of the platform.

5. Repeat these steps for each emulator platform you have installed on your machine and that you want to use from within the IDE.

   

   Note that only emulators that comply with UEI standards will be detectable by the IDE. Unfortunately, this means that the Motorola 7.5 emulator that the developers used for Marv The Miner can not be detected. A later section in the tutorial will explain a work-around for using non-UEI emulators from within the IDE.

Customizing Project Settings for Configurations

Each panel in the Project Properties page can be customized separately for each project configuration. By default, configurations will use the settings defined in the default configuration.

1. Open the Project Properties page and select the Platform panel. Make sure DefaultConfiguration is selected in the Project Configuration combo box.
2. Select J2ME Wireless Toolkit 2.x in the Emulator Platform combo box. Toggle the radio buttons to CLDC-1.0 and MIDP-2.0.
   By default, all configurations will use this emulator for building and executing the project. This isn't what we want, however, as the code references several platform-specific libraries.
3. Select the NokiaSeries60 configuration from the Project Configuration combo.
   The Platform panel is now entirely grayed out. This is because we are currently using the values from DefaultConfiguration for this panel.
4. Uncheck the Use Values from "DefaultConfiguration" check box at the top of the panel.
   All elements in the panel should now be enabled. Select the Series 60 MIDP Concept SKD Beta 0.3.1 Nokia platform from the Emulator Platform combo box.

   If you toggle between the each configuration, you'll see that all are now using the value specified in DefaultConfiguration except for the NokiaSeries60 configuration. If you change any of the configuration settings in the DefaultConfiguration Platform panel, the changes will propagate to all configurations except NokiaSeries60.

5. Select the NokiaOther configuration in the Project Configuration combo box. Uncheck the Use Values from "Default Configuration" checkbox and select one of the other Nokia platforms you installed.
6. Repeat these steps for the Vodafone platform as well.
7. As mentioned above, the Motorola 7.5 emulator is not UEI-compliant and could therefore not be installed into the IDE. However, we can still point to its APIs for compilation purposes. Activate the Motorla configuration and select the Libraries & Resources panel.
8. Uncheck the Use Values from "DefaultConfiguration" checkbox.
9. Click Add Jar/Zip and navigate to {motorola install directory}\Emulator7.5\lib. Select each .zip file (using ctl+mouse) and click Open.
10. Click OK to exit the project properties. You are done creating projects configurations for now.

Creating Custom Code Blocks for each Configuration

The second part of the device fragmentation solution is the ability to specify certain blocks of code in your source files as being specific to one or more configurations. This is accomplished by using actions in the right-click context menu of the editor, or from the Edit > Preprocessor Blocks menu.

1. Open Main.java, and examine the initStaticData() method. Here, the method is determining at runtime which device-specific APIs are available, and then behaving accordingly. This is a very clever solution to some parts of the device fragmentation problem. Unfortunately, it also has the problem of being increasing the size of the distribution Jar, impacting runtime performance, adding complexity to the sources, and does not solve all fragmentation problems (as you will see later).

Here is the pertinent part of initStaticData():

   vendor = 0;
   try
   {
       // Nokia
       Class.forName("com.nokia.mid.sound.Sound");
       vendor = 1;
       try
       {
           Class.forName("com.nokia.mid.ui.DeviceControl");
           com.nokia.mid.ui.DeviceControl.setLights(0,100);
           vendor = 2;
       }
       catch(Exception ex2){}
   }
   catch(Exception ex){}

   try
   {
       // Vodafone
       Class.forName("com.vodafone.v10.system.device.DeviceControl");
       com.vodafone.v10.system.device.DeviceControl.getDefaultDeviceControl().
           setDeviceActive(com.vodafone.v10.system.device.DeviceControl.BACK_LIGHT,
           true);
       vendor = 3;
   }
   catch(Exception ex){}

   try
   {
       // Motorola
       Class.forName("com.motorola.multimedia.Vibrator");
       Class.forName("com.motorola.multimedia.Lighting");
       com.motorola.multimedia.Lighting.backlightOn();
       vendor = 4;
   }
   catch(Exception ex){}
                    

2. Remove all of the functionality that is only dealing with determining which device the program is running on, so the code you are left looks like following:

 // Nokia
   com.nokia.mid.ui.DeviceControl.setLights(0,100);

   // Vodafone
   com.vodafone.v10.system.device.DeviceControl.
   	getDefaultDeviceControl().
   	setDeviceActive(com.vodafone.v10.system.device.DeviceControl.BACK_LIGHT,
   			true);

   // Motorola
   com.motorola.multimedia.Lighting.backlightOn();
                    

You now have three blocks of code that should be associated with your different configurations.

3. Highlight the Motorola-specific lines, then right-click on the editor and select Preprocessor Blocks>Motorola.
4. Repeat this step for the Vodafone block (Preprocessor Blocks > Vodafone).
5. For the Nokia code, select Preprocessor Blocks>Manage Preprocessor Block.
   This opens the Manage Preprocessor Block dialog.
6. Select the options for both NokiaOther and NokiaSeries60 and click OK.

These code blocks are now associated with the configurations listed in the headers and footers of the preprocessor blocks. Changing the project's active configuration will trigger a preprocessor that will comment in and out blocks based on if the active configuration is a part of the preprocessor block's header and footer.



7.  Change the project's active configuration by using the combo box in the main toolbar.
   You can also do this by right-clicking on the project node>Set Active Project Configuration>select configuration from the same menu in the main Build menu, or by toggling the Configuration combo in the main toolbar (if your project is currently the main project).
   
   Notice that the code block highlighting switches colors to identify which blocks are active or inactive. The active configuration name is also highlighted a different color in the header/footer of the code blocks.
   
8. Remove all the instances of class.forName() from the beep() method. If you also condense the if blocks, you are left with the following code:

if (midlet.muteSound == 0)
{
   // Nokia 3650, 7650
   com.nokia.mid.sound.Sound sound = new com.nokia.mid.sound.Sound(1000,100);
   sound.play(1);
     // All other Nokias
   com.nokia.mid.sound.Sound sound = new com.nokia.mid.sound.Sound(1000,100);
   sound.play(1);

}

if (midlet.useVibra == 1)
{
   // Nokia
   com.nokia.mid.ui.DeviceControl.startVibra(50,500);
     // Vodafone SDK
   com.vodafone.v10.system.device.DeviceControl.
   	getDefaultDeviceControl().
   		setDeviceActive(
   			com.vodafone.v10.system.device.DeviceControl.VIBRATION,
   			true);
   vibra_delay = 10;

   // Motorola 7.5
   com.motorola.multimedia.Vibrator.
   	setVibrateTone(
   		com.motorola.multimedia.Vibrator.VIBRATE_LONG);
   com.motorola.multimedia.Vibrator.vibrateFor(500);

}

You should be able to associate each block with the correct configuration. Remember to associate the Nokia vibration control call with both Nokia configurations.

9. The run() method also contains a Vodafone-specific call. Remove the try/catch blocks and associate the two lines with the Vodafone configuration.
   

We're almost done. The final step is to somehow handle Nokia's FullCanvas.

10. Activate the NokiaSeries60 configuration.
11. Right click on the FullCanvas declaration and select Create If/Else Block (NokiaSeries60).
12. Right click on the first block and add NokiaOther.
13. Right click on the second block and add NokiaOther.
14. The second block is an Inverted block. Change the inverted block class definition to extend Canvas.

When you are done, your class definition should appear like so:

Building and Executing the Application

At this point, we should be able to compile and run the program for all of our configurations. Clicking any of the icons in the main toolbar will execute the selected action for the Active configuration.

1. In the main menu, select Build > Build All Main Project Configurations.
   Assuming everything is set up correctly, all configurations should now be built.

   If you did not have access to one or more of the emulator platforms containing the correct APIs, this step might fail. If that is the case, you should manually comment out any line making a call to an API that you don't have.

   Preverification will fail for the Motorola configuration if you have not followed the steps to manually install the motoral emulator described in the section for non-UEI emulators. To make this configuration compile without manually adding the emulator, you can comment out all motorola API calls and remove the motorola libs from the Libraries & Resources panel.

2. Select the Files tab in the upper left hand side of the IDE and expand the dist folder. In this folder you should have directories containing Jar/JADs for each configuration that was successfully built, as well as a Jar/Jad that represents the DefaultConfiguration build.
3. Press F5 to run the program for the currently selected configuration. You can switch configurations and press F5 again to run multiple versions of the program at the same time.

• Each panel in the project properties page can be configuration-specific (except the General page). This gives you a great amount of flexibility. For example, you can have different MIDlet-Version values (Application Descriptor panel) for each configuration's uniquely named (Creating Jar panel) distribution Jar.
• When setting up dependencies between projects, especially when using Project Configurations, make sure to select the correct output jar in the Project Jar Files list box of the Select Project dialog. A project Jar will appear for each configuration in the project you have selected.

  If, for example, you have two projects MyLibrary and MyApplication, both containing two configurations ReleaseConfiguration and DebugConfiguration, then you would take the following steps to set up the dependency correctly:

  • Open Project Properties for MyApplication. Select ReleaseConfiguration in the Project Configuration combo.
  • Select Libraries & Resources panel, and click the Add Project button.
  • Navigate to the location of MyLibrary project. The Project Jar Files listbox will now contain three Project Jars. Select the one in path dist/ReleaseConfiguration/ and click Add Project Jar Files
  • Switch to DebugConfiguration and repeat these steps, except this time add the project jar located in dist/DebugConfiguration/

  This is the manner in which you should set up dependencies between projects when configurations are involved.

• The solution is VCS-friendly. All source files will always be saved to the hard drive as if DefaultConfiguration was selected. This prevents conflicts during VCS check-in or update resulting from have a different active configuration. Be sure to also share your project.properties file (located in {projecthome}/nbproject)!
• Projects can be run from the command line without the use of the IDE. Just type ant run in the project home directory and the project will be run using the active configuration. You can pass a different configuration to the ant script by typing ant run -Dconfig.active={config_name}
• Projects that used existing preprocessor solutions should be easy to import. Though the NetBeans preprocessor is less complex than some, any situation can be expressed using the provided directives.
• The Libraries & Resources panel or the Filtering panel can be used to determine which version of a resource should be deployed to a distribution Jar.
  • Libraries & Resources: Create multiple versions of a Jar file containing all resources for the application and then point to the correct version of the Jar for each configuration. So you might have 3 jars: large_res.Jar, medium_res.Jar, small_res.Jar each containing resources of the same name, but different resolutions. Then point your Nokia_large, Nokia_med, Nokia_small configurations at the correct version.
  • Filtering: Include your resources directly in or under the src directory then use the Filtering tree to control which version of the resources are included in the distribution Jar.

Adding Non-UEI Compliant Emulators

1. In your userhome directory (the Windows default is C:\Documents and Settings\{username}\.netbeans and the Linux default is /home/{username}/.netbeans), examine the {userhome}\config\Services\Platforms\org-netbeans-api-java-Platform directory.
   This directory contains xml files that define the installed emulator platforms. You can manually create these files for any emulator which is not UEI-compliant. The DTD for this xml file can be found at http://www.netbeans.org/dtds/j2me-platformdefinition-1_0.dtd
2. Save the following as SDK_4.1_MRI_7.5.xml to use the Motorola 7.5 emulator needed for this tutorial. Note that the use of &quot; is intentional, and should be saved as such.

<?xml version='1.0'?>
<!DOCTYPE platform PUBLIC '-//NetBeans//DTD J2ME PlatformDefinition 1.0//EN'
	'http://www.netbeans.org/dtds/j2me-platformdefinition-1_0.dtd'>
<platform name="Motorola_7_5"
home="C:\WTK\Motorola\SDK v4.1 for J2ME\Emulator7.5"
type="custom"
displayname="Motorola 7.5"
srcpath=""
preverifycmd="&quot;{platformhome}/bin/preverify.exe&quot;
	-classpath &quot;{classpath}&quot; -d &quot;{destdir}&quot;
	&quot;{srcdir}&quot;"
runcmd="">
    <device name="Motorola_7_5" securitydomains="trusted,untrusted"
    	description="Motorola_7_5">
        <configuration name="CLDC" version="1.1" displayname="CLDC"
        	classpath="${platform.home}/lib/cldc.zip"
        	dependencies="" default="true"/>
        <profile name="MIDP" version="2.0" displayname="MIDP"
        	classpath=";${platform.home}/lib/midp.zip"
        	dependencies="" default="true"/>
    </device>
</platform>

You will need to restart the IDE after saving this XML file. Once you have done so, you will be able to choose Motorola 7 5 as a platform and Motorola_7_5 as a device. You should associate the Motorola configuration with this new platform. Note that you may need to delete the cache files located in {userhome}\var\cache in order for the manually installed platform to be detected. Also, you should not delete the mdrstorage folder that may also be located there.

Notice that the runcmd attribute is set to empty string. This is because the command to start this Motorola emulator takes the MIDlet to execute as one of its parameters. This is nothing like UEI standards, and cannot be directly supported in the IDE. However...

3. If the emulator platform you're using does not require more information than that provided to UEI emulators, then you can skip this step. The following information is provided to UEI emulators:
   • Security Domain
   • Platform Type
   • Platform Home
   • Jad Location
   • Jad Destination Directory / Jad Name

If your emulator requires additional information (such as the location of project Jar or the name of the MIDlet to execute), you can execute emulators by modifying the build.xml file located in your project home directory.

This file controls all project actions. We can create a new target here that executes the motorola emulator and passes all appropriate data whenever the Run action is invoked on the Motorola configuration.

Add the following code your project's build.xml:

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

        <ant inheritrefs="true" inheritall="true" target="run_motorola"/>

    </target>

    <target description="Run MIDlet suite the normal way." depends="init"
    	name="run_normal" unless="run.motorola">

    	<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 for motorola's non-UEI emulator."
    	depends="init" name="run_motorola" if="run.motorola">
        <property name="project.home" location="."/>

        <!-- the last arg line contains an value "Miner".
                This must match the name of the midlet you want to execute  -->
        <java dir="${platform.home}/bin"
              fork="true"
              classname="com.mot.tools.j2me.emulator.Emulator"
              classpath="${platform.home}/bin/Emulator.jar;${platform.home}/bin/configtool.jar">
            <jvmarg value="-Djava.library.path=${platform.home}/lib"/>
            <arg value="-classpath${project.home}/${dist.dir}/${dist.jar}"/>
            <arg line="-deviceFile"/>
            <arg value="${platform.home}/bin/RESOUR~1/T720I~1.PRO"/>
            <arg line="javax.microedition.midlet.AppManager Miner -JSA 1 1"/>
        </java>

    </target>

So the run_motorola target will be run whenever the active configuration is Motorola. Otherwise, the run_normal target (which uses the normal emulator execution) will be invoked.

This concludes the Marv the Miner tutorial.