J2ME Wireless Tool Kit Integration

J2ME and J2EE technologies can be used together to create mobile and wireless applications. As the J2ME technology emerges and more profiles become available on J2ME-enabled devices, the ability to put enterprise data and services onto cellular phones, pagers, PDAs, and other wireless devices using Java becomes increasingly feasible.

Developers may use Studio to build, package, execute and debug J2ME applications, with the Java 2 Platform, Micro Edition (J2ME)Wireless Tool Kit. The following sections describe how to create MIDP applications using J2ME Wireless Module in Studio.

Installing J2ME Wireless Tool Kit

Download the kit from http://java.sun.com/j2me

Execute j2me_wireless_toolkit-1_0_4_01-bin-win.exe (on Windows) and j2me_wireless_toolkit-1_0_4_01-bin-linuxi386.bin(on Linux).

This brings up the installation wizard. Enter the required fields in the panels that come up and install the kit. Ensure that in the Setup panel, the type of setup is selected as Stand Alone.

Pramati Studio supports the 1.0.4 or a greater version of J2ME Wireless Tool Kit.

For detailed information on how to install the J2ME Wireless Module, refer the J2ME Wireless Tool Kit User's Guide.

Configuring the J2ME ToolKit

Once the J2ME Wireless Tool Kit has been installed, configure the installed location in Studio. To do this,

Click on Tools > J2ME Wireless Tool Kit > Configure J2ME Tool Kit from the main menu. This brings up the configure dialog.

Browse for the location of the installed toolkit, using the browse button. This automatically fills the executable names of the different properties existing in the toolkit.

The executable names are editable fields, and the user, if required may change these by selecting the name, and retyping it.

Creating MIDlet Suites

MIDP applications, or MIDlets, are packaged into a MIDlet Suite. MIDlet Suites are a group of MIDlets that share resources at runtime. A MIDlet Suite includes:

A Java Application Descriptor (JAD) file This file contains a predefined set of attributes (denoted by names that begin with "MIDlet-") that allow application management software to identify, retrieve, and install the MIDlets. All attributes appearing in the JAD file are made available to the MIDlets. The user may define application-specific attributes and add them to the JAD file

A Java Archive (JAR) file This contains

Java classes for each MIDlet in the Suite

Java classes shared between MIDlets

Resource files used by the MIDlets (for example, image files)

A manifest file describing the JAR contents and specifying attributes used by application management software to identify and install the MIDlet Suite

an empty Suite with no MIDlets, or

a MIDlet Suite with existing source files.

Creating an empty MIDlet Suite

To create a empty MIDlet Suite, right click on the Desk Root node and select New Folder > MIDlet Suite. This pops up a dialog, where the following information has to be filled in:

Enter the name of the Suite in the New MIDlet Suite field.

The location where the MIDlet sources are stored is filled automatically. Modify, if required. The JAD and JAR files, are both stored under this directory.

The Class Directory is also automatically filled and may be modified.

Click OK. This creates an empty MIDlet Suite in the Desk.

Importing Existing Sources

To create a MIDlet with existing source files, right click on the Desk Root node and select New Folder > MIDlet Suite. This pops up a dialog, where the following information has to be filled in:

Enter the name of the Suite in the New MIDlet Suite field.

The location where the MIDlet sources are stored is filled automatically. Modify, if required. The JAD and JAR files, are both stored under this directory.

The Class Directory is also automatically filled and may be modified.

Check the option, Use Existing Sources.

Source Dir Browse for and select the location of the source files. The source directory should contain the source files in the appropriate package hierarchy.

JAD location Browse for and select the appropriate .jad file, in case it is not automatically filled.

Click OK. This creates a MIDlet Suite with all the required source files.

Creating MIDlets

MIDP applications are also known as MIDlets. Follow the given instructions to add MIDlets to the MIDlet Suite:

Right click on the MIDlet Suite node in the Desk and select New File

In the New File Type dialog that pops up, select MIDlet and click OK

In the MIDlet dialog that pops up, fill in the following information:

Enter the class name along with package hierarchy in Class Name field

Select the Source Root for the created MIDlets in the active Desk. By default, it is selected as the active MIDlet

Select the template as either HelloMIDlet or MIDPCanvas

Click OK. This created MIDlet under the selected Source Root, and opens the file in the Display Panel.

Note: Use the Import Files option, available on a right click to add the resources (used by the MIDlets) to the MIDlet Suite.

Importing existing MIDlets

To import existing MIDlets to the MIDlet Suite, right click on the MIDlet Suite node or any appropriate directory under the Suite, and select Import Files. All the resource files used by the MIDlets must also be imported in a similar way.

Customizing MIDlet Suite Properties

Studio allows the user to customize the MIDlet Suite properties. These properties include:

Attributes used by the application management software to identify and install the MIDlet Suite. These attributes go into the JAR manifest.

Attributes (denoted by names that begin with "MIDlet-") that allow the application management software to identify, retrieve, and install the MIDlets. These attributes go into a Java Application Descriptor (JAD) file

To customize the attributes, right click on the MIDlet Suite for which properties are to be set and select MIDlet Suite Attributes.

In the Attributes dialog that pops up, five types of properties can be set. Modify the required fields and click OK

Required This tab contains all the mandatory fields of the MIdlet. The values of these attributes may be edited after selecting it.

User Defined To add a new user defined property, click on Add. This creates a new row, where the attribute name and value can be entered. To remove the entry, select the row and click on the remove button.

MIDlets Specify all the MIDlet specific attributes, by entering the values here.Use the Move Up and Move Down buttons to change the order of the MIDlets in the Suite (the order in which they are listed when you launch the Suite).

Select MIDlets Select the MIDlets that are to be included for the application by checking from the list of MIDlets here. The MIDlets that are not checked, do not have entries in the .jad file, but their class files are packaged in the .jar file.

Compiling the MIDlet Suite

To compile a MIDlet in a MIDlet Suite, right click on the MIDlet node in the Desk and select Compile. To build MIDlet Suites, right click on the MIDlet Suite node in the Desk and select Build from the popup menu.

This builds the entire application under the selected MIDlet Suite. All the compilation messages are displayed in the J2ME Output tab in the Output Panel of Studio.

Selecting a Default Device

If no device to emulate is specified, the Emulator uses the default device, DefaultColorPhone, when a MIDlet is run. To change the default emulated device, click on Tools > J2ME Wireless Tool Kit > Select Default Device from the main menu. The next time a MIDlet is run, it will be emulated on the device chosen.

Preverifying and Packaging the MIDlet Suite

Running the application or exporting the MIDlet Suite to a Web Module, preverifies and packages the MIDlet Suite.

Running the Application

To run the application, right click on the MIDlet Suite to preverify, package, and run the MIDlet Suite. This pops up an Emulator, where the application is executed. All the runtime messages are displayed in the Run-output tab in the Output Panel of Studio.

Setting Emulator Properties

The MIDlet Suite allows you to configure the Emulator device on which the MIDlets are executed. Select Tools > J2ME Wireless Tool Kit > Preferences from the main menu bar. This pops up the Preferences dialog, where the Emulator properties can be set, and click OK.

Exporting MIDlets to Web Modules

MIDlets can be hosted on any J2EE application Server, by packaging them in a WAR. To do this, right click on the MIDlet Suite and select Export to Web Module to export the JAD and the JAR files in the required Web Module.

The Web Module then needs to be deployed before trying to access the JAD file remotely. To launch the Emulator, right click on the JAD file in the Web Module and select Run. This runs the MIDlets by downloading them from the Server.

If the exported JAD files fail to execute, verify whether all the JAD attributes are correct. For example, all the required attributes must be specified and valid.

The JAD and the JAR files that are exported into Web Modules are not editable in Studio. All modifications to be made to these JAD files or the MIDlets must be made in the original MIDlet Suite and re-exported.

Debugging MIDlets

MIDlets may be debugged in Studio using the powerful Debugger. Follow the given steps, and debug MIDlets:

Right click on the MIDlet Suite to be debugged in the Explore Panel and select Debug. This creates a JAR file (it recreates the JAR file, if it exists) and starts the Emulator in the Debug Mode.

This starts the Emulator and waits for the Debugger to connect to it to start debugging.

Start the Debugger by clicking on Debug > Start from the main menu.

Choose Remote Application

IP As 127.0.0.1

and Port Number as 5000

Click OK to start a a remote debugging session. This connects to the Emulator at 5000 port.

Open a MIDlet in the MIDlet Suite and insert a breakpoint in the line, where the execution must stop.

Launch the MIDlet in the Emulator to be debugged.

When the execution reaches the line where the breakpoint has been set, Debugger highlights that line in the Editor, and stops the execution of the MIDlet.

The user may now use the options, Step In, Step Over, or Step Out to continue debugging the MIDlet.

Stopping the Debugger

Changing the debug port number

Open the j2me.props file stored in <install_dir>, and modify the value of the property, j2me.debug.port from 5000 to the new number.

Troubleshooting

If you encounter the error message, Could not create/locate J2me.props file in the Studio Installation directory, create the file manually in the Studio installation directory with the following content. Edit the j2me.home to point to the appropriate location, if required.

Changing the J2ME Wireless Tool Kit installation directory after creating a MIDlet Suite, will cause errors while executing the application. Update the Tool Kit's installation directory (in the Other Options field) in the Build properties dialog.

When you encounter an error where the executable is not found, or the executable name is incorrect, edit the executable name appropriately in the J2ME Tool Kit location dialog.