Quick Overview of BlackBerry Files
Lets briefly cover the files that you will encounter when creating a BlackBerry application:
- .java - your application's source files.
- .jad - the Java Application Descriptor (JAD).
- .rapc - same as a JAD file, but with BlackBerry-specific entries. In our Ant script, we won't use a .rapc but instead use standard .jad files.
- .jar - Java Archive, which is the standard packaging file format for MIDP 1.0 applications.
- .cod - standard (native) packaging file format that executes on the BlackBerry device.
- .alx - application loader file, used by the Application Loader tool, which is part of the BlackBerry Desktop Software, to load new applications onto the handheld. Use the IDE to generate .alx files for your projects. For more information, see About .alx files.
- .mak - a Makefile as the one in Listing 1.
It is important to emphasize that what gets loaded into BlackBerry handsets are .cod files. If you have a MIDlet, it must first be converted to a .cod package.
The BlackBerry RAPC Compiler
RAPC is the command line compiler that is used to compile .java files into .cod files that are loaded onto the handheld. Figure 2 illustrates the input and outputs of the RAPC compiler:
Figure 2. - Using the RAPC Compiler
Inputs to the RAPC compiler are:
- Source .java files or input JAR file.
- JAD file for the application.
- List of import libraries such as the RIM APIs and dependant 3rd party libraries.
- Codename to use for the application - must match the .jar file name.
- The -midlet flag - optional flag set if building a MIDlet instead of a CLDC application. You also need to properly populate the standard MIDlet-* JAD and MANIFEST attributes
For example, the RAPC compiler's usage is as follows:
rapc.exe import=C:\BlackBerryJDE3.7\lib\net_rim_api.jar codename=MyClientApp MyClientApp.jad MyClientApp.jar
The RAPC compiler generates a .cod file and a modified JAD file with BlackBerry specific entries added to it, such as the size of the .cod file, creation time, signature, and other. Listing 2 shows a JAD file for a BlackBerry CLDC application:
Listing 2. - Sample JAD file for a BlackBerry CLDC Application
Manifest-Version: 1.0 MIDlet-Version: 0.0 MIDlet-Jar-Size: 205354 MicroEdition-Configuration: CLDC-1.0 MIDlet-Jar-URL: MyClientApp.jar MIDlet-Name: MyClientApp MIDlet-1: ,, MicroEdition-Profile: MIDP-1.0 MIDlet-Vendor: J2MEDeveloper.com RIM-COD-Module-Dependencies: net_rim_cldc,net_rim_os RIM-MIDlet-Flags-1: 0 RIM-COD-Module-Name: MyClientApp RIM-COD-Size: 88616 RIM-COD-Creation-Time: 1089855050 RIM-MIDlet-Position-1: 0 RIM-COD-URL: MyClientApp.cod RIM-MIDlet-NameResourceId-1: 0 RIM-COD-SHA1: 89 bd de fe 1d 07 3a 0d 1a 15 23 ea 94 57 c5 fa 0f 2f 1f fe RIM-MIDlet-NameResourceBundle-1:
***Note that BlackBerry JDE and related build tools are only targeted at the Microsoft Windows NT, 2000 and XP environments.
Using Apache Ant for Blackberry Builds
There are plenty of great introductions to Ant, so here we will briefly cover the main concepts. Please refer to the resources section for a list of Ant resources.
Apache Ant is a build tool written in Java. An Ant script is an XML file that defines interdependent build tasks for a project such as "clean directories", "java compile", and "JAR classes". For our Ant scripts we leverage Antenna as much as possible. Antenna is a set of Ant tasks for building wireless Java applications targeted at MIDP; this simplifies many Ant script tasks which otherwise we would have to write ourselves.
Structuring the Project
A proper directory structure for your project will help you maintain your project's files neatly organized. Figure 3 illustrates a project organization that I have found useful; this directory structure is used by the finished Ant script I'll present below:
Figure 3. Our Project Directory Structure
The project's root directory contains the build.xml file as well as other support files such as our JAD and MANIFEST template files - we use these templates to generate our final (properly) populated JAD and MANIFEST files. The rest of our directories are for our compiled classes, build output, the source code, resource files, and support libraries.
