Advanced - Adding JAR Files to a MIDlet Suite
This document provides guidance on how to add external JAR files to a MIDlet Suite project.
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 and, potentially, the "export" setting associated with the jar file. It is therefore important that you:
Adding Hardware JAR files
There are two different ways that hardware JAR files can be added to the system. They can either be added via the Device Management preference page, or they can be added directly to the project, but not exported.
Using Device Definitions to Add Hardware JAR files
Hardware JAR files may be added as a new library from the Device Management preferences page. In many cases, EclipseME is able to extract all the relevant information from your Wireless Toolkit to create the appropriate library definitions. If it does not, you first need to add a new library to a device definition (see here for how to do this). Finally, modify your MIDlet Suite Project's project properties to use the new or updated device 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 Directly To A Project
Prior to release 0.9.4, the method described above was the only method of adding a hardware JAR to EclipseME. Beginning in release 0.9.4 of EclipseME, hardware JAR files may also be added to a project by simply adding them to the "Libraries" tab in the "Java Build Path" portion of the project properties. For example, in the project shown below, the file mmapi.jar has been added to the project.
If you add a JAR file this way, however, it is vitally important that you not have the checkbox next to this item checked on the "Order and Export" page, as shown below:
If this box is checked, EclipseME will attempt to preverify and included the contents of mmapi.jar in the deployed JAR file, which would obviously be wrong.
Which Approach Is Better?
Before release 0.9.4 of EclipseME, you had only one way of adding Hardware JAR files, so things were pretty simple. Starting with release 0.9.4, you have two choices. Which way is better?
The developers of EclipseME feel that, in the vast majority of cases, it is better to use the first approach - using device definitions to add the Hardware JAR files. This approach allows the changes to be reused across projects, and more properly associate the Hardware JAR files with the devices which, after all, describe the hardware to your project. If, for some reason, you cannot follow that approach however, the second course of action - adding the JAR file to the project but not exporting it - is now available to you.
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 from the 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.
Thus, in the example above, we are adding the Application JAR file extensions.jar to the project in addition to the Hardware JAR file mmapi.jar.
Beginning in release 0.9.4 of EclipseME, it is essential that you put a check in the check box next to Applications JAR files in the "Order and Export" tab of the Java Build Path, as shown below:
Once you have done this, the classes in the JAR file or class directory will both be part of your project's build path, as well as deployed in your project's JAR file. Thus, in the example shown, the case above, EclipseME will collect the classes and other resources in extensions.jar, preverify them, and include them as part of your deployed MIDlet. EclipseME will not, however, do this with mmapi.jar, since the checkbox is empty. The resources in mmapi.jar will be available at compile time, but will not be deployed.
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, or have forgotten to check the "export" box.
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.
Copyright © 2005, http://www.eclipseme.org. All rights reserved.