J2ME Wireless Tool Kit Integration

Java 2 Platform, Micro Edition (J2ME) and Java 2 Platform, Enterprise Edition (J2EETM) 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 can use Studio to build, package, execute, and debug J2ME applications, with J2ME Wireless Tool Kit. Studio also provides J2ME based validation and code completion.

The following sections describe how to create MIDP applications using J2ME Wireless Module in Studio.

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

On Windows, execute j2me_wireless_toolkit-1_0_4_01-bin-win.exe. On Linux, execute j2me_wireless_toolkit-1_0_4_01-bin-linuxi386.bin. This starts the Installation Wizard.

Enter the required information 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, read the J2ME Wireless Tool Kit User Guide.

Select Tools > J2ME Wireless Tool Kit > Configure J2ME Tool Kit from the menu bar. This displays the configure dialog.

Browse for the location of the installed Tool Kit. This fills the names for executable properties existing in the Tool Kit, automatically. The executable names can be edited.

MIDP applications, or MIDlets, are packaged into a MIDlet suite. MIDlet suites are a group of MIDlets that share resources at runtime. It includes:

Java Application Descriptor (JAD) file: Contains a predefined set of attributes denoted by names beginning with `MIDlet'. It allows application management software to identify, retrieve, and install MIDlets. All attributes in the JAD file are made available to the MIDlets. It is possible to define application-specific attributes and add them to the JAD file

Java Archive (JAR): This contains:

Java classes for each MIDlet in the suite

Java classes shared between MIDlets

Resource files such as image files used by the MIDlets

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 and select New Folder > MIDlet Suite. Enter the following information in the dialog:

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

The field for location of the MIDlet sources is filled automatically and can be modified as 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.

Creating MIDlets using existing sources

To create a MIDlet with existing source files, right click on the desk root and select New Folder > MIDlet Suite. Enter the following information in the dialog:

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

The field for location of the MIDlet sources is filled automatically and can be modified as required. The JAD and JAR files are stored under this directory. The Class Directory field is automatically filled and can be modified.

Select the option `Use Existing Sources'.

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

Browse and select the appropriate .jad file if the `JAD location' field is not filled, automatically.

MIDP applications are also known as MIDlets. 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, select MIDlet and click OK.

In the MIDlet dialog, 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 Default MIDlet or MIDlet to Servlet.

Click OK to create the MIDlet under the selected source root, and opens the file in the Display Panel.

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 should be imported in the same way.

Customizing MIDlet suite properties

Studio allows the user to customize the MIDlet suite properties. The 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 JAD file

To customize the attributes, right click on the MIDlet suite and select MIDlet Suite Attributes.

Required: Contains all mandatory fields for the MIDlet. The values of these attributes can be edited after selection

Optional: Enter all the optional values of the MIDlet properties

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 Remove

MIDlets: Enter all MIDlet specific values. Use the Move Up and Move Down buttons to change the order in which the MIDlets are listed when the suite is launched

Select MIDlets: Select the MIDlets from the list to include in the application. The MIDlets that are not selected, do not have entries in the JAD file, but the class files are packaged in the JAR file

Compiling a MIDlet suite

To compile a MIDlet in a MIDlet suite, right click on the MIDlet node and select Compile. To build MIDlet suites, right click on the MIDlet suite node and select Build. This builds the entire appli cation 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 for the MIDlet

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

Verifying and packaging the MIDlet suite

Running the application or exporting the MIDlet Suite to a web module, verifies and packages the MIDlet Suite.

Running the application

To run the application, right click on the MIDlet suite to verify, package, and run the MIDlet suite. The Emulator appears, where the application is executed. All the runtime messages are displayed in the Run tab in the output panel.

Configuring 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. In the Preferences dialog, set the Emulator properties and click OK.

Exporting MIDlets to web modules

MIDlets can be hosted on any J2EE application server by packaging them in a WAR. Right click on the MIDlet suite and select Export to Web Module to export the JAD and the JAR files to the required web module. The web module should 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 downloads the MIDlets from the Server and runs them.

If the exported JAD files fail to execute, verify if all JAD attributes are correct. For example, all specified attributes should be valid. The JAD and the JAR files that are exported into web modules are not editable in Studio. All modifications to the JAD files or the MIDlets should be made in the original MIDlet suite and exported.

Debugging MIDlets

Right click on the MIDlet suite and select Debug. This creates a JAR file and starts the Emulator in the Debug Mode.

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

To start the Debugger, select Debug > Debug from the main menu. Choose Remote Application option. Enter IP as 127.0.0.1 and Port Number as 5000. 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.

To debug, launch the MIDlet in the Emulator. 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 options, Step In, Step Over, or Step Out can be used 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 to the new number.

If the error message `Could not create/locate J2me.props file in the Studio Installation directory' is encountered, create the file manually in the Studio installation directory with the following content.

#Take a backup before editing this file manually 
#Mon Oct 07 12:15:11 IST 2002 
j2me.preverify=bin\\preverify.exe 
j2me.defaultdevice=bin\\DefaultDevicew.exe 
MicroEdition-Configuration=CLDC-1.0 
j2me.home=D\:\\WTK104 
MIDlet-Version=1.0.0 
j2me.utilities=bin\\utilsw.exe 
MIDlet-Vendor=Company Name 
MicroEdition-Profile=MIDP-1.0 
j2me.Emulator=bin\\Emulatorw.exe 
j2me.preferences=bin\\prefsw.exe 
j2me.debug.port=5000 
Edit the j2me.home to point to the appropriate location, if required.

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

If the executable is not found, or the executable name is incorrect, edit the executable name appropriately in the J2ME Tool Kit Location field in the dialog.