| John M. Wargo
Published by Addison-Wesley Professional
ISBN-10: 0-321-64742-4
ISBN-13: 978-0-321-64742-9 |
This chapter provides the information developers need when beginning a BlackBerry Java development project and trying to select the right development tools to use. This chapter includes information on how to download and install the RIM’s Java development tools. Chapter topics are
- Understanding the BlackBerry Java Application files
- Selecting the right development platform for Java applications
- Installing the BlackBerry Java development tools
- Obtaining and installing the application signing keys needed to run applications that use controlled application programming interfaces (APIs) on BlackBerry devices
- Using the Preprocessor to generate different versions of an application from a single set of source files
After the Java development platform is selected and the tools are installed, the chapters that follow describe how to use the individual development tools to build and debug Java applications for BlackBerry:
- Chapter 13, “Using the BlackBerry Java Development Environment (JDE),” covers the BlackBerry JDE.
- Chapter 14, “Using the BlackBerry JDE Plug-In for Eclipse (eJDE),” covers the BlackBerry eJDE.
- Chapter 15, “Using the BlackBerry JDE Component Package Tools,” covers the BlackBerry JDE Component Package.
12.1 Understanding BlackBerry Java Application Files
The BlackBerry platform uses several types of files to contain application code and provide application deployment tools with the information they need about the application and its components. Developers must understand the role of each to be able to effectively build and deploy applications. The following sections describe each of the file types. Other files are used by development tools, but the files discussed here are only the ones deployed to devices or used when deploying applications to devices.
12.1.1 .cod Files
A BlackBerry .cod file is the compiled application file deployed to BlackBerry devices. The .cod file bundles together one or more compiled Java classes for use with the BlackBerry Java virtual machine. Unlike standard Java, which compiles individual Java classes into class files (with a .class extension) and aggregates compiled classes into JAR files (Java ARchives with a .jar extension), RIM uses this proprietary file format instead because it is optimized for the BlackBerry platform.
Each singleton .cod file contains one or more compiled Java classes (and is, therefore, roughly equivalent to the standard Java JAR file); however, it has a strict size limit of 64k of code and 64k of data. A sibling .cod file is an archive of multiple, separately built .cod files that help alleviate the size limit restriction of singleton .cod files. When an application approaches the .cod file size limit, a portion of the functionality of the application must be migrated off into separate modules (library projects in the JDE and eJDE), which are packaged by the development tools into a sibling .cod file for deployment.
A MIDlet application created for another platform (a .jar file) can be easily converted into a .cod file for deployment to a BlackBerry device; see the BlackBerry Developer’s knowledge base article DB-00055 for additional information about this topic.
12.1.2 .alx Files
An application’s .alx file is used by the BlackBerry Application Loader (through the BlackBerry desktop manager or the BlackBerry Enterprise Server), which is described in Chapter 16, “Deploying Java Applications,” to deploy application .cod files to a BlackBerry device. The .alx file is a simple text file that
- Can be hand crafted (not really necessary, see next bullet)
- Is automatically generated by the BlackBerry JDE and eJDE
- Can reference multiple versions of an application (for deployment to different BlackBerry Device Software versions), device types, and capabilities
The file is in XML format and contains the information that the Application Loader needs to
- Describe the application (in dialogs displayed to users during installation and in the installed applications list on the BlackBerry device)
- Determine if the application is compatible with the target device
- Understand which files need to be deployed with the application (depending on BlackBerry Device Software version)
A portion of the application information defined in the file is populated from developer-entered application properties (application name, version, vendor, and copyright) defined in the JDE and eJDE. A developer generates or updates the .alx file and makes it available (along with the application .cod files) to anyone who will deploy the application using the BlackBerry Application Loader. The options for deploying BlackBerry Java applications are described in detail in Chapter 16.
A simple .alx file for the URL Launch application (described in Chapter 11, “Building BlackBerry Java Applications”) is shown here:
<loader version="1.0">
<application id="URLLaunch">
<name >
URL Launch
</name>
<description>
Launches the default browser and opens
www.bbdevfundamentals.com
</description>
<version >
1.0
</version>
<vendor >
BlackBerry Development Fundamentals
</vendor>
<copyright >
Copyright 2009 com.bbdevfundamentals
</copyright>
<fileset Java="1.39">
<directory >
</directory>
<files >
URLLaunch.cod
</files>
</fileset>
</application>
</loader>
A more sophisticated .alx file, one that deploys a different .cod file depending on the BlackBerry Device Software version the target device is running, is shown here. Notice how it uses the fileset element’s _blackberryVersion attribute and the <directory> element to point to the correct version of the application .cod file for the target device:
<loader version="1.0">
<application id="URLLaunch">
<name >
URL Launch
</name>
<description>
Launches the default browser and opens
www.bbdevfundamentals.com
</description>
<version >
1.0
</version>
<vendor >
BlackBerry Development Fundamentals
</vendor>
<copyright >
Copyright 2009 com.bbdevfundamentals
</copyright>
<fileset Java="1.34" _blackberryVersion="[4.1.0,4.2.3)">
<directory>410_423</directory>
<files>urllaunch.cod</files>
</fileset>
<fileset Java="1.34" _blackberryVersion="(4.3.0,4.3.1]">
<directory>430_431</directory>
<files> urllaunch.cod</files>
</fileset>
</application>
</loader>
See the BlackBerry Developer’s knowledge base article, “How To: Create a Single .alx File to Install Multiple Versions of an Application” (Article #DB-00028) for information on the more sophisticated options for the BlackBerry .alx file.
12.1.3 .jad Files
The .jad file is a simple text file used by the BlackBerry Application Web Loader, BlackBerry browser, and BlackBerry App World when deploying BlackBerry applications to a device (described in Chapter 16). The file can be hand crafted, but that’s not necessary because it is automatically generated by the BlackBerry JDE and eJDE whenever a BlackBerry Java development project is built. It contains information needed to verify the application files during deployment and other specifics about the application. A developer might generate or update the .jad file and make it available (along with the application’s .cod files) to anyone who will deploy the application using the listed tools. The options for deploying BlackBerry Java applications are described in Chapter 16.
A sample .jad file for the URL Launch application described in Chapter 11 is shown here. The line numbers are not part of the file; they have been added to make these descriptions easier to follow.
Line 3 defines the specific modules required by the application. The application will not deploy to a device if the required modules are not available.
Line 9 contains a Secure Hash Algorithm (SHA1) hash of the application’s .cod file that verifies the integrity of the .cod file.
Line 10 contains the .cod file size parameter; this value can be updated using the UpdateJad.exe file described in Chapter 15.
Lines 12 through 14 represent the application project’s properties (version, name, and vendor) populated in the JDE or eJDE.
1 Manifest-Version: 1.0
2 RIM-COD-Module-Name: URLLaunch
3 RIM-COD-Module-Dependencies: net_rim_cldc,net_rim_bbapi_
browser
4 MIDlet-Jar-Size: 2832
5 MIDlet-1: ,,
6 RIM-COD-Creation-Time: 1242820557
7 MIDlet-Jar-URL: URLLaunch.jar
8 RIM-COD-URL: URLLaunch.cod
9 RIM-COD-SHA1: e1 c2 7b bc 14 0c 63 cc 43 80 bf b2 1e 47 a1 77
c9 08 95 7b
10 RIM-COD-Size: 1084
11 MicroEdition-Configuration: CLDC-1.1
12 MIDlet-Version: 1.0
13 MIDlet-Name: URLLaunch
14 MIDlet-Vendor: BlackBerry Development Fundamentals
15 MicroEdition-Profile: MIDP-2.0
16 RIM-MIDlet-Flags-1: 0
12.2 Selecting the Right Development Platform for Java Applications
Before digging into the development tools, it’s important to talk about which development platform to select when building an application. Subsequent chapters cover the ins and outs of the different tools, but what most developers miss is which BlackBerry environment to start with when building their applications.
The features a BlackBerry application can leverage on a device vary greatly, depending on the version of the BlackBerry Device Software running on it. When RIM adds new features to a device, it usually adds a corresponding set of APIs a developer can use to take advantage of them. Any applications that make use of particular features (and corresponding APIs) will only run on a device that supports the feature. Everything is forward compatible, so the feature will be available in future versions of the BlackBerry Device Software; you wouldn’t want the application breaking on a newer device. A BlackBerry Java application is tied to the minimum BlackBerry Device Software version for which it was created; it will not run on a device running any previous version of the BlackBerry Device Software.
When RIM releases a new version of the BlackBerry Device Software, the API libraries included with the corresponding version of the BlackBerry Java development tools are updated. This update also affects the online help and the code-completion capabilities in an Integrated Development Environment (IDE), the device simulators, and more.
Note - You might actually get your application to run on an earlier version of the BlackBerry Device Software, but it probably won’t. If it does work, don’t get complacent; just because it works doesn’t mean there won’t be other problems later. Running an application crafted for a particular BlackBerry Device Software version on an earlier version is not supported and should not be attempted. Doing so could “brick” the device—make the device permanently unusable.
Because each version of the BlackBerry Device Software has its own special version of the development tools, if you are developing applications for multiple BlackBerry Device Software versions, you have to install multiple versions of the tools.
12.3 Selecting the BlackBerry Java Development Environment
The BlackBerry Java development tools provide a complete set of APIs and tools that developers can use to develop Java applications that run on BlackBerry devices. RIM offers different development tools for Java developers, and the good news is that all of them are free. The only exception to this is the cost an organization incurs when purchasing a set of signing keys, as described later in this chapter.
Three types of Java development tools are available from the BlackBerry Developer’s website (http://www.blackberry.com/developers). The one you select will vary, depending on your preference for IDE. The available options are
- BlackBerry Java Development Environment (JDE): A complete Java development environment for BlackBerry. Although not sophisticated as IDEs go, it is the tool RIM developers used for years to build the BlackBerry Device Software and associated applications. Developers might select this option if they didn’t care which IDE they used to build BlackBerry applications or if they wanted to keep all BlackBerry development segregated to a separate development environment.
- BlackBerry JDE Plug-in for Eclipse (eJDE): Provides the same functionality as the JDE, but the tools are integrated as a plug-in to the Eclipse IDE. The benefit of this toolset is that developers get the development tools provided by the JDE along with all the other sophisticated features and plug-ins supported by the Eclipse platform. Developers might select this option if they were already familiar with Eclipse or if they were doing other types of development and wanted to use the same IDE for all. This is the development tool that RIM currently recommends developers use for Java development for the BlackBerry platform. Going forward, feature enhancements will only be made in the eJDE.
- BlackBerry JDE Component Package: A collection of the tools developers need when developing BlackBerry Java applications using a different IDE than the ones listed in the previous bullets. Developers might select this option if they were already familiar with another development environment and were unwilling or unable, for whatever reason, to switch to one of the integrated BlackBerry tools.
The tools are also useful to developers who want to build automated processes for building or manipulating applications outside of an IDE.
Each tool is described in subsequent chapters.
12.4 Getting the BlackBerry Java Development Tools
When you are ready to download some BlackBerry development tools, open a browser and navigate to http://www.blackberry.com/developers. The site might change by the time you read this, so look for a section called Java Application Development Tools & Downloads and click the downloads link, as shown in Figure
12.1. When the page opens, look for a section on Java Development Tools. There should be a link for downloading the BlackBerry JDE and the BlackBerry JDE plug-in for Eclipse. The link for the BlackBerry JDE should also contain links to download the BlackBerry JDE Component Package.
Figure 12.1 BlackBerry Development Tools & Downloads page
Depending on your selection, a different set of options appears. Pay special attention to the system requirements for each tool. Each requires that a version of the Sun Java Development Kit be installed on the system running the BlackBerry Java development tools.
12.4.1 Downloading and Installing the BlackBerry JDE or JDE Component Package
When downloading the JDE or BlackBerry JDE Component Package, scroll down the page until you locate a section of the page containing the links to download the specific versions of the tools. Select the appropriate downloads for your particular needs. If you’re building applications for multiple BlackBerry Device Software versions, you need to download an installer for each version you will be using. If you’re building for a single version or running a single application on multiple BlackBerry Device Software versions, you need to download the version that corresponds to the lowest BlackBerry Device Software version you will support.
To install the JDE or JDE Component Package, first make sure that a copy of the required Java SDK is installed on the system and launch the file you downloaded from the website. Follow the prompts to complete the installation, and you’ll be ready to go. Depending on your Windows configuration, you might have to add the JDK bin folder to the Windows PATH environment variable before you can launch the development tools.
Note - The BlackBerry MDS simulator is required to test BlackBerry applications (using the device simulators) that make use of network connections to access a remote server. For some reason, the 4.2 and 4.2.1 JDE did not ship with the MDS simulator (all other versions since 4.1 did). If you exclusively work with either of those versions of the JDE, be sure to download and install the MDS simulator and then configure the affected JDE to use it.
If working in conjunction with
other JDE versions, the 4.2 and
4.2.1 JDE can be configured to
use the MDS simulator included
within one of the other JDEs.
12.4.2 Downloading and Installing the BlackBerry JDE Plug-In for Eclipse
When downloading the BlackBerry JDE Plug-In for Eclipse, a different set of options appears on the downloads page. In this case, a full installer includes the editor components and associated files plus one of the eJDE Component Packs (version 4.5, at the time of this writing), which contain the libraries and simulators for a particular version of the BlackBerry Device Software. At a minimum, you must download the full installation; you won’t be able to develop BlackBerry applications in Eclipse if you don’t. If you need to support building or maintaining applications for additional BlackBerry Device Software versions, you will likely want to download additional eJDE Component Packages (one for each version of the BlackBerry Device Software being supported).
Note - Because the eJDE components are installed as plug-ins to Eclipse, the Eclipse IDE must be installed in advance of the eJDE installation. You can download the latest version of Eclipse from http://www.eclipse.org.
The first step in the installation process is to install the BlackBerry Java development tools into the Eclipse IDE. Extract the eJDE full-installation package zip file to a local hard-drive folder; it doesn’t matter where the files are placed, as long as the Eclipse installation has access to them. After the files are extracted, launch the Eclipse IDE and complete the following steps:
- With the program open, access the Help menu and select the menu item labeled Software Updates.
- In the window that appears, select the Available Software tab and click the Add Site button.
- In the Add Site dialog, click the Local button.
- Using the standard Windows Open Folder dialog that appears, navigate to the folder where the installation files were extracted and open the folder.
- Back at the Add Site dialog, click the OK button to continue.
- Back at the Software Updates and Add-Ons window, ensure that the BlackBerry JDE Plug-In for Eclipse and BlackBerry Component Pack options are selected and then click the Install button. Eclipse prompts you to confirm the installation and finish the process, ultimately recommending that the IDE be restarted before continuing. At this point, the eJDE is installed and ready for use.
If you downloaded additional component packages, repeat the process for each of the additional component packages you want to use with this instance of Eclipse.
North American users can use the BlackBerry Eclipse update site to download and install component packages directly into an existing Eclipse installation. To do this, open the Software Updates and Add-Ons window and click the Add Site button. Instead of clicking Local to add a local reference, enter http://www.blackberry.com/go/eclipseUpdate in the Location field and click OK. Eclipse connects to the BlackBerry Eclipse Update site and retrieves a list of the components available for installation, as shown in Figure
12.2. Select the component that you want to install and click the Install button to download and install the selected component(s).
Figure 12.2 Completing the Component Package installation
12.5 Application Signing Keys
Chances are that most developer will find themselves needing to use one of the controlled APIs described in Chapter 11. Subsequent chapters show how to sign an application in the different Java development tools, but now, it seems to be a good time to discuss how to get a copy of the signing keys needed to sign an application.
BlackBerry applications that use controlled APIs do not run on BlackBerry devices until they are signed with the appropriate keys. The applications run in the BlackBerry simulators, so it is possible to build and test applications without the appropriate keys. This allows a developer to do all the work necessary to determine the best way to implement a programmatic feature and only purchase the keys if a controlled API is used and it’s time to test on real devices.
Depending on the types of controlled APIs your application uses, you might need different sets of keys. Most controlled APIs can be used with the standard set of keys, which can be purchased for $20 from RIM directly. If your applications use any of the Certicom cryptography APIs, there is a separate process to secure a license from them. Considering that RIM recently completed a purchase of Certicom, it’s likely that this restriction will disappear in the future.
Here are some important facts about signing keys:
- The keys must be installed on a system that has one of the BlackBerry Java Development tools installed.
- Each set of signing keys is associated with a specific PC. If you want to sign applications on multiple PCs, you must purchase a set of signing keys for each PC that will be used to sign applications. Some organizations set up a single signing PC and do all of their application signing on that PC. Other organizations purchase a set of keys for every developer workstation.
- Be prepared to associate a ten-digit personal identification number (PIN) with your signing key purchase. The PIN is needed when the keys are installed, so be sure to record it accurately and keep it in a safe place. This is not a device PIN; it’s just a special key you create to identify yourself to RIM when you purchase keys, then again later when you register them after the order is processed.
- If you lose your keys or need to install them on a different PC, you must contact RIM Developer Support (devsupport@rim.com) to request a new set of keys.
- When you purchase a set of keys, you do not have to pay for each application you sign. They keys are configured to support a large number of signings (millions), so you should be OK.
- Keys are valid forever.
- The registered owner of the signing keys receives email messages from the RIM Signing Authority whenever the keys have been used. An email message will be sent for each type of library used in the application. The emails are sent for security purposes, so the owner of the keys will know if someone uses the keys to sign an application. Make sure the registered owner is someone who doesn’t mind receiving a lot of emails. He can always use email filters to automatically redirect these messages to a folder or delete them automatically when they arrive.
Concerns About Signing Keys - One of the first questions most developers ask about the signing keys is, “Do I have to purchase a set of keys for each application I sign?” If you think about it, that would be a rather cumbersome process if it were true. No, you purchase one set of keys per PC, and you can sign as many applications as you want.
Actually, that’s not true; there is a limit on the number of signings you can do, but it’s such a huge number that you should be OK no matter what you do. In the set of keys installed to take the screen captures used in this chapter, the Signing Tool reports, “The client has 2,147,483,647 code signing request(s) left.” That’s more than enough signings for the normal developer’s lifetime.
12.5.1 Purchasing Signing Keys
To purchase a set of signing keys, open the Microsoft Internet Explorer web browser and go to http://www.blackberry.com/developers. On the page that appears, navigate to the area of the site responsible for Java Development and look in the right-side navigation for an item labeled Code Signing Keys. When you click the link, a page opens where you can find information about the signing keys and how to purchase a set. You can use a web-based form and your credit card to purchase directly online or you can fill out a form and fax the information to RIM for processing.
Signing Keys Payment Options - When purchasing a set of signing keys, the keys must be purchased using a credit card. Because the keys are used partially for security purposes, RIM must ensure that it knows the identity of the entity requesting them.
If a set of keys were used to create an application considered dangerous or to be used for nefarious purposes, RIM wants to associate those keys with a person (name and billing address).
After you complete the purchase of the keys, it might take one to three business days to receive the signing keys from RIM. If you do not receive your keys within this timeframe, email devsupport@rim.com to request a status of the order. After RIM processes the order, you receive at least three separate email messages from the BlackBerry Application Development Support Team. The emails each contain a file attachment (a .csi file) and instructions on how to complete the installation of the keys.
12.5.2 Installing Signing Keys
Before installing the keys, make sure at least one of the BlackBerry Java development tools is installed on the PC where the keys will be installed. The installation process varies, depending on whether you are installing the keys into the JDE or into the eJDE. Additionally, if you will work with multiple versions of the JDE or JDE Component Package, or if you will be working with the JDE and the eJDE, an additional configuration step must be completed to make the signing keys available across multiple tools. All this is described in the following sections.
Installing Signing Keys into the JDE
To install the keys into the JDE, each key file must be launched individually to integrate the keys into the BlackBerry Java development tools. The key files can be launched directly from the email messages containing each key, or each file can be downloaded from a message and launched from Windows Explorer or My Computer.
When a key file launches, the BlackBerry Signature Tool opens and manages the process of installing the keys, which is described in the section, “Completing the Signing Key Installation.” This process must be repeated for each signature key .csi file.
If you launch a .csi file and nothing happens, first ensure that a Java runtime environment and one of the BlackBerry JDE versions is installed on the system. In some cases, the Signing Tool will not launch automatically when the .csi files are launched. In that case, you need to register each .csi file manually from the command line. To start the manual installation, follow these steps:
- Copy the .csi files to the JDE bin folder. (For the 4.7 JDE, the folder location should be C:\Program Files\Research In Motion\BlackBerry JDE 4.7.0\bin.)
- Open a DOS command prompt in Windows and navigate to the folder containing the .csi files.
- For each of the .csi files, execute the following command:
javaw -jar SignatureTool.jar [CSI_File_Name].csi
In this command, [CSI_FILE_NAME] refers to the filename for the .csi file.
At this point, follow the steps described in the section, “Completing the Signing Key Installation.”
Installing Signing Keys into the eJDE
With the eJDE, the signature key file installation is integrated directly into Eclipse tools. To begin the process, access the BlackBerry menu in Eclipse, select the Install Signature Keys menu item, and follow the steps described next.
Completing the Signing Key Installation
When the first key installs, there are additional setup steps required to complete the process. The Signature Tool displays a dialog similar to the one shown in Figure
12.3, which indicates that the private key used to secure the signature keys cannot be located within the BlackBerry Java Tools installation. You must select Yes from the dialog to complete the installation, unless you believe this process has already been configured and you received the message in error. If you select No from the dialog, the installation process aborts.
Figure 12.3 BlackBerry Signing Tool private key dialog
The Signature Tool then asks
you to provide a password that
will protect access to the signing
keys on the PC, as shown in Figure 12.4. The password entered
here is needed every time an application
is signed using the keys. Select
a password that is easy to remember
when needed. If the password is
lost, you need to obtain a new
set of signature keys from RIM
before you can sign Java applications.
A replacement set of keys should
be free; just send an email to
devsupport@rim.com to request a
replacement set.
Figure 12.4 BlackBerry Signing Tool private key password
The private key is generated using information generated through random mouse movement and keyboard entry, as shown in Figure
12.5. Move the mouse around and type random keys on the keyboard until the progress bar reaches 100 percent. At this point, the information the Signature Tool needs to manage and secure the signing keys has been generated, and you will not be prompted to complete the process again for the PC.
Figure 12.5 Generating random information for the private key
Because the signing keys are restricted to a single PC, the installation process includes a step where the key installation is registered with RIM.
The next step in the process must be repeated for each signing key. The Signing Tool prompts you to provide the PIN assigned to these keys during purchase and the private key password assigned in an earlier step, as shown in Figure 12.6. When the information is entered, click the Register button to register the signing key installation with RIM. Because the Signing Tool registers using an Internet connection, if the environment the keys are being installed into requires the use of a proxy server, you can provide the proxy server configuration settings after clicking the Configure Proxy button.
Figure 12.6BlackBerry Signing Tool registration
If the registration process is successful, a dialog appears containing information about the key that was registered, including the number of signings supported by the key that was registered. If an error occurs in the process, search for the error in the Developer Knowledge Base at http://www.blackberry.com/developers and follow any appropriate instructions you find to resolve the problem.
Repeat this step for each key file you received. Because the private key has already been created, the only step in the process that must be completed is the registration of the additional keys with RIM.
Copying Signing Key Information
If you are using the eJDE exclusively, the signature information is installed with the plug-in and available across multiple versions of the eJDE Component Package. If using multiple versions of the JDE (one for each version of BlackBerry Device Software being supported) or the eJDE plus one or more versions of the JDE, there is an additional setup step required.
During the installation of the signing keys, the installation process creates two files containing information regarding your set of keys. These files must be available to each instance of the Signing Tool installed with the eJDE and JDE. The files are called sigtool.csk and sigtool.db, and they are created in the bin folder for the most recently installed version of the JDE or eJDE Component Package. To complete the installation, copy these two files into the same folder for each additional version of the JDE installed on the PC. For the JDE, the files are usually located in C:\Program Files\Research In Motion\BlackBerry JDE 4.7.0\bin (replacing the 4.7.0 with the version of the JDE you use). For the eJDE, the files are installed within the Eclipse installation, such as C:\Program Files\eclipse\plugins\net.rim.eide.componentpack4.7.0_4.7.0.46\components\bin.
Beginning with BlackBerry Device Software 4.3, the format of the signing key files was changed. To support signing applications using JDE versions prior to version 4.3, you must also copy the SignatureTool.jar file from the bin folder to the same folder in older versions of the JDE.
12.6 Conditional Compilation Using the Preprocessor
One of the issues that early BlackBerry Java developers faced was how to build Java applications for multiple versions of the BlackBerry Device Software. Say, for example, that a new feature became available in a newer Device Software version, and a developer wants to use it in his application. What the developer has to do is maintain separate source files for each version of the application: one that used the new feature and another for older versions of the BlackBerry Device Software. As an application gets more features and starts to support multiple devices, there might be more and more versions of the application being maintained. The developer could move the special code into libraries and link in the appropriate version when building, but this becomes complicated and requires some sophisticated configurations and special build tools.
It was only recently that RIM announced that the RIM Application Program Compiler (RAPC) supported preprocessing; a capability a developer can use to build multiple versions of an application from the same set of application source files.
12.6.1 Preprocessor Defines
To enable this feature, a developer creates Preprocessor Defines in the project file or on the command line to RAPC and then places special Preprocessor Directives into the source files to instruct the preprocessor on how to manipulate the source code at build time. The Preprocessor Defines are like special variables used only by the Preprocessor. Because the Preprocessor Defines are configured differently depending on which BlackBerry Java development is being used, they are covered in the chapters that address each development tool.
12.6.2 Preprocessor Directives
RAPC supports only a limited suite of Preprocessor Directives, but they’re enough to dramatically simplify the life of any developer building applications with multiple versions. The directives are placed into the application source files and instruct the Preprocessor on how to manipulate the code prior to compilation. This section describes the supported Preprocessor Directives available on the BlackBerry Java platform.
Enabling the Preprocessor
To enable the source file for preprocessing, the source file must contain the following directive. For readability and ease of use, it needs to be placed near the beginning of the source file. The proper syntax for the directive is
Using an If, Else, EndIf Block
To execute different code branches depending on whether a particular Preprocessor Define value is defined, use the following structure:
[Code executed if the preprocessor define exists]
[Code executed if the preprocessor define does not exist]
In this case, the first block of code is executed if <tag> is defined as a Preprocessor Define within the project. If <tag> is not defined, the second block of code executes.
To see an example of this at work, look at the following code. In the URL Launch application described in Chapter 11, there was a special condition identified where the application would not work correctly on BlackBerry Device Software 4.2. To support BlackBerry Device Software 4.2, an additional line of code needed to be added to the application. In the following example, a Preprocessor Directive is defined that inserts the additional line of code only if the Preprocessor Define, called BBDS42, is defined for the project:
public urlLaunch() {
BrowserSession browserSession = Browser.getDefaultSession();
browserSession.displayPage(appURL);
browserSession.showBrowser();
System.exit(0);
}
Using an If Not, Else, EndIf Block
To execute different code branches depending on whether a particular Preprocessor Define value is not defined, use the following structure:
[Code to be executed if the preprocessor define exists]
[Code executed if the preprocessor define does not exist]
This example is the opposite of the previous one. The first block of code is executed if <tag> is not defined as a Preprocessor Define within the project. If <tag> is defined, the second block of code executes.
12.7 Additional Resources
A complete listing of links to these resources is available online at http://www.bbdevfundamentals.com.
The BlackBerry Java development tools can be downloaded from http://www.blackberry.com/developers.
Several interesting knowledge base articles are related to concepts in this chapter:
- How To: Create a Single .alx File to Install Multiple Versions of an Application (Article #DB-00028)
- How To: Compile a MIDlet into a COD File (Article #DB-00055)
- How to: Manually Register the CSI Files (Article #DB-00100)
- What Is: Signature Key Format Changes in BlackBerry JDE 4.3.0 (Article #DB-00639)
- Support: Unable to Register Keys or Sign a File While Behind a Proxy Server (Article #DB-00105)
- How To: Use the Preprocessor (Article #DB-00712)
To access the articles, go to http://www.blackberry.com/developers and search for the relevant knowledge base article.
The BlackBerry Developer’s website hosts several tutorials related to content in this chapter:
