J2ME MIDP Device Fragmentation Tutorial with Marv The Miner(1)

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
src	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 pathoncewecreate 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: