BMD Blackberry Guides

Understanding BlackBerry Application Files

Once you build your project (using one of the build options under the project menu), the BlackBerry build tools will create a series of files. Some of these files are standard MIDP files, and some are BlackBerry specific.

The JARfile (extension .jar) is the main application file for MIDP. It's the file containing the resources and compiled class files to run on the device. It's a standard Java Archive file with the added requirement that the manifest file (META-INF/MANIFEST.MF in the JAR file) has some special MIDP-specific properties.

The JAD file (extension .jad) is the Java Application Descriptor file, which is used by MIDP's Over-the-Air(OTA) provisioning protocol. It's a Java properties file that contains information about the application to help the device (and user) decide whether to proceed with the download and installation before downloading the JAR file. It gives security-related information such as the permissions the MIDlet requires, and it gives download and installation information such as the size of the JAR file and its location. It also gives information about the application, such as the name, icon, and version as well as the fully qualified name of the MIDlet subclass that the AMS must call to launch the MIDlet. The application properties in the JAD file must match the corresponding properties in the manifest file (in the JAR) exactly; otherwise, the application won't install (for security reasons).

The RAPCfile (extension .rapc) is a helper file used by the BlackBerry JDE and the BlackBerry compile-and-build tool (rapc.exe). It contains many of the same

properties that go in the JAD and manifest files. The BlackBerry JDE creates this file (with your application's properties) and then uses it as input for the rapc. exe build tool, which then writes the properties to the JAD and manifest files. This file is not needed if you're building with Ant (see the ''Building with Multiple Devices for Ant'' section, which follows).

The debug file (extension .debug) and the CSO file (extension .cso) are additional helper files for running the application in the debugger and for digitally signing the application, respectively. You'll use the debug file when optimizing the game and graphics in Chapter 6, and you'll use the CSO file when signing and selling the game in Chapter 5.

The ALXfile (extension .alx) is an XML format descriptor file to help users install your game locally using RIM's desktop management software. The JDE doesn't create this file automatically with every build, but it's one of the menu options you can select. You don't need this file if you're planning to distribute your game entirely over the air (having your customers install your game directly from the Internet to their BlackBerry devices). You only need to create this file if you're planning on using a distribution model where your customers download the application files from your site onto a PC and then load the game from the PC onto the BlackBerry.

The COD file (extension .cod) is the main application file for BlackBerry. This is the file you use when you're installing the application onto the device directly from your PC, and it can also be used when installing the application over the air. It's a proprietary binary format, so you can't just inspect and extract its contents the way you can with a JAR file. You can install your game by loading this file onto your BlackBerry device with the JavaLoader tool (as you'll see in the ''Installing and Distributing Your Game'' section of this chapter), or by creating a corresponding ALX file to use with the desktop management software. COD files have a size limit (64KB maximum in order to install the application over the air), so they're often grouped in a ZIP file, which (confusingly enough) has its extension changed to .cod. (Zipping ''sibling'' COD files together is explained in more detail in Chapter 5.)