Guide to getting started in J2ME for the Motorola v3x phone

This guide will take you through setting up a build environment for J2ME in Windows and in writing a few sample applications for the v3x phone. There are some notes at the end if you are on another platform, but we strongly recommend using a Windows environment so that you can make full use of the simulator and debug output.
  1. Setting up Eclipse

    We recommend using Eclipse for your Java editing. If you're not familiar with Eclipse, you can get more information here: http://www.eclipse.org/

    The latest version of Eclipse can be downloaded here: http://www.eclipse.org/downloads/download.php?file=/eclipse/downloads/drops/R-3.2.1-200609210945/eclipse-SDK-3.2.1-win32.zip

  2. Setting up the Motorola J2ME SDK

    Next, you'll need to set up the Motorola SDK. You will first need to create an account on the Motdev website: http://developer.motorola.com/membership/join/

    Then download the latest SDK for Motorola OS phones from: http://developer.motorola.com/docstools/sdks/motorola63

    Unzip the SDK and install from the windows installer. Keep the eclipseme zip fild handy for the next step.

  3. Setting up EclipseME J2ME Plugin

    Next, you need to set up the J2ME plugin that will tie the Motorola SDK into the Eclipse environment.

    Open Eclipse and choose Help...Software Updates...Find and Install

    Choose "Search for new Features to Install"

    Choose "New Acrhived Site" and point it to the eclipse me zip file from the sdk download. Make sure the checkbox is checked and finish installing the plugin.

    Next, you'll need to point eclipse to the Motorola SDK. Go to Window...Preferences and select "Device Management" under J2ME. Click on "Import..." and browse to the directory where the SDK was installed ("C:\Program Files\Motorola\Motorola Java ME SDK v6.3 for Motorola OS Products\" if you chose the default installation). You can choose to just import the v3x emulator, or you can import them all to see how your application will look on different devices.

  4. Creating a simple J2ME application

    Here's a basic runthrough on how to create a simple J2ME application, basically a J2ME hello world.

    1. Create a new J2ME MIDlet Suite project: http://eclipseme.org/docs/createProject.html When doing so, be sure to set the target device to the RAZR v3x.
    2. Create a new Midlet in the project named "HelloWorld" A midlet is a J2ME application and represents the main UI class for a project. http://eclipseme.org/docs/createMidlet.html
    3. You can use the following source for the midlet: Helloworld.java
    4. You can debug and install using the installation instructions below.
  5. Debugging J2ME applications in the simulator

    This section will cover debugging and the use of the simulator in conjunction with Eclipse. It is recommended that you try to run applications in the emulator before trying to run them on the phone, however some funcationality cannot be emulated.
    1. Choose Run... from the Run menu of ecipse.
    2. Under Configurations, double click on the header Wireless Tookit Emulator to create a new configuration. The project name should be auto-populated with your current project. Under "Executable: Midlet" enter the name of your Midlet.
    3. Click on Run to start the Midlet in the emulator.
    To debug instead of run, complete the same setup under "debug..."
  6. Installing the application on the phone

    There are two files needed to install your J2ME application on the phone. One is the jar file which contains all of your compiled java code. The other is the jad file while contains metadata about your application and permissions information. Both of these are generated by Eclipse. To make sure they have been updated properly before loading them onto the phone, right click on your project name in the Package Explorer and select "J2ME" "Create Package" from the context menu. This will force a regeneration of the jar and jad file in the deployed folder for your project.

    Make sure your device is in USB Modem Mode before continuing. Then go to Settings, Java Settings on your device and choose Java Application Loader. Once the phone says to plug it into your computer, do so. If your system prompts you for a driver, you can download the Motorola Windows USB Drivers here. Next, you'll need to find the COM port that your phone attached to. To do this, go to the Windows Device Manager and look under Modems for the Motorola USB Modem. Under Properties, Advanced there will be a button to see the COM port setting. Remember this (or better yet, write it down as it will be the same as long as you plug your phone into the same USB port). Then open the Motorola MIDway application and set the port number to the one you wrote down. In MIDway, choose your JAD file and download it to the phone. If all goes well, the application should install and you can run it on the device.

    In order to debug your application on the device, keep MIDway running and click on the Debug tab. You'll be able to see your own println's as well as the printf's from the J2ME virtual machine. Note that if you print the stack trace of an exception, you'll only get the method name and exception type, but this is better than nothing.

  7. A word about permissions

    When you use various "protected" classes in J2ME, you need to make sure you set the permissions in your JAD file appropriately. You can do this by clicking on the JAD file in your main project (not the one in "deployed") and going to the "optional" tab. Under "Midlet Permissions:" add the appropriate permissions comma separated. Note that for some of these, you'll need to sign your application as well. The signing process is covered under the Motorola NDA, and you can receive the certificate and additional instructions in class.

    The following are common permissions:

  8. Example code:

    1. HTTP Download:

      StringBuffer s = new StringBuffer();
      HttpConnection c = (HttpConnection)Connector.open("http://web.mit.edu/index.html");
      InputStream is = c.openInputStream();
      byte b;
      while ((b = (byte)is.read()) != -1) {
          s.append((char)b);
      }
      is.close();
      c.close();

      Permissions needed: javax.microedition.io.Connector.http

    2. Writing to a file:

      FileConnection sc = (FileConnection)Connector.open("file:///c/mobile/picture/tmp.txt");
      OutputStream os = sc.openOutputStream();
      os.write(("text to go into the file").getBytes());
      os.flush();
      os.close();

      Permissions needed: com.motorola.file.writeaccess and signing

    3. Reading a file:

      FileConnection sc = (FileConnection)Connector.open("file:///c/mobile/picture/tmp.txt");
      InputStream is = sc.openInputStream();
      StringBuffer sofar = new StringBuffer();
      byte c;
      while ((c = (byte)is.read()) != -1){
          sofar.append((char)c);
      }
      is.close();

      Permissions needed: com.motorola.file.readaccess and signing

    4. Sending an SMS:

      sender = (MessageConnection)Connector.open("sms://");
      TextMessage t = (TextMessage)sender.newMessage(MessageConnection.TEXT_MESSAGE);
      t.setPayloadText(message);
      t.setAddress("sms://" + contactNumber);
      sender.send(t);

      Permissions needed: javax.wireless.messaging.sms.send

    5. Getting Cell ID (cid, lac, mcc, mnc combine to form globally unique id):

      String cellID = System.getProperty("CellID");
      String lac = System.getProperty("LocAreaCode");
      String imsi = System.getProperty("IMSI");
      String mcc = imsi.substring(0,3);
      String mnc = imsi.substring(3,6);

      Permissions needed: none, signing

    6. Placing a phone call:

      Dialer dialer = Dialer.getDefaultDialer();
      dialer.startCall("6172531000");

      Permissions needed: com.motorola.phone, signing

  9. Helper classes

    The following helper classes implement common features of standard desktop java that you might find useful to use in J2ME:
  10. J2ME developing on Linux/Mac

    While the Motorola emulator only runs on Windows, you should be able to code J2ME apps on other platforms. You can use the following Jar files that contain the J2ME platform for the v3x. Note that you must turn off compiling against the default JDK as most Java classes are not included in J2ME. If you end up going around and would like to share your insights, consider creating a web page or wiki to document the hurdles.
  11. More complete references