Advanced - Adding JAR Files to a MIDlet Suite

This document provides guidance on how to add external JAR files to a MIDlet Suite project.

  1. Types of JAR Files
  2. Adding Hardware JAR files
  3. Adding Application JAR files
  4. Emulator Caveats

Types of JAR Files

From the point of view of a J2ME project, there are two general categories of JAR files that might be added to a MIDlet Suite project. It is very important that you understand the distinction between the two, since they have to be added differently to get the result you want. The two categories are:

The reason for the distinction has to do with what EclipseME needs to do with the classes in the JAR file. For Hardware JAR files, EclipseME needs ensure that the classes in the file are part of your classpath during the build process so that your MIDlet will compile properly, however these classes must not be packaged up as part of your deployed MIDlet. To do so would be to attempt to override classes that are already implemented in the mobile device. This would probably not work, in the first place, since many of these classes have native code hooks which cannot be used from inside the "sandbox" in which a MIDlet runs. In the second place, a MIDlet that contains native hooks should fail the mandatory preverification step that is part of the deployment process. Finally, even if that didn't happen, no self-respecting MIDlet container should allow a MIDlet to override system classes - it should reject the MIDlet as being invalid.

For Application JAR files, on the other hand, EclipseME needs to extract all the classes, resources, etc., combine them together with the corresponding items in the MIDlet suite project, and put them all into the resulting deployable JAR file. J2ME devices do not have the concept of a classpath the way that J2SE and J2EE systems do. A J2ME suite consists of only two files - a JAR file and a JAD file. Every class or resource that your MIDlet will access must therefore be bundled together into the single JAR file.

EclipseME distinguishes between the two categories of JAR files based on the way that you add the file to the system. It is therefore important that you:

  1. determine the correct category for the JAR file and then
  2. add it to the system in the correct manner.

Adding Hardware JAR files

Hardware JAR files must be added to a profile in the Platform Components preferences page. In many cases, EclipseME is able to extract all the relevant information from your Wireless Toolkit to create the appropriate profiles and platform definitions. If it does not, you first need to create a new profile and add the JAR file to the profile (see here for how to do this). Then, either create a new Platform Definition that includes the profile, or update an existing Platform Definition to include it. (see here for how to do this) Finally, modify your MIDlet Suite Project's project properties to use the new or updated Platform Definition. (see here)

Once this is done, the JAR file will be included in your project's build path, so that the compiler will find the relevant class definitions, however EclipseME will not attempt to include these classes in your deployed JAR file - as far as EclipseME is concerned, this JAR file is now part of the Wireless Toolkit, and is there for reference purposes only.

If, when you try to run your MIDlet in the emulator, particularly in OTA mode, you get complaints about illegal classes, this may be a sign that you have incorrectly added a Hardware JAR to the system as if it were an Application JAR.

Adding Application JAR files

Application JAR files must be added to your project's build path just the way you would with JAR files in any non-J2ME project. Select Properties from the Project menu, click on the Java Build Path item in the left-hand pane, and then add the JAR files (or class directories) to the list in the right-hand portion of the dialog box.

Once you have done this, the classes in the JAR file or class directory will also be part of your project's build path. Unlike the case above, however, EclipseME will collect these classes, preverify them, and include them as part of your deployed MIDlet.

If, when you try to run your MIDlet in the emulator, particularly in OTA mode, you get a ClassNotFoundException, this is a signal that the relevant classes did not get bundled into your deployed JAR file. This is usually a sign that you have not added the Application JAR file to your project's Java Build Path properly.

Emulator Caveats

If you are using a special feature, such as Bluetooth, video, etc., you may run into a situation in which you correctly add the hardware JAR as specified above, your application compiles perfectly, but then when you run it in the emulator, the hardware device does not seem to function.

In all likelihood, this is not an EclipseME issue - it is most likely an issue with the J2ME emulator. In many circumstances the emulator in a Wireless Toolkit has just enough support for a hardware feature to allow your MIDlet to load, but doesn't contain truly functional emulation for all the hardware features of the physical device itself. Unfortunately, there is nothing we can do to help you with this.