Blackberry java plug in for eclipse development guide 933400 1110042117 001 1 1 us by Marco Hurtado

BlackBerry Java Plug-in for Eclipse Version: 1.1

Development Guide

Published: 2010-05-27 SWD-933400-0527051130-001

Contents 1

Development Guide.................................................................................................................................................................... Managing BlackBerry application projects.................................................................................................................................. Create a BlackBerry application project.............................................................................................................................. Create a Java source file in a BlackBerry device application project............................................................................... Import a BlackBerry application project from an existing BlackBerry JDE workspace.................................................. Import a BlackBerry Java Plug-in for Eclipse sample application.................................................................................... Import a file into a BlackBerry application project............................................................................................................. Delete a file from a BlackBerry application project............................................................................................................ Change the properties of a BlackBerry application project.............................................................................................. Project dependencies............................................................................................................................................................. Add a project dependency.................................................................................................................................................... Add a .jar file dependency..................................................................................................................................................... Specify the application settings for a BlackBerry application project............................................................................. Specify the localization settings for a BlackBerry application project............................................................................. Specify compiler settings for a BlackBerry Application project........................................................................................ Specify the build settings for a BlackBerry application project........................................................................................ Specify the alternate entry point settings for a BlackBerry application project............................................................. Create a launch configuration for a BlackBerry device application project.................................................................... Managing BlackBerry device application memory...................................................................................................................... Locating memory allocation problems................................................................................................................................. Optimizing code using the Profiler...................................................................................................................................... Localizing BlackBerry device application projects...................................................................................................................... Creating resource files........................................................................................................................................................... Create a resource file for a BlackBerry device application................................................................................................ Verify the resource keys that are used in a BlackBerry device application project........................................................ Locate all of the Java files that use a resource key............................................................................................................. Specify an original locale....................................................................................................................................................... Mark a translation as correct or incorrect........................................................................................................................... Building a BlackBerry device application..................................................................................................................................... Build an application project automatically.......................................................................................................................... Specifying preprocessor directives....................................................................................................................................... Create preprocessor directives for a workspace................................................................................................................. Create preprocessor directives for a project.......................................................................................................................

3 3 3 3 3 4 4 5 5 5 5 6 6 8 9 10 11 12 13 13 15 18 18 19 19 19 20 20 20 20 20 21 21

Packaging a BlackBerry application project....................................................................................................................... Package a BlackBerry application project........................................................................................................................... Running BlackBerry device applications that use protected APIs............................................................................................ Register to use protected BlackBerry APIs.......................................................................................................................... Using restricted code signatures.......................................................................................................................................... Request a code signature...................................................................................................................................................... Requesting a replacement registration key........................................................................................................................ Prevent a BlackBerry device application that runs on the BlackBerry Smartphone Simulator from accessing protected APIs........................................................................................................................................................................ Use a code signing key to protect packages and classes.................................................................................................. Install a new code signing key.............................................................................................................................................. Import an existing code signing key.................................................................................................................................... Remove a code signing key................................................................................................................................................... View the signature status for code signature requests..................................................................................................... Restrict access to packages or classes in a BlackBerry library project............................................................................ Sign a BlackBerry application project automatically after packaging............................................................................. Turn off automatic signature when you package a BlackBerry application project....................................................... Run the BlackBerry Signature Tool in the background...................................................................................................... Suppress password prompts from the BlackBerry Signature Tool.................................................................................... Suppress code signing warnings.......................................................................................................................................... Testing and debugging BlackBerry applications......................................................................................................................... Configuring the BlackBerry Smartphone Simulator........................................................................................................... Testing a BlackBerry device application with the BlackBerry Smartphone Simulator................................................... Making BlackBerry device applications available to BlackBerry device users................................................................ Troubleshooting.............................................................................................................................................................................. I cannot reload a BlackBerry device application without restarting the BlackBerry Smartphone Simulator or resetting the BlackBerry device............................................................................................................................................

21 21 22 22 22 23 23 24 24 24 25 25 25 26 27 27 28 28 28 28 28 35 40 42 42

2 Provide feedback.........................................................................................................................................................................

3 Legal notice..................................................................................................................................................................................

Development Guide

Managing BlackBerry application projects Project settings are defined in an .xml file. You can use the Eclipse® editor to change the settings. You can import the projects that you created in the BlackBerry® JDE Plug-in for Eclipse 1.0, or in the BlackBerry® Java® Development Environment, into Eclipse 3.5 with the BlackBerry® Java® Plug-in 1.1.

Create a BlackBerry application project When you run a BlackBerry® application project that does not contain a public static method, the project is treated as a library application project. 1. 2. 3. 4. 5. 6.

On the File menu, click New > Project. Expand the BlackBerry® folder and select BlackBerry Project. Click Next. In the Project name field, type a name for the project. Select Create new project in workspace. Complete one of the following tasks: • To specify a specific JRE™, select Use a project specific JRE. • To specify the default JRE in the workspace, select Use default JRE.

7. 8.

Click Next. Click Finish.

Create a Java source file in a BlackBerry device application project 1. 2. 3. 4.

In the Package Explorer view, expand a BlackBerry® device application project. Right-click the src folder and select New > Class. In the Name field, type a name for the .java file. Click Finish.

Import a BlackBerry application project from an existing BlackBerry JDE workspace You can import a project from the following development environments into Eclipse® 3.5 with the BlackBerry® Java® Plug-in for Eclipse 1.1: • BlackBerry® Java® Development Environment .

Development Guide

Managing BlackBerry application projects

• Eclipse with the BlackBerry® JDE Plug-in 1.0 . You cannot export a project from Eclipse 3.5 with the BlackBerry Java Plug-in for Eclipse 1.1 into an earlier version. Project files (.jdp) and workspace files (.jdw) are no longer supported. 1. 2. 3. 4. 5.

On the File menu, click Import. In the Import dialog box, expand the BlackBerry folder. Select Import Legacy BlackBerry Projects. Click Next. Complete one of the following tasks: • To specify a specific JRE™,select Use a project specific JRE. • To specify the default JRE in the workspace, select Use default JRE.

6. 7. 8.

In the BlackBerry Workspace field, browse to a BlackBerry workspace (.jdw) file. Select the projects that you want to import. Complete one of the following tasks: • To create a copy of the imported projects in the Eclipse workspace, select the Copy BlackBerry projects into workspace option. • To link to the original location of the imported projects, clear the Copy BlackBerry projects into workspace option.

Click Finish.

Import a BlackBerry Java Plug-in for Eclipse sample application 1. 2. 3. 4. 5.

On the File menu, click Import. In the Import dialog box, expand the BlackBerry folder. Select Import BlackBerry Samples. Click Next. Complete one of the following tasks: • To specify a specific JRE™, select Use a project specific JRE. • To specify the default JRE in the workspace, select Use default JRE.

6. 7.

In the BlackBerry Projects dialog box, select the sample applications that you want to import. Click Finish.

Import a file into a BlackBerry application project 1. 2. 3.

In the Package Explorer view, select a BlackBerry® application project. Right-click the project and click Import. Expand the General folder.

Development Guide

4. 5. 6. 7. 8. 9.

Managing BlackBerry application projects

Select the File System folder. Click Next. In the From directory dialog box, browse to the location of the source files and select the files that you want to import. In the Into folder field, browse to the location where you want to save the files. In the Options section, select the appropriate options. Click Finish.

Delete a file from a BlackBerry application project 1. 2. 3.

In the Navigator view, select a file in a BlackBerry® application project. Right-click the file and click Delete. Click OK.

Change the properties of a BlackBerry application project The properties of a BlackBerry® application project are contained in the BlackBerry_App_Descriptor.xml file. Note: The BlackBerry_App_Descriptor.xml file is not located in a source folder. A change to the BlackBerry_App_Descriptor.xml file does not trigger a Java® build and does not package a BlackBerry application project. 1. In the Package Explorer view, expand a BlackBerry application project. 2. Double-click the BlackBerry_App_Descriptor.xml file. 3. Change the properties and save the file.

Project dependencies You can use project dependencies to help save time and reduce code duplication when you create a BlackBerry® device application.

Add a project dependency 1. 2. 3. 4. 5. 6.

In the Package Explorer view, right-click the project that you want to add a dependency to. Click Build Path --> Configure Build Path. Click the Projects tab. Click Add. Select the project that you want this project to depend on. You must select either a Java® application project or a BlackBerry® application project of the Library type. Click OK.

Managing BlackBerry application projects

Development Guide

Add a .jar file dependency 1. 2. 3. 4.

In the Package Explorer view, right-click the project that you want to add a dependency to. Click Build Path > Configure Build Path . Click the Libraries tab. Complete one of the following tasks: • Click Add JARS if the .jar file is in the current workspace. • Click Add External JARS if the .jar file is not in the current workspace.

Select the .jar file that you want this project to depend on. The .jar file must be generated by a Java® application project. You cannot add a BlackBerry® application project of the Library type in this manner. Click OK.

Specify the application settings for a BlackBerry application project 1. 2. 3. 4. 5. 6.

In the Package Explorer view, right-click a BlackBerry® application project and click Properties. In the Properties for pane, click BlackBerry Project. Click Application Descriptor. Click the Application tab. Specify the application settings. On the Eclipse® toolbar, click Save.

Properties for application settings Setting

Description

Title

Type a descriptive name for the project. To create a keyboard shortcut for an application, add the Unicode underscore character (\u0332) after a letter in the title. For example, for the Hello World application, type H\u0332ello World. When the BlackBerry® device user presses the H key on the Home screen of the BlackBerry device, the Hello World application starts. If multiple applications use the same keyboard shortcut, the application that appears first on the Home screen starts.

Version

This setting is not available if the Application type is Library. Type the version number of the project. The default value is 1.0.0.

Managing BlackBerry application projects

Development Guide

Setting

Description

Vendor Description Application type

Type the name of the company that owns the project. Type a description for the project. Select one of the following application types: • • •

Name of main MIDlet class

BlackBerry Application: an application that uses CLDC/MIDP and BlackBerry APIs MIDlet: an application that uses only MIDP APIs Library: a library that other applications depend on

The default setting is BlackBerry Application. Type the name of the class that extends javax.microedition.midlet.MIDlet

Application arguments

This field is available only if the Application type is MIDlet. Specify the arguments to pass into the main() method of the application.

Do not display the application icon on the BlackBerry home screen.

This field is available only if the Application type is BlackBerry Application. Select this setting to run the application in the background, without displaying an icon on the Home screen of the BlackBerry device.

Auto-run on startup

This setting is not available if the Application type is Library. Select this setting to start the application automatically when the BlackBerry device starts. This setting is not available if the Application type is MIDlet.

Startup tier

Applications that run automatically must be digitally signed by RIM to run on a BlackBerry device. If the Auto-run on startup setting is selected, specify the priority in which the application is started, in relation to other applications. For third-party applications, you can select tier 6 or 7 (other start-up tiers are reserved for BlackBerry Applications). The default setting is 7 (lowest priority).

Application icons

This setting is not available if the Application type is MIDlet. Add the files for application icons from the project's resources or from a location external to the project. To specify a rollover icon, select Rollover.

Managing BlackBerry application projects

Development Guide

Setting

Description The number of application icons is limited to two.

Specify the localization settings for a BlackBerry application project Before you begin: Create the files that are required for localization. For information about localizing a BlackBerry device application, see the BlackBerry Java Application Development Guide . 1. 2. 3. 4. 5. 6. 7.

In the Package Explorer view, select a BlackBerry application project. Right-click the project and click Properties. In the Properties for pane, select BlackBerry Project --> Application Descriptor. Click the Application tab. Specify the locale resources. Click Close. Click Yes.

Properties for localization settings Setting

Description

Internationalized resource bundle available Resource bundle

Select this setting if the title and description of the application are internationalized in a resource bundle. Select the resource header file to use for the application (for example, HelloWorldRes). Select the resource key to use for the application title (for example, APPLICATION_TITLE). If you do not provide a resource key for the application title, the BlackBerry速 Java速 Plug-in for Eclipse速 uses the title that is specified in the Title field. Select the resource key to use for the application description (for example, APPLICATION_DESCRIPTION). If you do not provide a resource key for the application description, the BlackBerry Java Plug-in for Eclipse uses the description that is specified in the Description field.

Title ID

Description ID

Managing BlackBerry application projects

Development Guide

Specify compiler settings for a BlackBerry Application project 1. 2. 3. 4. 5. 6. 7.

In the Navigator view, select a BlackBerry® application project. Right-click the project and select Properties. In the Properties for pane, select BlackBerry Project Properties. Click the Compile tab. Change the compiler settings. Click Apply. Click OK.

Properties for compiler settings Setting

Description

Output messages about what the compiler is doing

Select this setting to view detailed compiler information when you build a project.

Generate no warnings

Treat warnings as errors Output source locations where deprecated APIs are used Don't convert image files to png

No warning for no exported static routine: .main(String[]) Preprocessor defines Alias list

Selecting this setting is the same as setting the -verbose setting for rapc. If you select this setting, Eclipse® will create many “rapc_XXXX.dir" directories in the %TEMP% directory during compilation. Select this setting to hide compiler warnings when you build a project. Tip: Warnings do not prevent the project from being built successfully, but they can indicate possible errors in your code. Select this setting to stop compilation if warnings occur. Select this setting to view the location of deprecated APIs in the source files. Select this setting to prevent image files from being converted to .png format. Select this setting if your application needs to access raw image data on the BlackBerry device. Select this setting to prevent the compiler from issuing a warning if main() is undefined. Add, remove, or edit directives that the preprocessor uses when it processes Java® files. Repackage existing API libraries into a new library project. Specify one or more libraries that this project replaces, separated with semi-colons (;).

Managing BlackBerry application projects

Development Guide

Setting

Description For example, if you are creating a library project called “newlib” that repackages existing libraries “libA” and “libB”, you can specify libA;libB in this field so that .cod files that use those libraries continue to work correctly.

Specify the build settings for a BlackBerry application project 1.

In the Package Explorer view, select a BlackBerry® application project.

2. 3. 4. 5. 6. 7.

Right-click the project and click Properties. In the Properties for pane, select BlackBerry Project --> Application Descriptor. Click the Build tab. Specify the build settings. Click Close. Click Yes.

Properties for build settings Setting

Description

Output file name

Specify the name of the .cod file that is generated when you package the project. If this field is empty, the project name is used. Specify the folder for the files that you create when you package a project. Repackage the existing API libraries into a new library project. Specify one or more libraries that this library project replaces, separated by semi-colons (;). Add, delete, or change the directives that the preprocessor uses when it processes the Java® files for a project. Select this setting to view detailed compiler information when you build a project.

Output folder Alias list Preprocessor Directives Output messages about what the compiler is doing Convert image files to .png Create warning for no exported static routine: main(String[]) Compress resources if significant space gain Generate .alx file (Desktop deployment/ BES Push)

Select this setting to convert image files to .png format. Select this setting to have the compiler issue a warning if main() is undefined. Select this setting to compress the resource files. Select this setting to create the application (.alx) files for distribution.

Managing BlackBerry application projects

Development Guide

Setting

Description

Desktop Manager deployment dependencies

Add, delete, or change the external .alx files that you want to include in your application. You can use this setting to include the applications that your project depends on that are not in the current workspace. The .alx files that you add are included in <requires id> tags in the .alx file that is generated for your project.

Specify the alternate entry point settings for a BlackBerry application project 1.

In the Package Explorer view, select a BlackBerry速 application project.

2. 3. 4. 5. 6. 7. 8. 9.

Right-click the project and click Properties. In the Properties for pane, select BlackBerry Project --> Application Descriptor. Click the Alternate Entry Points tab. Click Add. In the New Entry Point dialog box, type the name of a project in the workspace that this project invokes. Click OK. Select the Alternate entry point properties and Locale Resources. On the Eclipse速 toolbar, click Save.

Properties for the alternate entry point settings Setting

Description

Title

Type a name for the alternate entry point that is displayed on the Home screen of the BlackBerry速 device. Type the name of the class that extends

Name of main MIDlet class

javax.microedition.midlet.MIDlet

Application arguments

This field is available only if the Application type is MIDlet . Specify the arguments to pass into the application's main() method.

Do not show the application icon on theBlackBerry device Home screen

This field is available only if the Application type is BlackBerry application. Select this setting to run the application in the background, without displaying an icon on the Home screen of theBlackBerry device. This setting is not available if the Application type is Library .

Development Guide

Setting

Description

Auto-run on startup

Select this setting to start the application automatically when the BlackBerry device starts. This setting is not available if the Application type is MIDlet.

Startup tier

Internationalized resource bundle available Resource bundle Title ID

Alternate Entry Point icons

This setting is not available if the Application type is MIDlet . Select this setting if the title and the description of the alternate entry point have been internationalized in a resource bundle. Select the resource header file to use for the alternate entry point (for example, HelloWorldRes). Select the resource key to use for the application title (for example, AEP_TITLE). If you do not provide a resource key for the application title, the BlackBerry速 Java速 Plug-in for Eclipse速 uses the title that is specified in the Title field. Add the files for application icons from the project's resources or from a location external to the project. To specify a rollover icon, select Rollover. The number of application icons is limited to two.

Create a launch configuration for a BlackBerry device application project 1. 2. 3. 4. 5. 6. 7.

On the Run menu, click Run Configurations or Debug Configurations. Right-click BlackBerry Simulator, and click New. On the Projects tab, click the project that you want to create a configuration for. On the JRE tab, click the JRE that you want to use. On the Simulator tab, configure the settings for the BlackBerry速 Smartphone Simulator. Click Close. Click Yes.

Managing BlackBerry device application memory

Development Guide

Managing BlackBerry device application memory Locating memory allocation problems Memory allocation problems can cause the BlackBerry速 Java速 Virtual Machine to run out of flash memory, and the BlackBerry device to reset.

Viewing memory statistics You can use the Memory Statistics tool with the Objects tool to find memory allocation problems. The Memory Statistics tool retrieves information about the memory usage of your application, and identifies the number of objects stored in memory. The Objects tool displays detailed information about each object. Column

Description

# objects Bytes in use Allocated Free

number of objects that are currently stored in memory amount of memory that is used by objects total amount of memory that is allocated to the Java速 Virtual Machine amount of memory that is available

Row

Description

Object handles RAM Flash Transient objects (flash) Persistent objects (flash) Code modules (flash)

number of object handles that are stored in memory RAM usage sum of the objects that are stored in flash memory number of transient objects that are stored in flash memory number of persistent objects that are stored in flash memory number of code modules that are stored in flash memory

View statistics to locate memory allocation problems 1. 2. 3. 4.

On the Window menu, click Show View > Other. Expand the BlackBerry folder. Click BlackBerry Memory Statistics View. Click OK.

Development Guide

Managing BlackBerry device application memory

Display objects that are stored in memory to locate memory allocation problems 1. 2. 3. 4. 5. 6. 7. 8. 9. 10. 11. 12. 13. 14. 15. 16.

17. 18.

Specify two or more breakpoints in your code. On the Run menu, click Debug As > BlackBerry Simulator. The application runs to the first breakpoint. In the Debug view, click Suspend. On the Window menu, click Show View > Other. Expand the BlackBerry folder. Click BlackBerry Objects View. Click OK. In the BlackBerry Objects View, click Set up filters. In the Objects View Options dialog box, in the Snapshot Filter drop-down list, click Compare to Snapshot. Click OK. In the BlackBerry Objects View, click Perform garbage collection. Click Snapshot. Press F8 to resume running the application. Perform operations in the application that do not increase the number of reachable objects. For example, create a new contact and then delete it. In the Debug view, click Suspend. In the BlackBerry Objects View, click Perform garbage collection. The BlackBerry Objects View displays the number of objects that have been deleted and added since the previous snapshot. If the number of objects added is not the same as the number of objects deleted, you might have a memory allocation problem. To identify new objects, use the Type, Process, and Location filter types in the Objects View Options dialog box. To save the contents of the BlackBerry Objects View to a comma-separated values (.csv) file, click Save.

Find a memory allocation problem 1. 2. 3. 4. 5. 6. 7. 8.

Specify two or more breakpoints in your code. On the Run menu, click Debug As > BlackBerry Simulator. The application runs to the first breakpoint. On the Window menu, click Show View > Other. Expand the BlackBerry folder. Click BlackBerry Memory Statistics View. Click OK. In the BlackBerry Memory Statistics View, click Refresh . Click Snapshot.

Managing BlackBerry device application memory

Development Guide

9. 10. 11. 12.

Press F8 to resume running the application. The application runs to the second breakpoint. Click Refresh. Click Compare. Repeat steps 1 through 11, setting breakpoints closer together until they converge on the memory allocation problem.

Optimizing code using the Profiler The profiler application collects the following information for the specified code area: • percentage of time spent to the current point of execution. • number objects created. • size of objects created. • number of objects committed. You can improve the reliability of results and computer performance when you run the profiler application by closing other Windows® applications and increasing the heap memory in Eclipse® to 512 MB (see Specify heap memory for Eclipse) .

Specify Profiler options 1. 2. 3. 4. 5. 6. 7.

In the Package Explorer view, right-click a BlackBerry® device application project. Click Debug As > BlackBerry Simulator. On the Window menu, click Show View > Other. Expand the BlackBerry folder. Click BlackBerry Profiler View. Click OK. In the BlackBerry Profiler View, click Setup Options.

Profiler options Drop-down list

Option

Description

Method attribution

Cumulative

The profiler application calculates the time spent executing bytecode in a method and all methods that are invoked by that method. The profiler application calculates the time spent executing bytecode in the specified method only. The timer stops when another method is invoked. The profiler application measures execution time (measured in clock ticks).

In method only

What to profile

Time (clock ticks)

Managing BlackBerry device application memory

Development Guide

Drop-down list

Option

Description

Number of objects created

The profiler application calculates the number of objects that are created. The profiler application measures the size of objects that are created. The profiler application calculates the number of committed objects. The profiler application measures the size of committed objects. The profiler application calculates the number of objects that are moved into memory. The profiler application measures the size of objects that are moved into memory. The profiler application calculates user counting.

Size of objects created Number of objects committed Size of objects committed Number of objects moved to RAM Size of objects moved to RAM User Counting

Generate Profiler data 1. 2. 3.

Specify a breakpoint at the beginning and end of the section of code that you want to profile. On the Run menu, click Debug As > BlackBerry Simulator. In the BlackBerry速 Smartphone Simulator, run the application. The debugging tool pauses the application when it reaches the first breakpoint. 4. In Eclipse速, on the Window menu, click Show View > Other. 5. Expand the BlackBerry folder. 6. Click BlackBerry Profiler View. 7. Click OK. 8. In the BlackBerry Profiler View, click Setup Options. 9. In the Profiler Options dialog box, select the type of method attribution and the type of information that you want to profile. 10. Click OK. 11. Press F8 to resume program execution. The debugging tool pauses the application when it reaches the second breakpoint. 12. In the BlackBerry Profiler View, click Refresh. The profiler retreives the data. Profiler data is not cleared, so running an application again adds to the data. 13. To save the contents of the profiler pane to a comma-separated values (.csv) file, in the BlackBerry Profiler View, click Save

Managing BlackBerry device application memory

Development Guide

Viewing Profiler data The BlackBerry Profiler Pane has three tabs. Each tab displays details about an item of execution (such as a method), the percentage of time spent running the item, and the number of times that the item was run. Tab

Description

Summary

The Summary tab displays general statistics about the system and the garbage collector.

Method

Source

This tab displays the percentage of time that the BlackBerry速 Java速 Virtual Machine has spent idle, executing code, and performing quick and full garbage collection. The Percent column displays the percentage of total BlackBerry JVM running time, including idle time and collection time. The Method tab displays a list of modules, sorted either by the information that you are profiling or by the number of times each item has been executed. On this tab, the Percent column displays the percentage of BlackBerry JVM execution time only, not including idle time and garbage collection time. The Source tab displays the source lines of a single method. You can navigate through the methods that invoke, and are invoked by, that method. You can expand a source line to show individual bytecode. You can further expand any bytecode that corresponds to a method invocation to show the target or targets of the method invocation.

View Profiler data 1. 2. 3. 4.

On the Window menu, click Show View > Other. Expand the BlackBerry folder. Click BlackBerry Profiler View. Click OK.

Save the contents of the BlackBerry profiler view to a .csv file 1. 2. 3.

In the BlackBerry Profiler View, click Refresh. Click Save data to a .csv file. Select a location and type a name for the file.

Localizing BlackBerry device application projects

Development Guide

Click Save.

The BlackBerry® Java® Plug-in for Eclipse® saves the contents of the BlackBerry profiler view to a comma-separated values (.csv) file. Contents are saved in the same format that they are displayed in.

Localizing BlackBerry device application projects You can use the BlackBerry® Java® Plug-in for Eclipse® to localize text strings without changing the application code. The BlackBerry Java Plug-in for Eclipse provides versioning support for creating resources in different languages. You can make changes to resource values in a native language, or original locale. Translators can identify language resources that have changed and that require translation. A ResourceBundle object stores information and resources for a locale. A ResourceBundleFamily object contains a collection of ResourceBundle objects. An application can use a ResourceBundleFamily object to display the information in a language that is specific to the locale of the BlackBerry device user. When you compile a BlackBerry device application , the BlackBerry Java Plug-in for Eclipse compiles each ResourceBundle object that you include with the application into a separate code .cod file. You can install the appropriate .cod files on a BlackBerry device along with the other files that the application requires. For more information about managing resources for localization, see the BlackBerry Java Development Environment Fundamentals Guide .

Creating resource files When you create a new .rrh resource header file, the BlackBerry® Java® Plug-in for Eclipse® creates the associated .rrc resource content file. If an .rrh file already exists, the BlackBerry Java Plug-in for Eclipse creates only the new .rrc file. If an .rrh file does not already exist, the BlackBerry Java Plug-in for Eclipse creates the .rrc file and the .rrh file. For each BlackBerry device application that you want to localize, you must create a resource header file, a resource content file for the global locale, and a resource content file for any specific locales that you require. File

Description

Example

Resource header file

This file defines the descriptive keys for each localized string.

AppName.rrh

Resource content file root (global) locale

During compilation, the BlackBerry Java Plug-in for Eclipse creates a resource interface automatically that uses the same name as the .rrh file with Resource appended. This file maps numeric keys to string literals for the root (global) locale.

AppName.rrc

Localizing BlackBerry device application projects

Development Guide

File

Description

Example

Resource content file (specific locales)

This file maps descriptive keys to values for the global and specific locales (language and country).

AppName_en.rrc

This file must have the same name as the resource header file, followed by an underscore (_) and the language code, and then, optionally, by a single underscore (_) and a country code (for example, AppName_en_GB.rrc). Two-letter language and country codes are specified in ISO-639 and ISO-3166, respectively.

Create a resource file for a BlackBerry device application 1. 2. 3. 4. 5. 6. 7.

On the File menu, click New > Other. In the New dialog box, expand the BlackBerry item. Click BlackBerry Resource File. Click Next. In the Create a new BlackBerry Resource File dialog box, click the project folder for the BlackBerry device application. In the File name field, type the name of the .rrc file or .rrh file. Click Finish.

Verify the resource keys that are used in a BlackBerry device application project 1. 2.

In the Package Explorer view, double-click an .rrh file. In the Resource Editor window, click Validate. If one or more resource keys are not found, a message appears indicating the resource keys that are not present.

Locate all of the Java files that use a resource key 1. 2. 3.

In the Package Explorer view, double-click an .rrh file. In the Resource Editor window, click a key, and click Validate. Click Yes. If the key is found, the BlackBerry速 Java速 Plug-infor Eclipse速 lists all of the Java速 files that reference the key and the line numbers in the Java files where the key is referenced.

Building a BlackBerry device application

Development Guide

Specify an original locale The original locale contains resource values in a native language. You must specify an original locale for each resource header (.rrh) file. 1. In the Package Explorer view, double-click an .rrh file. 2. In the Resource Editor window, click Options. 3. In the Resource Editor Options dialog box, select Use versioning highlighting from given resource. 4. In the locale drop-down list, click a locale (for example, en).

Mark a translation as correct or incorrect 1. 2. 3.

In the Package Explorer view, double-click an .rrh file. In the Resource Editor window, right-click a resource key. Perform one of the following actions: • To mark a translation as correct, click Mark Translation Correct. • To mark a translation as incorrect, click Mark Translation Incorrect.

Building a BlackBerry device application Build an application project automatically On the Project menu, click Build Automatically. Each time you save resources in a project, an incremental build occurs.

Specifying preprocessor directives You can specify preprocessor directives that are used to preprocess your Java® source files before they are passed to the Java compiler. You can specify preprocessor directives for a single project or for all projects in a workspace. You must turn on preprocessing in Eclipse® before you can specify preprocessor directives. For more information about how to turn on preprocessing, see the BlackBerry Java Plug-in for Eclipse Installation and Configuration Guide . Directive

Description

//#preprocess

This directive specifies that a file must be preprocessed. This directive must be the first line in a .java file. This directive specifies that the block before the else is compiled if tag is specified. Otherwise, only the block after the else is compiled.

//#ifdef tag ... #else ... #endif

Building a BlackBerry device application

Development Guide

Directive

Description

//#ifndef tag ... #else ...

This directive specifies that the block before the else is compiled if tag is not specified. Otherwise, only the block after the else is compiled.

#endif

If you have not turned on preprocessing, before you specify preprocessor directives you are prompted to restart Eclipse.

Create preprocessor directives for a workspace The preprocessor directives that you create are defined for all projects in the workspace. Before you begin: You must turn on preprocessing in Eclipse® before you can specify preprocessor directives. For more information about how to turn on preprocessing, see the BlackBerry Java Plug-in for Eclipse Installation and Configuration Guide . 1. 2. 3. 4.

On the Window menu, click Preferences. Expand the BlackBerry Java Plug-in item and click Build. In the Preprocessor Defines dialog box, add, remove, or edit directives. Click OK.

Create preprocessor directives for a project Before you begin: You must turn on preprocessing in Eclipse® before you can specify preprocessor directives. For more information about how to turn on preprocessing, see the BlackBerry Java Plug-in for Eclipse Installation and Configuration Guide . 1. 2. 3. 4. 5. 6.

In the Package Explorer view, right-click a BlackBerry® project and click Properties. Click BlackBerry Project. Click Application Descriptor. Click the Build tab. In the Preprocessor Directives dialog box, type the preprocessor directives for your project. On the Eclipse toolbar, click Save.

Packaging a BlackBerry application project When you package a BlackBerry® application project, you create the files that you install on a BlackBerry device (for example .cod files and .alx files). When you package a BlackBerry application project, you trigger an incremental Java® build, and you also repackage the applications that depend on the BlackBerry application project.

Package a BlackBerry application project 1.

In Package Explorer view, right-click a BlackBerry® project.

Development Guide

Running BlackBerry device applications that use protected APIs

Click BlackBerry > Package Project(s). The Console view displays the progress of packaging.

Running BlackBerry device applications that use protected APIs To use protected Research In Motion® APIs in your BlackBerry® device application, you must first receive code signing permission from RIM. For more information about code signing and to register with RIM to use protected APIs, visit www.blackberry.com/ eng/developers/javaappdev/codekeys.jsp. If a BlackBerry device application tries to access protected RIM APIs, the BlackBerry® Java® Plug-in for Eclipse® might display warning messages in the Java® editor window or in the Problems view. The warning messages appear next to the lines of application code that reference a protected API. You can suppress these warnings.

3. 4. 5. 6. 7. 8.

Visit www.blackberry.com/JDEKeys and complete the registration form. Save the .csi file that Research In Motion sends to you. The .csi file contains a list of signatures and your registration information. If the BlackBerry® Signing Authority Tool administrator does not provide you with the .csi file or the Registration PIN and you are an ISV partner, contact your ISV Technical Partnership Manager. If you are not an ISV partner, send an email message to jde@rim.com. Double-click the .csi file to start the BlackBerry Signing Authority Tool . If a dialog box appears that states that a private key cannot be found, follow the instructions to create a new key pair file. In the Registration PIN field, type the PIN that RIM provided. In the Private Key Password field, type a password of at least eight characters. The private key password protects your private key. If you lose this password, you must register again with RIM. If this password is stolen, contact RIM immediately. Click Register. Click Exit.

Using restricted code signatures The BlackBerry® Signing Authority Tool administrator might place restrictions on your .csi file to limit your access to code signatures. To request changes to these restrictions, contact your administrator.

Running BlackBerry device applications that use protected APIs

Development Guide

.csi file restriction

Description

# of Requests

This restriction specifies the maximum number of requests that you can make by using this .csi file. When you reach the maximum number of requests, the .csi file is no longer valid. To make new code signature requests, you must apply for a new .csi file.

Expiry Date

Although administrators can permit an infinite number of requests, they often specify a maximum number of requests for security reasons. This restriction specifies the expiry date for your .csi file. After the expiry date, you can no longer make code signature requests with this .csi file. To make new signature requests, you must apply for a new .csi file.

Request a code signature Before you begin: To perform this task, you must already have a .csi file that Research In Motion provides. For more information about requesting a .csi file from RIM , visit www.blackberry.com/eng/developers/javaappdev/codekeys.jsp 1. 2. 3. 4. 5. 6.

In Eclipse®, in the Package Explorer view, right-click a BlackBerry® application project. Click BlackBerry > Sign with Signature Tool. Select the files that require a code signature. In the Signature Tool dialog box, click Request. Type your private key password. Click OK. The BlackBerry® Signing Authority Tool uses the private key password to append the signature to the request, and sends the signed list of .cod files to the Web Signer application for verification. The Web Signer application is installed when you install the BlackBerry Signing Authority Tool . For more information about the Web Signer application, see the BlackBerry Signing Authority Tool Version 1.0 - Password Based Administrator Guide .

Requesting a replacement registration key Your registration key and .csk file are stored together. If you lose the registration key or the .csk file, you cannot request code signatures. • •

If you are an ISV partner and lose the .csk file, contact your ISV Technical Partnership Manager. If you are not an ISV partner and lose the .cskf file, send an email message to jde@rim.com.

Development Guide

Running BlackBerry device applications that use protected APIs

Prevent a BlackBerry device application that runs on the BlackBerry Smartphone Simulator from accessing protected APIs To prevent an application that runs on the BlackBerry® Smartphone Simulator from accessing protected APIs, you must turn on device security in the BlackBerry Smartphone Simulator. 1. On the Run menu, click Debug Configurations or Run Configurations. 2. Expand the BlackBerry Simulator item. 3. Select an existing launch configuration for a BlackBerry Smartphone Simulator, or create a new one. 4. Click the Simulator tab. 5. Click the General tab. 6. Select Enable device security. 7. Click Run.

Use a code signing key to protect packages and classes Before you begin: You must have the internal code signing key, the external code signing key, or both code signing keys that Research In Motion® provides. For more information about requesting code signing keys from RIM, visit www.blackberry.com/eng/developers/ javaappdev/codekeys.jsp. 1. 2. 3. 4. 5. 6. 7. 8. 9.

Open Eclipse®. Open the project that contains the packages or classes that you want to control access to. In the Navigator view, double-click a .key file. To specify that the .key file is used to protect all public classes, select Use as default for public classes. To specify that the .key file is used to protect all non-public classes, select Use as default for non-public classes. Locate the name of the package that contains the packages and classes that the .key file protects. Expand the package contents. Select each element that requires access control. Click Ok.

Install a new code signing key 1. 2. 3.

On the Window menu, click Preferences. Expand the BlackBerry® Java® Plug-in item. Click Signature Tool.

Development Guide

4. 5. 6. 7.

Running BlackBerry device applications that use protected APIs

Click Install New Keys. Navigate to the location of the signature (.csi) file that you want to add the key to and click the file. Click Open. Click OK.

Import an existing code signing key 1. 2. 3. 4. 5. 6. 7.

On the Window menu, click Preferences. Expand the BlackBerry® Java® Plug-in item. Click Signature Tool. Click Import Existing Keys. Navigate to the location of the BlackBerry® application project that you want to import the key from. Select the folder that you want to import the key from. Click OK.

Remove a code signing key 1. 2. 3. 4. 5. 6.

On the Window menu, click Preferences. Expand the BlackBerry® Java® Plug-in item. Click Signature Tool. Click Remove Keys. Click Yes. Click OK.

View the signature status for code signature requests For files that the Web Signer application has signed, the status is Signed. For files that the Web Signer application did not sign, the status is Failed. The Web Signer application might have rejected the .cod file because the private key password was typed incorrectly. 1. Open Eclipse®. 2. On the Project menu, click BlackBerry > Sign with Signature Tool. 3. Select a .cod file. 4. View the Status column.

Running BlackBerry device applications that use protected APIs

Development Guide

Restrict access to packages or classes in a BlackBerry library project You can protect the packages and the classes in your BlackBerry速 library project by using one or more private keys. For more information about the code signing process visit www.blackberry.com/go/devguides to see the BlackBerry Signing Authority Tool Version 1.0 - Password Based Administrator Guide. Note: You can protect a package or a class with only one private key at a time. Before you begin: You must have a key pair (public key and private key). You can get a key pair by using the BlackBerry速 Signing Authority Tool. To download the BlackBerry Signing Authority Tool visit www.blackberry.com/developers/downloads. 1.

Complete one of the following tasks: Task

Steps

Copy a private key (.key) into your BlackBerry library project.

In the Package Explorer view, copy and paste the private key into the / src folder of your BlackBerry library project.

Double-click the private key to open the key editor.

On the File menu, click Import.

Expand General and click File System.

Click Next.

In the From directory dialog box, click Browse. Navigate to the location of the private key and click OK.

In the right-hand pane, select the private key.

In the Into folder dialog box, click Browse and navigate to the location of the /src folder of your BlackBerry library project.

Click the src folder and click OK.

Click Finish.

Double-click the private key to open the key editor.

In the Package Explorer view, right-click the /src folder of your BlackBerry library project.

Click New > File.

Click Advanced.

Select the Link to file in the file system option.

Click Browse to navigate to the location of the private key and click Open.

Import a private key (.key) into your BlackBerry library project.

Link a private key (.key) to your BlackBerry library project.

Running BlackBerry device applications that use protected APIs

Development Guide

Task

Steps f.

Click Finish.

The key editor opens automatically. 2. 3. 4.

In the key editor, select the package or class that you want to restrict access to. Close the key editor and click Save. Package your BlackBerry library project. Access to the .cod file that is created is restricted at runtime.

After you finish: When a BlackBerry device application accesses a package or a class that is protected in the BlackBerry library project, the application's .cod file must be signed with the same private key as the package or class. You can sign the .cod file with the private key by using the File Signer tool in the BlackBerry Signing Authority Tool .

Sign a BlackBerry application project automatically after packaging 1. 2. 3. 4. 5.

On the Window menu, click Preferences. Expand the BlackBerry Java Plug-in item. Click Signature Tool. Select Automatically sign the .cod files after packaging. Click OK.

Turn off automatic signature when you package a BlackBerry application project By default, when you package a BlackBerry速 application project, the BlackBerry速 Signature Tool runs automatically to sign .cod files that access protected APIs. To turn off this feature and run the BlackBerry Signature Tool manually, complete the following tasks: 1. 2. 3. 4. 5.

On the Window menu, click Preferences. Expand the BlackBerry Java Plug-in item. Click the Signature Tool item. Clear the Automatically sign the .cod files after packaging option. Click OK.

Development Guide

Testing and debugging BlackBerry applications

Run the BlackBerry Signature Tool in the background You can run the BlackBerry® Signature Tool automatically after you package your BlackBerry application project. 1. 2. 3. 4. 5.

On the Window menu, click Preferences. Expand the BlackBerry Java Plug-in item. Click the Signature Tool. Select the Run Signature Tool in background check box. Click OK.

Suppress password prompts from the BlackBerry Signature Tool When you package a BlackBerry® application project, the BlackBerry® Signature Tool prompts you for your signing password. You can save your signing password for the Eclipse® session. 1. 2.

When you are prompted, in the Signing Password dialog box, select Remember password. Click OK.

Suppress code signing warnings 1. 2. 3. 4. 5.

On the Window menu, click Preferences. Expand the BlackBerry Java Plug-in item. Click Warnings. Select the keys for the protected APIs that you do not want to see warnings for. Click OK.

Testing and debugging BlackBerry applications Configuring the BlackBerry Smartphone Simulator Settings for the BlackBerry® Smartphone Simulator are associated with a launch configuration. Each launch configuration is associated with a set of projects and a specific version of the BlackBerry® Device Software.

Specify configuration settings for the BlackBerry Smartphone Simulator 1.

In Eclipse®, on the Run menu, click Debug Configurations or Run Configurations.

Testing and debugging BlackBerry applications

Development Guide

2. 3.

Expand the BlackBerry Simulator item. Perform one of the following tasks: • To work with an existing launch configuration, under BlackBerry Simulator, click a launch configuration. • To work with a new launch configuration, right-click BlackBerry Simulator, and click New.

4. 5.

Click the Simulator tab. Click the General tab.

Configuration settings for the BlackBerry Smartphone Simulator Option

Description

Launch Mobile Data System Connection Start the BlackBerry® MDS Connection Service when you start the BlackBerry® Service (MDS-CS) with simulator Smartphone Simulator. You can use the BlackBerry MDS Connection Service to test network applications, push applications, and browser applications. Launch app or URL on start up Specify an application to start or a URL to open when the BlackBerry Smartphone Simulator starts. Device Specify the BlackBerry device model that starts when you run an application. The BlackBerry device models that are available are based on the version of the BlackBerry® Device Software that is currently selected. Automatically use default values for all Select this option to have all options use the default value. prompts In the Specify the number of seconds to wait before the automated response is selected field, type the number of seconds that you want the BlackBerry Smartphone Simulator to wait. PIN Specify the PIN of the BlackBerry Smartphone Simulator. ESN Specify the Electronic Serial Number of the BlackBerry Smartphone Simulator. If unspecified, the number is generated from the PIN. MEID Specify the 14-digit hexadecimal CDMA Mobile Equipment Identifier of the BlackBerry Smartphone Simulator. Enable device security Specify that the BlackBerry Smartphone Simulator simulates a secure connection. System locale Specify the locale of the BlackBerry Smartphone Simulator. Keypad locale Specify the locale of the keyboard on the BlackBerry Smartphone Simulator. The default value is en.

Specify the appearance of the BlackBerry Smartphone Simulator 1.

In Eclipse®, on the Run menu, click Debug Configurations or Run Configurations.

Testing and debugging BlackBerry applications

Development Guide

2. 3.

4. 5.

Click the Simulator tab. Click the View tab.

Settings for the appearance of the BlackBerry Smartphone Simulator Option

Description

Disable automatic backlight shutoff

Specify that the backlighting of the BlackBerry® Smartphone Simulator remains turned on. Specify that the BlackBerry Smartphone Simulator does not display network information. Specify that the BlackBerry Smartphone Simulator displays only the LCD screen. Specify that the BlackBerry Smartphone Simulator displays the LCD screen using a specific zoom level. Specify that the backlighting remains on after the idle timeout period. Specify that help for key mappings is not displayed.

Hide network-specific information Display the LCD only LCD zoom Always keep LCD backlight on Do not show help for key mappings

Specify debugging preferences for the BlackBerry Smartphone Simulator 1. 2. 3.

In Eclipse®, on the Run menu, click Debug Configurations or Run Configurations. Expand the BlackBerry Simulator item. Perform one of the following tasks: • To work with an existing launch configuration, under BlackBerry Simulator, click a launch configuration. • To create a new launch configuration, right-click BlackBerry Simulator, and click New.

4. 5.

Click the Simulator tab. Click the Debugging tab.

Debugging settings for the BlackBerry Smartphone Simulator Option

Description

Interrupt debugger on potential deadlock

Stop the application if the JRE™ detects a thread deadlock.

Testing and debugging BlackBerry applications

Development Guide

Option

Description

Do not stop execution when an exception is caught by catch (Throwable )

Continue running the application when an exception is caught by a catch (Throwable th) block.

Specify network settings for the BlackBerry Smartphone Simulator 1. 2. 3.

4. 5.

Click the Simulator tab. Click the Network tab.

Network settings for the BlackBerry Smartphone Simulator Option

Description

Disable Registration

Prevent the BlackBerry® Smartphone Simulator from registering with the wireless network. Specify a string that describes one of the available networks. Use the following format: "{param}:value;{param}:value". Start the BlackBerry Smartphone Simulator with the wireless transceiver turned off. Specify the phone number of the BlackBerry Smartphone Simulator. Specify that the BlackBerry Smartphone Simulator answers outgoing calls automatically. Specify the International Mobile Equipment Identity of the BlackBerry Smartphone Simulator. Specify the 19 or 20-digit serial number of the simulated SIM card. Specify a 15-digit number to designate the subscriber. Specify that the BlackBerry Smartphone Simulator reports the SIM card as not inserted. For a computer with multiple network interfaces, specify the interface that the BlackBerry Smartphone Simulator uses for network operations.

Network Start with radio off Phone number Automatically answer outgoing calls IMEI ICCID (GPRS) IMSI (GPRS) Simulate SIM not present IP Address

Testing and debugging BlackBerry applications

Development Guide

Option

Description

Ignore UDP port conflicts

Suppress warnings that the BlackBerry Smartphone Simulator produces when it cannot bind to a selected port. Specify the UDP port number that the BlackBerry Smartphone Simulator uses to receive SMS text messages. Specify the UDP port that the BlackBerry Smartphone Simulator uses to send SMS text messages. Specify the PDE port number that the BlackBerry Smartphone Simulator uses for GPS access. This setting is only for BlackBerry devices that operate on the CDMA network.

SMS source port SMS destination port PDE port

Specify ports for the BlackBerry Smartphone Simulator 1. 2. 3.

In Eclipse, on the Run menu, click Debug Configurations or Run Configurations. Expand the BlackBerry Simulator item. Perform one of the following tasks: • To work with an existing launch configuration, under BlackBerry Simulator, click a launch configuration. • To work with a new launch configuration, right-click BlackBerry Simulator, and click New.

4. 5.

Click the Simulator tab. Click the Ports tab.

Port settings for the BlackBerry Smartphone Simulator Option

Description

USB cable connected

Specify that the BlackBerry® Smartphone Simulator is connected to the USB port of a computer. Specify the port number that a Bluetooth® test board is connected to.

Bluetooth test board port

Specify memory settings for theBlackBerry Smartphone Simulator 1. 2. 3.

Testing and debugging BlackBerry applications

Development Guide

4. 5.

Click the Simulator tab. Click the Memory tab.

Memory settings for the BlackBerry Smartphone Simulator Option

Description

Application heap size (bytes)

Specify the amount of RAM on a BlackBerry速 Smartphone Simulator that Java速 can use for all memory allocation. By default, the BlackBerry Smartphone Simulator configures an amount that is based on the BlackBerry Smartphone Simulator type. Branding data Specify the data that the BlackBerry Smartphone Simulator uses for the branding sector of the BlackBerry Smartphone Simulator flash memory. Reset the file system on startup Specify that the BlackBerry Smartphone Simulator deletes file system data when it starts. Reset NVRAM on startup Specify that the BlackBerry Smartphone Simulator deletes system non-volatile storage data when it starts. File system size (bytes) Specify the amount of simulated flash memory that the BlackBerry Smartphone Simulator uses as the file system. The BlackBerry Smartphone Simulator uses an amount that is based on the BlackBerry Smartphone Simulator type. Do not save flash data on simulator exit Specify that the BlackBerry Smartphone Simulator does not save changes to flash memory when it closes. Do not compact file system on exit Specify that the BlackBerry Smartphone Simulator does not compact the file system data when it closes. Simulate no SD Card inserted Specify that the BlackBerry Smartphone Simulator does not create files that represent media card data. Clear SD Card on startup Specify that the BlackBerry Smartphone Simulator creates a new media card file instead of using an existing media card file when starting. SD Card size Specify the size for new media cards that a BlackBerry Smartphone Simulator uses. The default size is 32 MB. SD Card image Specify that the BlackBerry Smartphone Simulator uses an existing media card data file as the media card. Use PC file system for media card files Specify that the BlackBerry Smartphone Simulator uses a folder on the hard disk drive of the computer as the media card.

Testing and debugging BlackBerry applications

Development Guide

Option

Description

PC file system path for media card files

Specify the root folder location of the media card file that the BlackBerry Smartphone Simulator uses. The BlackBerry Smartphone Simulator uses this location when the "Use PC file system for SD Card files" option is selected. The default path is <working directory>/sdcard).

Specify advanced features for the BlackBerry Smartphone Simulator 1. 2. 3.

4. 5.

Click the Simulator tab. Click the Advanced tab.

Advanced settings for the BlackBerry Smartphone Simulator Option

Description

Do not simulate using an authentic RIM Specify that the BlackBerry® Smartphone Simulator identifies the battery as a thirdbattery party battery. Do not use PC numpad as trackball Specify that the BlackBerry Smartphone Simulator does not use the numeric keyboard on the computer to simulate the trackball. Command Line View the command line settings that you can use to start the BlackBerry Smartphone Simulator .

Specify a BlackBerry device for a BlackBerry Smartphone Simulator launch configuration 1. 2. 3.

In Eclipse® , on the Run menu, click Debug Configurations or Run Configurations. Expand the BlackBerry Simulator item. Perform one of the following tasks: • To work with an existing launch configuration, under BlackBerry Simulator, click a launch configuration. • To create a new launch configuration, right-click BlackBerry Simulator, select New.

4. 5.

Click the Simulator tab. Click the General tab.

Development Guide

Testing and debugging BlackBerry applications

In the Device drop-down list, select a BlackBerry® device.

Specify a BlackBerry Smartphone Simulator that is installed outside of the Eclipse environment You can download and install a BlackBerry® Smartphone Simulator that is compatible with the BlackBerry JRE™ of your BlackBerry application project outside of the Eclipse® IDE and use it in the BlackBerry® Java® Plug-in for Eclipse® . To download a BlackBerry Smartphone Simulator installation file, visit www.blackberry.com/developers/resources. 1. 2. 3. 4. 5.

On the Run menu, click Run Configurations or Debug Configurations. Click the configuration that you want to use, or create a new configuration. Click the Simulator Tab. In the Device drop-down list, click a BlackBerry device from the BlackBerry Smartphone Simulator set that you installed. Click Run or Debug.

Run a BlackBerry device application in the BlackBerry Smartphone Simulator The BlackBerry® Smartphone Simulator displays icons on the Home Screen or in the Downloads folder for all BlackBerry device applications that are installed. When you select an icon, the name of the application appears at the bottom of the BlackBerry device screen. 1. In the Package Explorer view, click a project. 2. On the Run menu, click Run As > BlackBerry Simulator. 3.

In the BlackBerry Smartphone Simulator click the application icon.

Testing a BlackBerry device application with the BlackBerry Smartphone Simulator Testing a BlackBerry device application that uses an HTTP connection You can test applications that use an HTTP connection by using the BlackBerry® MDS Connection Service.

Start the BlackBerry MDS Connection Service when you start the BlackBerry Smartphone Simulator 1. 2. 3.

In Eclipse®, on the Run menu, click Debug Configurations or Run Configurations. Expand the BlackBerry Simulator item. Complete one of the following tasks: • To work with an existing launch configuration, under BlackBerry Simulator, click a launch configuration. • To create a new launch configuration, right-click BlackBerry Simulator, select New.

4. 5. 6.

Click the Simulator tab. Click the General tab. Select the Launch Mobile Data System Connection Service (MDS-CS) with simulator check box.

Development Guide

Testing and debugging BlackBerry applications

Click Apply.

Open a web site in the BlackBerry Browser when the BlackBerry Smartphone Simulator starts 1. 2. 3.

4. 5. 6. 7. 8. 9.

Click the Simulator tab. Click the General tab. Select the Launch Mobile Data System Connection Service (MDS-CS) with simulator check box. In the Launch app or URL on startup field, type the web address. Click Close. Click Yes.

Start a BlackBerry device application when the BlackBerry Smartphone Simulator starts 1.

In Eclipse®, on the Run menu, click Debug Configurations or Run Configurations.

Perform one of the following tasks: • To work with an existing launch configuration, under BlackBerry Simulator, click a launch configuration. • To create a new launch configuration, right-click BlackBerry Simulator, select New.

3. 4. 5. 6. 7.

Click the Simulator tab. Click the General tab. In the Launch app or URL on startup field, type the name of the .cod file of the application. Click Close. Click Yes.

View output from the BlackBerry Smartphone Simulator 1. 2. 3.

In Eclipse®, on the Window menu, click Show View > Console. In the Console view, select Display Selected Console. From the console drop-down list, click BlackBerry Simulator Console Output.

Add a BlackBerry device application to the BlackBerry Smartphone Simulator launch configuration 1.

On the Run menu, click Debug Configurations or Run Configurations.

Development Guide

Testing and debugging BlackBerry applications

2. 3.

Expand the BlackBerry Simulator item. Perform one of the following tasks: • To work with an existing configuration, under BlackBerry Simulator, click a configuration. • To create a new configuration, right-click BlackBerry Simulator, and click New.

4. 5. 6. 7.

Click the Projects tab. Click the BlackBerry® device application that you want to add. Click Close. Click Yes.

Debug a BlackBerry device application on a BlackBerry Smartphone Simulator that is running 1. 2. 3. 4.

On the Run menu, click Debug Configurations. Right-click Running BlackBerry Simulator, and click New. In the Name field, type a name. Click Debug.

Add a .jar file, that was created without using RAPC, to the BlackBerry Smartphone Simulator or a BlackBerry device When your BlackBerry® application project imports a .jar file that was created without using RAPC, you can add the .class files to your BlackBerry application project and install the .class files in the BlackBerry® Smartphone Simulator or on a BlackBerry device. 1. In the Package Explorer view, right-click a BlackBerry application project. 2. Click Properties. 3. Click Java Build Path. 4. On the Libraries tab, click Add JARs or Add External JARs. 5. Navigate to the .jar file that you want to add, and click Open. 6. On the Order and Export tab, select the .jar file and click OK. 7. Package the BlackBerry application project and run the application in the BlackBerry Smartphone Simulator. The .class files are zipped into the .cod file of the BlackBerry application project and installed on the BlackBerry Smartphone Simulator.

Run a MIDlet application in the BlackBerry Smartphone Simulator You can import a MIDlet .jar file into a BlackBerry® application project and run the MIDlet application in the BlackBerry® Smartphone Simulator. You can import only one MIDlet .jar file into the BlackBerry application project. You must manually add any dependent library (.cod) files to the BlackBerry Smartphone Simulator. Before you begin:

Development Guide

Testing and debugging BlackBerry applications

You must have a .jad and .jar file pair to add to the BlackBerry application project. 1. 2. 3. 4. 5. 6. 7. 8.

Create a new BlackBerry application project, and add the .jad and .jar files to the project. Do not place the files in a source folder. In the Package Explorer view, right-click the BlackBerry application project. Click Properties. Click Java Build Path. On the Libraries tab, click Add JARs or Add External JARs. Navigate to the MIDlet .jar file that you want to add and click Open. On the Order and Export tab, select the MIDlet .jar file and click OK. Package the BlackBerry application project and run the application in the BlackBerry Smartphone Simulator. The .class files are zipped into the .cod file of the BlackBerry application project and added to the BlackBerry Smartphone Simulator.

Reload a BlackBerry device application without restarting the BlackBerry Smartphone Simulator Before you begin: You must install the BlackBerry® Java® SDK 5.0 or later on your computer. 1. 2.

In Eclipse® right-click a BlackBerry device application. Complete one of the following tasks: • Click Run As > BlackBerry Simulator. • Click Debug As > BlackBerry Simulator.

3. 4. 5.

In the BlackBerry® Smartphone Simulator, click the icon to run the application. In Eclipse, make changes to the application that is running. Save the changes. Complete one of the following tasks: • On the Run menu, clickRun As > BlackBerry Simulator. • On the Run menu, click Debug As > BlackBerry Simulator. The changes to the BlackBerry device application appear in the BlackBerry Smartphone Simulator.

Restore the default settings for the BlackBerry Smartphone Simulator 1. 2. 3. 4.

On the Project menu, click BlackBerry > Clean Simulator. Expand the BlackBerry® JRE™ that you want to restore the default settings for. Select the appropriate check boxes. Click OK.

Development Guide

Testing and debugging BlackBerry applications

Set preferences for running a BlackBerry device application in debug mode 1. 2. 3. 4. 5. 6.

On the Window menu, click Preferences. Expand BlackBerry Java Plug-in. Click Debug. In the Warning section, select the Prompt for missing debug files check box if you want to be notified about missing files. Click Apply. Click OK.

Test a BlackBerry device application on a BlackBerry device You can use a command line tool called Javaloader.exe to install and remove a BlackBerry® device application on a BlackBerry device using a USB connection without using descriptor files or web pages. Javaloader.exe can be useful when you install or remove a BlackBerry device application frequently during testing and development. 1. Connect the BlackBerry device to the computer. 2. At a command prompt, navigate to the following folder: C:\Program Files\Eclipse\plugins\net.rim.ejde.componentpackx.x.x_x.x.x.x\components\bin 3. Type javaloader to view the syntax of the tool.

Debug a BlackBerry device application on a BlackBerry device 1. 2. 3. 4. 5. 6. 7. 8.

Connect the BlackBerry® device to your computer using a USB cable. Open the BlackBerry® Device Manager. Install the application on the BlackBerry device. In Eclipse®, on the Run menu, click Debug Configurations. Right-click BlackBerry Device, and click New. In the Name field, type a name. Click the BlackBerry Device tab. In the BlackBerry Device configuration section, perform one of the following actions: • Select Attach to any connected to attach to any BlackBerry device that is connected. • Select Attach to specific device. Select a BlackBerry device from the Attach to BlackBerry Device drop-down list.

Click Debug.

Testing and debugging BlackBerry applications

Development Guide

Making BlackBerry device applications available to BlackBerry device users Packaging a BlackBerry application project for multiple versions of BlackBerry Device Software You can create a BlackBerry® device application that is compatible with multiple versions of the BlackBerry® Device Software. When you package your BlackBerry application project (and it's dependent projects) for multiple versions of the BlackBerry Device Software, the BlackBerry® Java® Plug-in for Eclipse® creates the application files for distribution to BlackBerry device users that run the versions of the BlackBerry Device Software that you include in your BlackBerry application project. When you distribute your BlackBerry device application by using the BlackBerry® Desktop Software or the BlackBerry® Enterprise Server push service, the BlackBerry Java Plug-in for Eclipse creates one master .alx file in the Standard folder of your BlackBerry application project. When you distribute your BlackBerry device application over the Internet, the BlackBerry Java Plug-in for Eclipse creates the .jad and .cod files for each version of the BlackBerry Device Software in the Web folder of your BlackBerry application project. You can use the auto-signature feature in the BlackBerry® Java® Plug-in for Eclipse® to sign the .cod files automatically after you package a BlackBerry application project.

Packaging output for BlackBerry application projects Location

File extension

Description

<project-dir>/deliverables/ Standard/

.alx

You can use this file to install a BlackBerry device application on a BlackBerry device by using the BlackBerry Device Software or the BlackBerry® Enterprise Server. When you package a BlackBerry application project for multiple versions of the BlackBerry® Device Software, this file contains all the application files.

<project-dir>/deliverables/ Standard/<x.x.x>

.cod

You can configure the .alx file name on the Build tab of the BlackBerry_App_descriptor.xml file editor. This file is the executable file for the BlackBerry device application.

where "x.x.x" represents the version of the BlackBerry® Java® SDK .csi

This log file is created when you sign the .cod files in your BlackBerry device application.

Testing and debugging BlackBerry applications

Development Guide

Location

<project-dir>/deliverables/ Web <project-dir>/deliverables/ Web/<x.x.x>

File extension

Description

.cso .debug .jad .jar

This log file contains the signature keys that are available. This file permits you to debug a BlackBerry device application. This file describes the application that is contained in the .jar file. This file is the application archive file that you can use to distribute your BlackBerry device application. This file is necessary for packaging your BlackBerry device application. The files in this location are generated only when packaging is invoked explicitly. They are intended for sharing with or copying to a deployment system. This file is the executable file for the BlackBerry device application.

.rapc —

.cod

where "x.x.x" represents the version of the BlackBerry Java SDK x.cod .csi .cso .debug .jad .jar .rapc

This file is created when a large .cod file is split into one or more sibling .cod files (for example 1.cod, 2.cod, and so on). This log file is created when you sign the .cod files in your BlackBerry device application. This log file contains the signature keys that are available. This file permits you to debug a BlackBerry device application. This file describes the application that is contained in the .jar file. This file is the application archive file that you can use to distribute your BlackBerry device application. This file is necessary for packaging your BlackBerry device application.

Distributing a BlackBerry device application from a web page You can use the BlackBerry® Application Web Loader to allow BlackBerry device users to install a BlackBerry device application from a web page. When you package the project by using the BlackBerry® Java® Plug-in for Eclipse® , you can distribute the .jad and .the cod files that are located in the deliverables folder of the project. When BlackBerry device users use Windows® Internet Explorer® to visit the web page that hosts the .jad and the .cod files, they are asked to connect their BlackBerry device to the USB port on their computer. A Microsoft® ActiveX® control installs the BlackBerry device application . For more information about using the BlackBerry Application Web Loader, see the BlackBerry Application Web Loader Development Guide .

Development Guide

Troubleshooting

Distribute a BlackBerry device application from the BlackBerry Desktop Manager In the BlackBerry® Desktop Manager, you can use the application loader tool to allow BlackBerry device users to download a BlackBerry device application onto their computers and install the application on their BlackBerry devices. For more information about how to distribute a BlackBerry device application from the BlackBerry Desktop Manager, see the BlackBerry Java Application - Core - Development Guide . For more information about using .alx files, see the Application Loader Online Help. 1. In the Package Explorer view, expand a BlackBerry device application project. 2. Double-click the BlackBerry_App_Descriptor.xml file. 3. Click the Build tab. 4. Select Generate .alx file (Desktop Deployment / BlackBerry Enterprise Server Push). 5. Distribute the .alx file and the .cod files for the BlackBerry device application to BlackBerry device users.

Turn off .alx generation when you package a BlackBerry application project By default, when you package a BlackBerry® application project, a .alx file is generated automatically to permit you to distribute your BlackBerry device application by using the BlackBerry® Desktop Software or the BlackBerry® Enterprise Server push service. To turn off this feature, complete the following tasks: 1. 2. 3.

In the Package Explorer view, expand a BlackBerry application project. Double-click the BlackBerry_App_Descriptor.xml file. Click the Build tab.

4. 5. 6.

Clear the Generate .alx file (Desktop Deployment / BlackBerry Enterprise Server Push) option. Close the BlackBerry_App_Descriptor.xml file. Click Yes.

Troubleshooting I cannot reload a BlackBerry device application without restarting the BlackBerry Smartphone Simulator or resetting the BlackBerry device Possible Cause You might be required to restart the BlackBerry Smartphone Simulator or reset the BlackBerry device when you try to reload your BlackBerry device application when you use versions of the BlackBerry® Java® SDK earlier than 5.0.0.18 or versions of the BlackBerry® Device Software earlier than 5.0.0.469. When you make changes to your code while you run or debug your BlackBerry device application in the BlackBerry Smartphone Simulator or debug it on a BlackBerry device, if a process is running an application and the corresponding .cod file is replaced with an updated version, the BlackBerry Smartphone Simulator stops the process and performs garbage collection on any listeners,

Development Guide

Troubleshooting

class instances, or memory objects that belong to the application. If the structure of a persistent object is not changed, the object is preserved. If an object belongs to an application module that is replaced, and the object cannot be disposed of, a restart of the BlackBerry Smartphone Simulator or a reset of the BlackBerry device might be required.

Possible Solution Install the BlackBerry Java SDK 5.0.0.18 or later on your computer, or install the BlackBerry Device Software 5.0 0.469 or later on the BlackBerry device.

Development Guide

Provide feedback To provide feedback on this deliverable, visit www.blackberry.com/docsfeedback.

Provide feedback

Development Guide

Legal notice

©2010 Research In Motion Limited. All rights reserved. BlackBerry®, RIM®, Research In Motion®, SureType®, SurePress™ and related trademarks, names, and logos are the property of Research In Motion Limited and are registered and/or used in the U.S. and countries around the world. AMD Athlon is a trademark of Advanced Micro Devices, Inc. Eclipse is a trademark of Eclipse Foundation, Inc. Intel and Pentium are trademarks of Intel Corporation. Perforce is a trademark of Perforce Software Incorporated. Java and Sun are trademarks of Sun Microsystems, Inc. Microsoft, Microsoft ActiveX, Windows, and Windows Vista are trademarks of Microsoft Corporation. All other trademarks are the property of their respective owners. This documentation including all documentation incorporated by reference herein such as documentation provided or made available at www.blackberry.com/go/docs is provided or made accessible "AS IS" and "AS AVAILABLE" and without condition, endorsement, guarantee, representation, or warranty of any kind by Research In Motion Limited and its affiliated companies ("RIM") and RIM assumes no responsibility for any typographical, technical, or other inaccuracies, errors, or omissions in this documentation. In order to protect RIM proprietary and confidential information and/or trade secrets, this documentation may describe some aspects of RIM technology in generalized terms. RIM reserves the right to periodically change information that is contained in this documentation; however, RIM makes no commitment to provide any such changes, updates, enhancements, or other additions to this documentation to you in a timely manner or at all. This documentation might contain references to third-party sources of information, hardware or software, products or services including components and content such as content protected by copyright and/or third-party web sites (collectively the "Third Party Products and Services"). RIM does not control, and is not responsible for, any Third Party Products and Services including, without limitation the content, accuracy, copyright compliance, compatibility, performance, trustworthiness, legality, decency, links, or any other aspect of Third Party Products and Services. The inclusion of a reference to Third Party Products and Services in this documentation does not imply endorsement by RIM of the Third Party Products and Services or the third party in any way. EXCEPT TO THE EXTENT SPECIFICALLY PROHIBITED BY APPLICABLE LAW IN YOUR JURISDICTION, ALL CONDITIONS, ENDORSEMENTS, GUARANTEES, REPRESENTATIONS, OR WARRANTIES OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING WITHOUT LIMITATION, ANY CONDITIONS, ENDORSEMENTS, GUARANTEES, REPRESENTATIONS OR WARRANTIES OF DURABILITY, FITNESS FOR A PARTICULAR PURPOSE OR USE, MERCHANTABILITY, MERCHANTABLE QUALITY, NONINFRINGEMENT, SATISFACTORY QUALITY, OR TITLE, OR ARISING FROM A STATUTE OR CUSTOM OR A COURSE OF DEALING OR USAGE OF TRADE, OR RELATED TO THE DOCUMENTATION OR ITS USE, OR PERFORMANCE OR NON-PERFORMANCE OF ANY SOFTWARE, HARDWARE, SERVICE, OR ANY THIRD PARTY PRODUCTS AND SERVICES REFERENCED HEREIN, ARE HEREBY EXCLUDED. YOU MAY ALSO HAVE OTHER RIGHTS THAT VARY BY STATE OR PROVINCE. SOME JURISDICTIONS MAY NOT ALLOW THE EXCLUSION OR LIMITATION OF IMPLIED WARRANTIES AND CONDITIONS. TO THE EXTENT PERMITTED BY LAW, ANY IMPLIED WARRANTIES OR CONDITIONS RELATING TO THE DOCUMENTATION TO THE EXTENT THEY CANNOT BE EXCLUDED AS SET OUT ABOVE, BUT CAN BE LIMITED, ARE HEREBY LIMITED TO NINETY (90) DAYS FROM THE DATE YOU FIRST ACQUIRED THE DOCUMENTATION OR THE ITEM THAT IS THE SUBJECT OF THE CLAIM. TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW IN YOUR JURISDICTION, IN NO EVENT SHALL RIM BE LIABLE FOR ANY TYPE OF DAMAGES RELATED TO THIS DOCUMENTATION OR ITS USE, OR PERFORMANCE OR NONPERFORMANCE OF ANY SOFTWARE, HARDWARE, SERVICE, OR ANY THIRD PARTY PRODUCTS AND SERVICES REFERENCED HEREIN INCLUDING WITHOUT LIMITATION ANY OF THE FOLLOWING DAMAGES: DIRECT, CONSEQUENTIAL, EXEMPLARY,

Development Guide

Legal notice

INCIDENTAL, INDIRECT, SPECIAL, PUNITIVE, OR AGGRAVATED DAMAGES, DAMAGES FOR LOSS OF PROFITS OR REVENUES, FAILURE TO REALIZE ANY EXPECTED SAVINGS, BUSINESS INTERRUPTION, LOSS OF BUSINESS INFORMATION, LOSS OF BUSINESS OPPORTUNITY, OR CORRUPTION OR LOSS OF DATA, FAILURES TO TRANSMIT OR RECEIVE ANY DATA, PROBLEMS ASSOCIATED WITH ANY APPLICATIONS USED IN CONJUNCTION WITH RIM PRODUCTS OR SERVICES, DOWNTIME COSTS, LOSS OF THE USE OF RIM PRODUCTS OR SERVICES OR ANY PORTION THEREOF OR OF ANY AIRTIME SERVICES, COST OF SUBSTITUTE GOODS, COSTS OF COVER, FACILITIES OR SERVICES, COST OF CAPITAL, OR OTHER SIMILAR PECUNIARY LOSSES, WHETHER OR NOT SUCH DAMAGES WERE FORESEEN OR UNFORESEEN, AND EVEN IF RIM HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW IN YOUR JURISDICTION, RIM SHALL HAVE NO OTHER OBLIGATION, DUTY, OR LIABILITY WHATSOEVER IN CONTRACT, TORT, OR OTHERWISE TO YOU INCLUDING ANY LIABILITY FOR NEGLIGENCE OR STRICT LIABILITY. THE LIMITATIONS, EXCLUSIONS, AND DISCLAIMERS HEREIN SHALL APPLY: (A) IRRESPECTIVE OF THE NATURE OF THE CAUSE OF ACTION, DEMAND, OR ACTION BY YOU INCLUDING BUT NOT LIMITED TO BREACH OF CONTRACT, NEGLIGENCE, TORT, STRICT LIABILITY OR ANY OTHER LEGAL THEORY AND SHALL SURVIVE A FUNDAMENTAL BREACH OR BREACHES OR THE FAILURE OF THE ESSENTIAL PURPOSE OF THIS AGREEMENT OR OF ANY REMEDY CONTAINED HEREIN; AND (B) TO RIM AND ITS AFFILIATED COMPANIES, THEIR SUCCESSORS, ASSIGNS, AGENTS, SUPPLIERS (INCLUDING AIRTIME SERVICE PROVIDERS), AUTHORIZED RIM DISTRIBUTORS (ALSO INCLUDING AIRTIME SERVICE PROVIDERS) AND THEIR RESPECTIVE DIRECTORS, EMPLOYEES, AND INDEPENDENT CONTRACTORS. IN ADDITION TO THE LIMITATIONS AND EXCLUSIONS SET OUT ABOVE, IN NO EVENT SHALL ANY DIRECTOR, EMPLOYEE, AGENT, DISTRIBUTOR, SUPPLIER, INDEPENDENT CONTRACTOR OF RIM OR ANY AFFILIATES OF RIM HAVE ANY LIABILITY ARISING FROM OR RELATED TO THE DOCUMENTATION. Prior to subscribing for, installing, or using any Third Party Products and Services, it is your responsibility to ensure that your airtime service provider has agreed to support all of their features. Some airtime service providers might not offer Internet browsing functionality with a subscription to the BlackBerry速 Internet Service. Check with your service provider for availability, roaming arrangements, service plans and features. Installation or use of Third Party Products and Services with RIM's products and services may require one or more patent, trademark, copyright, or other licenses in order to avoid infringement or violation of third party rights. You are solely responsible for determining whether to use Third Party Products and Services and if any third party licenses are required to do so. If required you are responsible for acquiring them. You should not install or use Third Party Products and Services until all necessary licenses have been acquired. Any Third Party Products and Services that are provided with RIM's products and services are provided as a convenience to you and are provided "AS IS" with no express or implied conditions, endorsements, guarantees, representations, or warranties of any kind by RIM and RIM assumes no liability whatsoever, in relation thereto. Your use of Third Party Products and Services shall be governed by and subject to you agreeing to the terms of separate licenses and other agreements applicable thereto with third parties, except to the extent expressly covered by a license or other agreement with RIM. Certain features outlined in this documentation require a minimum version of BlackBerry速 Enterprise Server, BlackBerry速 Desktop Software, and/or BlackBerry速 Device Software.

Development Guide

Legal notice

The terms of use of any RIM product or service are set out in a separate license or other agreement with RIM applicable thereto. NOTHING IN THIS DOCUMENTATION IS INTENDED TO SUPERSEDE ANY EXPRESS WRITTEN AGREEMENTS OR WARRANTIES PROVIDED BY RIM FOR PORTIONS OF ANY RIM PRODUCT OR SERVICE OTHER THAN THIS DOCUMENTATION. Research In Motion Limited 295 Phillip Street Waterloo, ON N2L 3W8 Canada Research In Motion UK Limited Centrum House 36 Station Road Egham, Surrey TW20 9LF United Kingdom Published in Canada